Hyperliquid API: a beginner's guide

Hyperliquid runs an exchange on its own blockchain, and almost everything the exchange knows is readable through one public HTTP endpoint. No account, no key and no SDK is needed to read it. This guide walks through the six requests most people start with, using curl. Every response below is real, from mainnet at about 20:44 UTC on 4 November 2026, cut down with … where it was long.

New to the exchange itself? Read what Hyperliquid is and how HyperCore and HyperEVM differ first. The developer hub lists the rest of the API surface.

The two endpoints

Both live on https://api.hyperliquid.xyz.

Endpoint	What it does	Auth
POST /info	Reads: markets, prices, books, candles, funding, any address’s positions, orders and fills	None
POST /exchange	Actions: place, cancel and modify orders, transfers, withdrawals, approvals	Signed by your wallet or an API wallet

Both take a JSON body with Content-Type: application/json. The body’s type field picks the request. Testnet uses the same paths on https://api.hyperliquid-testnet.xyz (docs). For live streams instead of polling, use the WebSocket API.

Two conventions save confusion later:

• Numbers come back as strings ("80112.5"), so they don’t lose precision. Parse them yourself.
• Times are Unix milliseconds (1793825061957 is 2026-11-04 20:44:21 UTC).

1. meta: every perp market

meta returns the list of perpetual markets (the “universe”), each market’s size decimals and maximum leverage.

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"meta"}'

{
  "universe": [
    {"szDecimals":5,"name":"BTC","maxLeverage":40,"marginTableId":56},
    {"szDecimals":4,"name":"ETH","maxLeverage":25,"marginTableId":55},
    {"szDecimals":2,"name":"ATOM","maxLeverage":5,"marginTableId":5},
    …
    {"szDecimals":1,"name":"MATIC","maxLeverage":20,
     "marginTableId":20,"isDelisted":true},
    …
  ],
  "marginTables": [[50,{"description":"","marginTiers":[…]}], …],
  "collateralToken": 0
}

On 4 November 2026 the universe had 235 entries, 56 flagged isDelisted, so 179 live markets. Two things to know:

• A market’s position in this list is its asset ID. BTC is 0, ETH is 1. Orders sent to the exchange endpoint use that number, not the name (asset IDs).
• Delisted markets stay in the list. Filter on isDelisted before you count or display anything.

HIP-3 markets, which outside teams deploy (stocks, oil, gold; see HIP-3), live on separate perp dexes. Pass the dex name: {"type":"meta","dex":"xyz"} returned 142 trade.xyz markets with names such as xyz:XYZ100 and xyz:TSLA. {"type":"perpDexs"} lists every dex. Their asset IDs are 100000 + dex_index × 10000 + index_in_meta.

If you also want mark price, funding and open interest, ask for metaAndAssetCtxs instead. It returns the same universe plus one context object per market:

{"funding":"-0.0000023278","openInterest":"39639.819",
 "prevDayPx":"77791.0","dayNtlVlm":"5456971415.73…",
 "oraclePx":"80092.0","markPx":"80049.0","midPx":"80042.5", …}

That was BTC: about $5.46B of 24-hour volume and 39,640 BTC of open interest.

2. allMids: every mid price

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"allMids"}'

{"BTC":"80112.5","ETH":"2417.75","HYPE":"83.6145", …,
 "@107":"83.6445","PURR/USDC":"0.117825", …}

That response had 1,423 keys. Plain names (BTC) are perps. Spot pairs appear as @<index>, the pair’s index in spotMeta: @107 is HYPE/USDC, whose base is token 150, the real HYPE. The docs note that when a book is empty the “mid” falls back to the last trade price (info endpoint), so check l2Book before you trust a mid on a thin market. HYPE has more than one spot pair, so we use the perp mark for “the HYPE price” (HYPE price).

3. l2Book: the order book

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"l2Book","coin":"BTC"}'

{
  "coin": "BTC",
  "time": 1793825061957,
  "levels": [
    [{"px":"80112.0","sz":"7.06955","n":33},
     {"px":"80111.0","sz":"1.38308","n":6}, …],
    [{"px":"80113.0","sz":"4.96285","n":9},
     {"px":"80114.0","sz":"0.82774","n":2}, …]
  ]
}

levels[0] is bids, best first, and levels[1] is asks. sz is the size in coins at that price and n is how many orders make it up. The response holds at most 20 levels per side. Add "nSigFigs": 2–5 to group prices into wider buckets (docs). For a spot book, use the @index name, e.g. "coin":"@107".

4. clearinghouseState: any address’s positions

Every Hyperliquid account is public. clearinghouseState returns an address’s perp positions and margin. The example uses HLP Strategy A (0x0104…703a), one of the sub-vaults of Hyperliquid’s own HLP vault.

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"clearinghouseState",
       "user":"0x010461c14e146ac35fe42271bdc1134ee31c703a"}'

{
  "marginSummary": {"accountValue":"3050274.582862",
    "totalNtlPos":"3510572.443996","totalRawUsd":"3400239.32204",
    "totalMarginUsed":"175528.622146"},
  "withdrawable": "2699217.338505",
  "assetPositions": [
    {"type":"oneWay","position":{
      "coin":"BTC","szi":"0.01789",
      "leverage":{"type":"cross","value":20},
      "entryPx":"80141.4","positionValue":"1433.27524",
      "unrealizedPnl":"-0.454884","liquidationPx":null,
      "marginUsed":"71.663762", …}},
    …
  ],
  "time": 1793825085023
}

