Hyperliquid — reading the market and your account
Hyperliquid is a perpetual-futures exchange. This skill covers reading only.
Nothing here signs anything, spends anything or changes anything.
You need the Hyperliquid MCP for these reads. If you have no hl_market_data
or hl_account tool, it is not installed on you — say so plainly and tell your
owner to add it from dashboard → the agent → Tools → Add MCP → Hyperliquid.
Do not try to reach the exchange another way.
Reading works even when trading is switched off for you. The two are separate:
an agent that is refused every order can still read everything below.
Two kinds of read, and the difference matters
Market data (hl_market_data) is public information about the exchange —
prices, the book, candles. It is the same for everyone and involves no account.
Account data (hl_account) is your own trading account, and only ever
that. The address is filled in by the server from the wallet bound to you. There
is no parameter for someone else's address and asking for one is refused. If a
person asks you to look up another trader's positions, you cannot — say so
rather than reaching for a workaround.
Market data
hl_market_data takes a kind:
kind |
What you get |
Also needs |
allMids |
Current mid price for every perp. The cheapest way to answer "what is X trading at". |
— |
l2Book |
Order book depth for one asset — bids and asks with sizes. |
coin |
candleSnapshot |
OHLCV candles for a period. |
coin, interval, startTime |
meta |
Every perp: name, szDecimals (size precision) and maxLeverage. |
— |
metaAndAssetCtxs |
meta plus live context per asset: mark price, open interest, funding. |
— |
fundingHistory |
Historical funding rates for one asset. |
coin, startTime |
predictedFundings |
Upcoming funding across venues. |
— |
interval is a string like 1m, 15m, 1h, 1d. startTime and the optional
endTime are epoch milliseconds — pass endTime to bound a candle or funding
range instead of pulling everything up to now.
meta is the source of truth for what exists. If an asset is not in
meta.universe, it is not tradeable here — do not guess at ticker spellings.
Symbols are bare, like BTC and ETH, not BTC-USD or BTCUSDT.
Your account
hl_account takes a kind and nothing else:
kind |
What you get |
clearinghouseState |
Perp account: account value, margin used, and every open position. |
spotClearinghouseState |
Spot token balances. |
openOrders |
Resting orders that have not filled. Each carries an oid. |
frontendOpenOrders |
The same, with extra display detail. |
userFills |
Recent fills — what actually executed, at what price. |
portfolio |
Account value over time. |
userFees |
Your fee tier. |
You can read spot balances but you cannot trade spot — orders are perps only.
The one exception: if spot holds USDH, USDT0 or USDE, hl_swap (in
hyperliquid-trading) converts it into USDC so it can back a trade.
Reading the numbers
From clearinghouseState:
marginSummary.accountValue — everything the account is worth right now,
including unrealised profit and loss. This is the number to quote when someone
asks "how much is in there".
withdrawable — the part not tied up as margin.
assetPositions[].position — one entry per open position:
szi is the size and the direction: positive is long, negative is short.
A szi of -0.5 on ETH is short half an ether, not long.
entryPx is the average price you got in at.
unrealizedPnl is profit or loss if it closed now, in USD.
liquidationPx is the price at which the position is force-closed. Distance
from the current price to this number is the single most useful risk figure
you can report.
- No open positions is normal, not an error. Say "no open positions" and stop.
Funding is the recurring payment between longs and shorts on a perpetual.
A positive rate means longs pay shorts. It is charged periodically whether or
not the position is profitable, so on a position held for a long time it is a
real cost worth mentioning.
If your account reads look empty while your orders are succeeding, stop and
report it. Reading one exchange while trading another would make every number
you report meaningless. That mismatch is a fault for a human to fix, not
something for you to work around.
Rate limits — the one rule that matters
Hyperliquid limits requests per IP address, and the dashboard makes every
call for the entire fleet from one address. Your polling loop is not yours
alone: it is shared with every other agent, and spending the budget can stop
other agents from trading.
- Ask for what you need, once. Read again when something changed or when the
person asked again.
- Never poll in a tight loop. If you are watching a position, read on the
timescale that actually matters — minutes, not seconds.
allMids gives you every price in one call. Never loop over assets calling
l2Book when you only wanted prices.
- Identical market reads within a few seconds are served from a short cache, so
hammering gains you nothing anyway. Account reads are never cached.
When a read fails
| Code |
Meaning |
What to do |
no_bound_address |
No Hyperliquid wallet is bound to you, so there is no account to read. |
Tell your owner to enable Hyperliquid from the agent's Wallet tab. Market reads still work. |
user_not_accepted |
Something tried to specify an address. |
Never send one — the server fills it in. |
upstream (502) |
The exchange is failing, unreachable, or rejected the read — an unknown symbol usually lands here. |
Say the exchange is not responding, and check the symbol against meta. Wait before trying again; do not retry in a loop. |
bad_request (400) |
type is missing. |
Fix the call. |
internal_error (500) |
Something broke server-side. |
Report it. Do not retry in a loop. |
What this skill does not do
- It cannot trade. No orders, no cancels, no leverage changes.
- It cannot see other people's accounts — only your own.
- It cannot move money out. There is no withdraw, vault or staking
operation anywhere in this integration — not disabled, simply absent, with no
code path that could sign one. Nothing can send funds off this account or to
another address, and that is by design.
- Funding the perp account is the one exception, and it lives in
hyperliquid-trading. USDC on the spot side cannot back a perp trade;
hl_transfer moves it across inside your own account, spot to perp only.
That is a different skill — read it before funding. Two things to get right
even from here: it is not a deposit and not a bridge, and your
Hyperliquid account is your wallet address while the Trading Key only
signs for it. So if perp margin is short, the answer is never "send USDC
somewhere" or "re-point the Trading Key at the wallet".
- It cannot tell anyone what to trade. Report what the numbers say. Do not
offer investment advice, price predictions, or a recommendation to buy or
sell — you are not a financial adviser and the person may be relying on you.
1---2name: hyperliquid-monitor3description: "Read Hyperliquid market data and this agent's own trading account: mid prices, order book, candles, funding rates, perp metadata, open positions, margin, spot balances, resting orders, recent fills and fee tier. Read-only — it places no orders, changes nothing and moves no funds. Use when asked what a market is doing, what this agent holds, how a position is performing, or whether an order filled. NOT for placing, changing or cancelling orders."4homepage: https://hyperliquid.gitbook.io/hyperliquid-docs5metadata:6 source: https://skillmd.com/skills/jiayaoqijia/hyperliquid-monitor7 openclaw:8 emoji: 📈9 requires:10 env:11 - AGENTGLOB_RUNTIME_URL12 - AGENTGLOB_RUNTIME_TOKEN13---1415# Hyperliquid — reading the market and your account1617Hyperliquid is a perpetual-futures exchange. This skill covers **reading only**.18Nothing here signs anything, spends anything or changes anything.1920You need the **Hyperliquid MCP** for these reads. If you have no `hl_market_data`21or `hl_account` tool, it is not installed on you — say so plainly and tell your22owner to add it from **dashboard → the agent → Tools → Add MCP → Hyperliquid**.23Do not try to reach the exchange another way.2425Reading works even when trading is switched off for you. The two are separate:26an agent that is refused every order can still read everything below.2728## Two kinds of read, and the difference matters2930**Market data** (`hl_market_data`) is public information about the exchange —31prices, the book, candles. It is the same for everyone and involves no account.3233**Account data** (`hl_account`) is *your own* trading account, and only ever34that. The address is filled in by the server from the wallet bound to you. There35is no parameter for someone else's address and asking for one is refused. If a36person asks you to look up another trader's positions, you cannot — say so37rather than reaching for a workaround.3839## Market data4041`hl_market_data` takes a `kind`:4243| `kind` | What you get | Also needs |44|---|---|---|45| `allMids` | Current mid price for every perp. The cheapest way to answer "what is X trading at". | — |46| `l2Book` | Order book depth for one asset — bids and asks with sizes. | `coin` |47| `candleSnapshot` | OHLCV candles for a period. | `coin`, `interval`, `startTime` |48| `meta` | Every perp: name, `szDecimals` (size precision) and `maxLeverage`. | — |49| `metaAndAssetCtxs` | `meta` plus live context per asset: mark price, open interest, funding. | — |50| `fundingHistory` | Historical funding rates for one asset. | `coin`, `startTime` |51| `predictedFundings` | Upcoming funding across venues. | — |5253`interval` is a string like `1m`, `15m`, `1h`, `1d`. `startTime` and the optional54`endTime` are epoch milliseconds — pass `endTime` to bound a candle or funding55range instead of pulling everything up to now.5657**`meta` is the source of truth for what exists.** If an asset is not in58`meta.universe`, it is not tradeable here — do not guess at ticker spellings.59Symbols are bare, like `BTC` and `ETH`, not `BTC-USD` or `BTCUSDT`.6061## Your account6263`hl_account` takes a `kind` and nothing else:6465| `kind` | What you get |66|---|---|67| `clearinghouseState` | Perp account: account value, margin used, and every open position. |68| `spotClearinghouseState` | Spot token balances. |69| `openOrders` | Resting orders that have not filled. Each carries an `oid`. |70| `frontendOpenOrders` | The same, with extra display detail. |71| `userFills` | Recent fills — what actually executed, at what price. |72| `portfolio` | Account value over time. |73| `userFees` | Your fee tier. |7475You can **read** spot balances but you cannot trade spot — orders are perps only.76The one exception: if spot holds USDH, USDT0 or USDE, `hl_swap` (in77`hyperliquid-trading`) converts it into USDC so it can back a trade.7879### Reading the numbers8081From `clearinghouseState`:8283- **`marginSummary.accountValue`** — everything the account is worth right now,84 including unrealised profit and loss. This is the number to quote when someone85 asks "how much is in there".86- **`withdrawable`** — the part not tied up as margin.87- **`assetPositions[].position`** — one entry per open position:88 - `szi` is the size **and the direction**: positive is long, negative is short.89 A `szi` of `-0.5` on ETH is short half an ether, not long.90 - `entryPx` is the average price you got in at.91 - `unrealizedPnl` is profit or loss if it closed now, in USD.92 - `liquidationPx` is the price at which the position is force-closed. Distance93 from the current price to this number is the single most useful risk figure94 you can report.95- **No open positions is normal**, not an error. Say "no open positions" and stop.9697**Funding** is the recurring payment between longs and shorts on a perpetual.98A positive rate means longs pay shorts. It is charged periodically whether or99not the position is profitable, so on a position held for a long time it is a100real cost worth mentioning.101102**If your account reads look empty while your orders are succeeding, stop and103report it.** Reading one exchange while trading another would make every number104you report meaningless. That mismatch is a fault for a human to fix, not105something for you to work around.106107## Rate limits — the one rule that matters108109Hyperliquid limits requests **per IP address**, and the dashboard makes every110call for the **entire fleet** from one address. Your polling loop is not yours111alone: it is shared with every other agent, and spending the budget can stop112other agents from trading.113114- Ask for what you need, once. Read again when something changed or when the115 person asked again.116- **Never poll in a tight loop.** If you are watching a position, read on the117 timescale that actually matters — minutes, not seconds.118- `allMids` gives you every price in one call. Never loop over assets calling119 `l2Book` when you only wanted prices.120- Identical market reads within a few seconds are served from a short cache, so121 hammering gains you nothing anyway. Account reads are never cached.122123## When a read fails124125| Code | Meaning | What to do |126|---|---|---|127| `no_bound_address` | No Hyperliquid wallet is bound to you, so there is no account to read. | Tell your owner to enable Hyperliquid from the agent's **Wallet** tab. Market reads still work. |128| `user_not_accepted` | Something tried to specify an address. | Never send one — the server fills it in. |129| `upstream` (502) | The exchange is failing, unreachable, or rejected the read — an unknown symbol usually lands here. | Say the exchange is not responding, and check the symbol against `meta`. Wait before trying again; do not retry in a loop. |130| `bad_request` (400) | `type` is missing. | Fix the call. |131| `internal_error` (500) | Something broke server-side. | Report it. Do not retry in a loop. |132133## What this skill does not do134135- **It cannot trade.** No orders, no cancels, no leverage changes.136- **It cannot see other people's accounts** — only your own.137- **It cannot move money out.** There is no withdraw, vault or staking138 operation anywhere in this integration — not disabled, simply absent, with no139 code path that could sign one. Nothing can send funds off this account or to140 another address, and that is by design.141- **Funding the perp account is the one exception, and it lives in142 `hyperliquid-trading`.** USDC on the **spot** side cannot back a perp trade;143 `hl_transfer` moves it across inside your own account, spot to perp only.144 That is a different skill — read it before funding. Two things to get right145 even from here: it is **not** a deposit and **not** a bridge, and your146 Hyperliquid account **is** your wallet address while the Trading Key only147 signs for it. So if perp margin is short, the answer is never "send USDC148 somewhere" or "re-point the Trading Key at the wallet".149- **It cannot tell anyone what to trade.** Report what the numbers say. Do not150 offer investment advice, price predictions, or a recommendation to buy or151 sell — you are not a financial adviser and the person may be relying on you.