hyperliquid-info
Cursor / Agent Plugin wrapping Hyperliquid’s public Info API (POST /info).
Read-only. No /exchange, no private keys, no order placement.
Docs: Info endpoint · Perpetuals · Spot
Domain types
| Type | Meaning |
|---|---|
MidMap | coin → mid price string |
L2Book | { coin, time, levels: [bids, asks] } |
RecentTrade | { coin, side, px, sz, time, tid, users } |
AssetMeta / SpotMeta | universe + margin / tokens + spot pairs |
AssetCtx / SpotAssetCtx | mark / oracle / funding / OI / day volume |
ClearinghouseState | margin + positions for a user |
SpotClearinghouseState | spot balances (balances[]) |
OpenOrder / FrontendOpenOrder / UserFill / Candle / FundingRate | as named |
Portfolio | day/week/month/allTime (+ perp*) PnL & accountValue histories |
UserFees | fee schedule + user rates + staking/referral discounts |
VaultDetails / UserVaultEquity | vault APR, followers, equity |
DelegatorSummary / ValidatorSummary | staking state |
BorrowLendReserveState | supply/borrow rates & utilization |
OutcomeMeta / SettledOutcome | HIP-4 outcome markets |
Install (Cursor IDE)
- Clone this repo (or copy the folder).
- Copy into a real directory:
~/.cursor/plugins/local/hyperliquid-info - Reload Window / enable local plugins if your org gates imports.
Install (Claude Code)
Clone this repo, then start Claude Code with claude --plugin-dir /path/to/hyperliquid-plugin. .claude-plugin/plugin.json loads the skill and starts the MCP server with node ${CLAUDE_PLUGIN_ROOT}/server/index.mjs. The server has no dependencies, so it needs only Node on PATH and no npm install.
For testnet, export HYPERLIQUID_API_URL before you launch Claude Code.
MCP tools (59)
Every tool is read-only and returns compact JSON as text. List tools return a page: { total, returned, offset, next_offset, truncated, items }, with limit (default 50, max 500) and offset inputs. Market tables also take coins (e.g. ["BTC","ETH"]). No result is larger than 40,000 characters; anything bigger asks you to narrow the request. Upstream errors come back as tool errors (isError) with the HTTP reason and a hint. Each request times out after 15 s (HYPERLIQUID_TIMEOUT_MS).
Market / meta
| Tool | Returns |
|---|---|
get_all_mids | MidMap (coins to filter) |
get_l2_book | L2Book (coin) |
get_recent_trades | RecentTrade[] (coin) |
get_meta | perp universe + margin tables |
get_meta_and_asset_ctxs | one row per perp: meta + mark / funding / OI / volume (coins) |
get_all_perp_metas | metas across all perp dexs (HIP-3) |
get_perp_dexs | builder-deployed dex list |
get_perp_dex_limits | OI / transfer caps (dex required) |
get_perp_dex_status | net deposits etc. |
get_perps_at_open_interest_cap | coins at OI cap |
get_perp_deploy_auction_status | perp deploy auction |
get_perp_annotation | category/description (coin) |
get_perp_categories | [[coin, category], …] |
get_perp_concise_annotations | concise annotations |
get_margin_table | margin tiers by id |
get_candles | OHLCV (coin, interval; default last 100 bars, max 200) |
get_funding_history | historical funding (coin; default last 24h) |
get_predicted_fundings | cross-venue predicted funding |
get_exchange_status | specialStatuses + time |
Spot / outcomes / borrow-lend
| Tool | Returns |
|---|---|
get_spot_meta | spot pairs with base/quote token names and ids (coins) |
get_spot_meta_and_asset_ctxs | spot pair rows + mid / mark / volume / supply (coins) |
get_token_details | supply / mid / mark + genesis list counts (tokenId; genesis pages one list) |
get_spot_pair_deploy_auction_status | spot pair auction |
get_spot_deploy_state | deployer auction state (user) |
get_spot_clearinghouse_state | spot balances (user) |
get_outcome_meta | HIP-4 questions, deployers, paged outcomes |
get_settled_outcome | settled outcome (outcome) |
get_all_borrow_lend_reserve_states | all reserve states |
get_borrow_lend_reserve_state | one token (token) |
get_borrow_lend_user_state | user borrow/lend (user) |
User
| Tool | Returns |
|---|---|
get_clearinghouse_state | perp account (user) |
get_open_orders | resting orders (user) |
get_frontend_open_orders | orders + trigger/TP-SL fields |
get_historical_orders | recent historical orders |
get_user_fills | recent fills |
get_user_fills_by_time | fills by time range |
get_user_funding | funding payments ledger |
get_user_non_funding_ledger_updates | deposits/transfers/withdrawals |
get_user_twap_slice_fills | TWAP slice fills |
get_order_status | status by oid / cloid |
get_active_asset_data | leverage / trade sizes (user, coin) |
get_user_rate_limit | request / volume caps |
get_user_role | user / agent / vault / subAccount |
get_user_fees | fees + schedule |
get_portfolio | portfolio histories (period for one) |
get_sub_accounts | sub-accounts |
get_extra_agents | named API agents |
get_referral | referral / rewards |
get_user_abstraction | abstraction mode |
get_user_dex_abstraction | HIP-3 dex abstraction flag |
get_approved_builders | approved builders |
get_max_builder_fee | max fee (user, builder) |
Vault / staking
| Tool | Returns |
|---|---|
get_vault_details | vault APR / leader / paged followers (vaultAddress; period adds history) |
get_user_vault_equities | vault equities for user |
get_delegations | staking delegations |
get_delegator_summary | delegated / pending |
get_delegator_history | stake events |
get_delegator_rewards | rewards |
get_validator_summaries | validators |
Pass the master/sub-account address for user queries — not an agent wallet.
Network
Default: https://api.hyperliquid.xyz
Testnet: set HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz in the environment. Claude Code passes it through .claude-plugin/plugin.json; for Cursor, add it under env in mcp.json.
Skill
skills/hyperliquid-info/SKILL.md — address and coin conventions, result sizing, and error handling.
Test
npm test runs test/smoke.mjs. It starts the server over stdio and checks initialize, tools/list, argument validation, timeouts and drain-on-close. Then it calls every tool with the args in test/fixtures.json against the live API and checks that each result fits the size cap and is not an error. The live calls are skipped when the API is unreachable or SMOKE_OFFLINE=1 is set. CI runs it on every push and daily (.github/workflows/smoke.yml).
License
MIT