That vault held 177 positions. szi is the signed size: positive is long, negative is short. A liquidationPx of null means the account has enough margin that the position has no liquidation price.

Three traps:

• Use the account’s address, not an API wallet’s. Querying an agent key returns an empty account (docs).
• HIP-3 positions are per dex. Add "dex":"xyz" to see trade.xyz positions.
• Unified or portfolio-margin accounts should read spotClearinghouseState for the trading balance, per the perpetuals docs.

To see this for your own address without writing code, paste it into the wallet checker.

5. candleSnapshot: OHLC candles

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"candleSnapshot","req":{"coin":"BTC",
       "interval":"1h","startTime":1793814270978}}'

[
  {"t":1793811600000,"T":1793815199999,"s":"BTC","i":"1h",
   "o":"80475.0","c":"80382.0","h":"80500.0","l":"80188.0",
   "v":"1337.39062","n":14775},
  …
  {"t":1793822400000,"T":1793825999999,"s":"BTC","i":"1h",
   "o":"79949.0","c":"80113.0","h":"80305.0","l":"79904.0",
   "v":"846.95889","n":8766}
]

t and T are the candle’s open and close times, v is volume in coins and n the number of trades. The last candle is still forming. Supported intervals run from 1m to 1M. Only the most recent 5,000 candles of each interval are available, so 1-minute history goes back about 3.5 days (docs). Add endTime to bound the window.

6. fundingHistory: hourly funding rates

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"fundingHistory","coin":"ETH",
       "startTime":1793814270978}'

[
  {"coin":"ETH","fundingRate":"0.0000125",
   "premium":"-0.0003462684","time":1793815200030},
  {"coin":"ETH","fundingRate":"0.0000125",
   "premium":"-0.00035548","time":1793818800073},
  {"coin":"ETH","fundingRate":"0.0000125",
   "premium":"-0.0003042539","time":1793822400019}
]

Hyperliquid pays funding every hour. 0.0000125 is 0.00125% per hour, which is 0.01% per 8 hours. A positive rate means longs pay shorts (how funding works).

Requests that take a time range return at most 500 items. To go further back, send the last returned time as the next startTime and repeat (pagination). Each 20 items returned also adds to the request’s rate-limit weight. Our funding dataset already does this for every market, if you’d rather download a file.

Other info requests worth knowing

type	Returns
spotMeta	Spot tokens and pairs (349 pairs, 511 tokens on 4 Nov 2026)
perpDexs	Every perp dex, core first, then the HIP-3 dexes (11 entries)
openOrders / frontendOpenOrders	An address’s resting orders
userFills / userFillsByTime	An address’s trade history
userFunding	Funding an address paid or received
orderStatus	One order by oid or client ID
vaultDetails	A vault’s leader, followers, history and sub-vaults
userRateLimit	How much of an address’s request budget is used
maxBuilderFee / approvedBuilders	An address’s builder-code approvals
outcomeMeta	HIP-4 outcome markets

The full list, with response schemas, is on the info endpoint page of the docs.

Rate limits in one paragraph

Each IP address has a budget of 1,200 weight per minute for HTTP requests. l2Book, allMids, clearinghouseState, orderStatus, spotClearinghouseState and exchangeStatus cost 2. userRole costs 60. Every other documented info request costs 20, and history requests add weight for every 20 items they return (every 60 for candles). An unbatched exchange action costs 1 (rate limits). In practice, about 600 allMids polls a minute, or 60 polls of a weight-20 request. If you need more than that, switch to the WebSocket. The developer hub has the full table, including the per-address limits on trading.

When a request fails

What we saw on 4 November 2026:

• An unknown type returns HTTP 422 with the plain-text body Failed to deserialize the JSON body into the target type. A typo in a field name does the same.
• l2Book for a coin that doesn’t exist returned HTTP 500 with the body null.

If requests start failing during a burst, you are probably over the rate limit: slow down and retry with a backoff rather than in a tight loop.

The exchange endpoint: use an SDK

Orders, cancels, transfers and withdrawals go to POST /exchange. Each one must be signed, and the signing scheme is easy to get subtly wrong: field order matters, trailing zeros matter and addresses should be lowercase. A bad signature doesn’t fail loudly. It recovers a different signer, so you see errors like User or API Wallet 0x… does not exist (signing). Hyperliquid’s own advice is to use an SDK. The hub lists them.

# ILLUSTRATIVE ONLY: testnet, API-wallet key from the environment.
# pip install hyperliquid-python-sdk
import os
import eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants

agent = eth_account.Account.from_key(os.environ["HL_AGENT_KEY"])
ex = Exchange(agent, constants.TESTNET_API_URL,
              account_address=os.environ["HL_ACCOUNT"])

# A resting limit order far from the market; cancel it after.
res = ex.order("ETH", True, 0.01, 1000, {"limit": {"tif": "Gtc"}})
print(res)

Perps are leveraged, and a bug in a bot can lose real money fast. Test on testnet first. The testnet faucet gives 1,000 mock USDC, but only to addresses that have already deposited on mainnet (testnet faucet). Hyperliquid’s terms restrict users in the United States, Ontario and other places (availability). That applies to API users too.

Where to go next

• Stream instead of poll: WebSocket API
• Let a server trade without your main key: API wallets
• Smart contracts on Hyperliquid: HyperEVM RPC and chain settings
• Charge a fee on orders your app sends: builder codes for developers
• Don’t want to call the API yourself? Download our free datasets or plug an AI agent into our MCP server.