Hyperliquid API guide

Contents

This guide is for developers and traders writing bots, dashboards or apps against Hyperliquid. Every endpoint, number and payload below comes from Hyperliquid's developer documentation as of 2 November 2026. The request and response examples are copied from those docs; we did not run them for this guide. Where we describe what we hit in our own integration, the text says so. For the chain itself, start with what Hyperliquid is and how it works.

How does the Hyperliquid API work?#

Hyperliquid runs API servers that follow a node, keep the chain state in memory and forward your transactions. Hyperliquid's API servers page says a server sends your signed transaction to its node, the node gossips it into HyperBFT consensus, and the server replies only after the transaction is in a committed block. An exchange response is the execution result on the L1, not a receipt for a queued request.

The API overview page gives both base URLs. The notation page warns that this is the "v0" API with nonstandard short names: px is price, sz is size in the base coin, szi is signed size, ntl is notional, side B is bid and A is ask. Hyperliquid says a future v1 will standardize them in one breaking change.

Is the Hyperliquid API free?#

Yes. The Hyperliquid API needs no account, key or subscription, and reads cost nothing beyond your rate-limit budget. What costs money is what you do on HyperCore:

The activation charge is easy to miss. Hyperliquid charges it on the first transaction sent to a new HyperCore account, while Circle's CCTP on HyperCore page says deposits through its CoreDepositWallet defer it to the account's first outbound action. We budget for it either way: our deposit and exit limits ask the user to agree to it and set a 2 USDC minimum for that first move.

Third-party providers sell higher limits, archive data and colocated access. You do not need them to use the API. You may need them, or your own node, once the public limits below get in the way.

The Hyperliquid info endpoint: reading market and account data#

Every read is a POST to /info with a JSON body whose type picks the query. Hyperliquid's info endpoint page documents this order book snapshot (response shortened to one level per side):

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

{
  "coin": "BTC",
  "time": 1754450974231,
  "levels": [
    [{ "px": "113377.0", "sz": "7.6699", "n": 17 }],
    [{ "px": "113397.0", "sz": "0.11543", "n": 3 }]
  ]
}

The first array holds bids and the second asks, at most 20 levels per side, and n counts the orders at that price. Prices and sizes come back as strings, so parse them as decimals, not floats.

Three rules prevent most empty or wrong results:

• Query the real account, never the agent. Hyperliquid says passing an API wallet's address "leads to an empty result". Use the main or sub-account address.
• Spot coins have index names. PURR/USDC is the only spot pair with a readable name. Every other pair is @ plus its index in spotMeta.universe, so HYPE/USDC on mainnet is @107. The app also renames some pairs: BTC/USDC in the app is UBTC/USDC on HyperCore.
• Time ranges page at 500. A time-range query returns at most 500 elements. Use the last timestamp as the next startTime.

Perp and spot details sit on their own pages. The spot info page shows spotMeta listing USDC as token index 0 with weiDecimals 8 and token ID 0x6d1e7cde53ba9467b783cb7c530ce054. You need that exact name:tokenId pair, USDC:0x6d1e7cde53ba9467b783cb7c530ce054, in transfer actions such as sendAsset.

Those 8 decimals bite when money crosses to HyperEVM, where USDC has 6. Circle's CoreDepositWallet contract scales 6-decimal HyperEVM USDC to 8 decimals on HyperCore. In our own money code we keep the two units separate and convert on every crossing.

Hyperliquid's docs do not document a leaderboard endpoint as of 2 November 2026. For what is publicly known about the biggest accounts, see Hyperliquid's top traders.

The Hyperliquid exchange endpoint: placing and cancelling orders#

Every write is a POST to /exchange with three fields: the action, a nonce, and a signature over both. Hyperliquid's exchange endpoint page documents the order action with one-letter keys:

{
  "action": {
    "type": "order",
    "orders": [
      { "a": 4, "b": true, "p": "1100", "s": "0.2", "r": false, "t": { "limit": { "tif": "Gtc" } } }
    ],
    "grouping": "na"
  },
  "nonce": 1713825891591,
  "signature": { "r": "...", "s": "...", "v": "..." }
}

a is the asset ID, b is buy, p is the price, s is the size, r is reduce-only and t is the order type. Time in force is Alo (post-only), Ioc (immediate or cancel) or Gtc. An optional c sets a 128-bit client order ID, and an optional builder object adds a builder fee in tenths of a basis point. In our app we attach that object only when a fee applies: a buy that creates a brand-new HyperCore account goes without it, because that account cannot have approved a builder fee yet. The response returns one status per order:

{ "status": "ok", "response": { "type": "order", "data": { "statuses": [ { "resting": { "oid": 77738308 } } ] } } }

A status can also be filled with totalSz, avgPx and oid, or an error string such as "Order must have minimum value of $10." The outer "status": "ok" only means the batch was processed, so check each entry. Hyperliquid's error responses page adds a trap for batch senders: errors that follow from the payload alone, such as an empty batch, come back as one error for the whole request, not one per order.

Subaccounts and vaults have no private keys. The main account signs, and the request sets vaultAddress to the subaccount or vault. Many actions also accept expiresAfter, a millisecond timestamp after which validators reject the action. Hyperliquid warns that an action cancelled for a stale expiresAfter uses 5 times the normal address-based rate limit.

The fast cancel flag does less today than its name suggests. Hyperliquid's latency guide tells traders to send cancels with it, while the exchange page says that as of 2 November 2026 fast only makes the cancel reject trigger orders, and that mempool priority for fast cancels arrives "in a future network upgrade".

How does Hyperliquid API signing work?#

Hyperliquid signatures are EIP-712 typed-data signatures from an Ethereum key, but there are two schemes, and mixing them up is the most common bug. Hyperliquid's signing page lists the two Python SDK functions, sign_l1_action and sign_user_signed_action, and recommends using an SDK rather than writing your own signer.

The domain and payload details come from the official SDK's signing module, which the docs tell you to match "exactly". A wrong signature does not fail with "bad signature". It recovers a different address, so the error says something like "User or API Wallet 0x0123... does not exist" or "Must deposit before performing actions", naming an address that changes with every input. The usual causes, per Hyperliquid:

1. Using the wrong scheme for the action.
2. Changing the field order, which changes the msgpack bytes.
3. Trailing zeros on numbers: send "1100", not "1100.0".
4. Upper-case letters in addresses. Lower-case every address before signing.
5. Trusting a local recover-signer check, which can rebuild a different payload than the server does.

What is a Hyperliquid API wallet (API key)?#

A Hyperliquid API wallet is a separate key pair that your main account authorizes to sign for it. It is Hyperliquid's version of an exchange API key, and the docs also call it an agent wallet. You create one on the Hyperliquid API page or with the approveAgent action, signed by your main wallet.

Hyperliquid's nonces and API wallets page and the approveAgent field description set the rules:

• An account can have 1 unnamed API wallet and up to 3 named ones, plus 2 more named ones per sub-account.
• Appending valid_until {timestamp} to the name sets an expiry, at most 180 days ahead.
• Approving a new unnamed wallet replaces the old unnamed one. Approving a named wallet with an existing name replaces that one.
• An API wallet is pruned when it is replaced, when it expires, or when the account that registered it has no funds left.
• Never reuse an API wallet address. Once a wallet is pruned, its nonce history can be pruned too, and Hyperliquid warns that previously signed actions can then be replayed. Generate a fresh key every time.

Can a Hyperliquid API wallet withdraw funds?#

Not through any action Hyperliquid documents. withdraw3, usdSend, spotSend and sendAsset are user-signed actions, which the account's own key signs. The only transfer the docs say an agent may sign is agentSendAsset, and its destination "must match the source address", so it moves collateral between the same account's spot balance and perp DEXs. The builder codes page also says ApproveBuilderFee must be signed by the main wallet, not an agent. A leaked API wallet key still matters: it can trade, and bad trades can lose the account's money. Give each bot its own key, set an expiry, and revoke keys you no longer use.

How do Hyperliquid nonces work?#

Hyperliquid does not use Ethereum's one-by-one nonce, because a market maker can send thousands of orders and cancels a second. Per the nonces page:

• Hyperliquid stores the 100 highest nonces for each signer.
• A new nonce must be larger than the smallest stored nonce and must never have been used.
• A nonce must be within (T - 2 days, T + 1 day), where T is the block's Unix millisecond timestamp. In practice, use the current time in milliseconds.
• Nonces are tracked per signer. Sub-accounts or vaults signed by the same API wallet share that wallet's nonce set.

Hyperliquid's recipe for porting a bot from a centralized exchange: one API wallet per trading process (and per sub-account), a task that batches orders and cancels every 0.1 seconds, ALO orders batched apart from IOC and GTC because validators prioritize ALO-only batches, and an atomic counter for nonces that can jump forward to the current millisecond. Hyperliquid says this tolerates transactions arriving out of order by up to 2 seconds.

What are the Hyperliquid API rate limits?#

Hyperliquid limits each IP address and each trading address separately. The rate limits and user limits page sets the IP limits:

At weight 2, polling l2Book uses up the whole 1,200 budget at 10 requests per second, across all coins. That is why Hyperliquid tells anyone who wants real-time data to use the WebSocket.

Address-based limits apply to actions only, not info requests, and treat each sub-account as its own user:

• Requests. 1 action per 1 USDC traded since the address was created, on top of a starting buffer of 10,000. The docs' userRateLimit example shows exactly that: cumVlm of 2,854,574.59 and nRequestsCap of 2,864,574. An address that hits the limit gets one request every 10 seconds.
• Cancels. A higher cap of min(limit + 100000, limit * 2), so a rate-limited bot can still pull its orders.
• Batches. A batch of n orders counts as 1 request for the IP limit but n for the address limit.
• Buying headroom. reserveRequestWeight buys extra actions at 0.0005 USDC each, so 10,000 extra actions cost 5 USDC.
• Open orders. 1,000, plus 1 per 5 million USDC of volume, up to 5,000. Above 1,000, new reduce-only and trigger orders are rejected.
• Congestion. In heavy traffic, an address may use only twice its previous day's maker share of block space.

Account mode matters too. Hyperliquid's account abstraction modes page caps unified account and portfolio margin users at 50,000 actions per day and recommends standard mode for market makers and high-volume bots.

How do I use the Hyperliquid WebSocket?#

Open a connection to wss://api.hyperliquid.xyz/ws and send a subscribe message. The WebSocket page gives this exchange:

$ wscat -c wss://api.hyperliquid.xyz/ws
> { "method": "subscribe", "subscription": { "type": "trades", "coin": "SOL" } }
< {"channel":"subscriptionResponse","data":{"method":"subscribe","subscription":{"type":"trades","coin":"SOL"}}}

After the acknowledgement, messages arrive on a channel named after the subscription. Time-series feeds such as user fills start with a snapshot tagged isSnapshot: true. The subscriptions page lists 24 feeds as of 2 November 2026. The ones most bots use:

Two operational rules come from Hyperliquid's docs. First, servers disconnect "periodically and without announcement", so every bot must reconnect and resubscribe; missed data is in the snapshot on reconnect, or you can backfill with info requests. Second, the timeouts and heartbeats page says the server closes a connection it has not sent anything to for 60 seconds. On quiet feeds, send { "method": "ping" } well before that deadline, for example every 30 seconds, and expect { "channel": "pong" }.

WebSocket post requests#

The WebSocket also carries info requests and signed actions, which lets you send reads and signed actions over the socket you already have open. Hyperliquid's post requests page wraps the normal payload with an id you choose:

{
  "method": "post",
  "id": 123,
  "request": {
    "type": "info",
    "payload": { "type": "l2Book", "coin": "ETH", "nSigFigs": 5, "mantissa": null }
  }
}

The reply arrives on channel post with the same id, and response.type is info, action or error. For a signed order, set request.type to action and put the exact /exchange body in payload. Explorer requests do not work over the WebSocket.

Hyperliquid asset IDs, tick sizes and lot sizes#

Orders take an integer asset ID, and the formula differs by market type. Hyperliquid's asset IDs page defines them:

Spot pair IDs are not token IDs, and mainnet and testnet differ: HYPE is token 150 and spot pair 107 on mainnet, but token 1105 and spot pair 1035 on testnet. Never hard-code IDs across networks. Read meta, spotMeta and outcomeMeta at startup.

The tick and lot size page sets the price and size rules:

• Prices allow up to 5 significant figures and at most 6 - szDecimals decimal places on perps, or 8 - szDecimals on spot. Integer prices are always valid, so 123456 is valid while 12345.6 is not.
• Sizes round to the asset's szDecimals. With szDecimals = 3, 1.001 is valid and 1.0001 is not.
• Orders also need a minimum value: $10 on perps, or 10 units of the quote token on spot, per the documented error strings.

Using the Hyperliquid API with HIP-3 and HIP-4 markets#

HIP-3 builder-deployed perps#

HIP-3 markets, which outside teams deploy, live on separate perp DEXs. Their coins are named {dex}:{coin}, many info requests and subscriptions take a dex field (empty means the first, validator-run DEX), and their asset IDs use the HIP-3 formula above. Deployers operate them with perpDeploy actions, listed on Hyperliquid's HIP-3 deployer actions page. For what trades there, see HIP-3 builder-deployed perpetuals.

HIP-4 outcome markets#

Prediction markets, which Hyperliquid calls outcome markets (HIP-4), trade through the spot-style API with their own IDs. One encoding = 10 × outcome + side appears three ways: coin #10, token name +10 and asset ID 100000010 for outcome 1, side 0. Only sides 0 and 1 exist.

The docs' settledOutcome example shows a recurring BTC binary that settled No:

{
  "spec": {
    "outcome": 95,
    "name": "Recurring",
    "description": "class:priceBinary|underlying:BTC|expiry:20260526-0600|targetPrice:77363|period:1d",
    "sideSpecs": [{ "name": "Yes" }, { "name": "No" }],
    "quoteToken": "USDC"
  },
  "settleFraction": "0.0",
  "details": "price:76876.9"
}

Three HIP-4 differences catch integrators. Priority-fee order grouping is not available when any order is on an outcome asset, per the priority fees page. Builder fees can apply to outcome buys as well as sells, charged in the quote token on a best-effort basis, per Hyperliquid's HIP-4 deployer actions page. That page is still headed "Testnet-only" as of 2 November 2026 and caps testnet deployers at 10 active outcomes and 50 new outcomes a day. And settleFraction can sit between 0 and 1, so a side can pay part of a dollar.

From our own HIP-4 data work: split, merge and settlement show up in fills and ledger records but are not order-book trades, so we leave them out of price charts. The Yes and No books are mirrored views of one outcome's liquidity, so we never count them as two books. Our 2 October 2026 snapshot of Hyperliquid's mainnet outcome catalog held 257 outcomes, a dated catalog count, not a measure of liquidity. More on the markets in our guide to HIP-4 outcome markets.

HyperEVM JSON-RPC#

HyperEVM is a standard EVM JSON-RPC, not part of the /info and /exchange API. The public endpoint at https://rpc.hyperliquid.xyz/evm serves chain ID 999, allows 100 requests per minute per IP, supports most state calls only at the latest block, limits eth_getLogs to 50 blocks per query, and has no WebSocket, per Hyperliquid's JSON-RPC page. Contracts read HyperCore through precompiles and write to it through CoreWriter. Moving USDC the other way, from HyperCore to HyperEVM, is a signed sendAsset on the exchange endpoint to 0x2000000000000000000000000000000000000000, USDC's system address; our partner frontend funding guide shows the call our SDK makes. Our HyperEVM guide covers the RPC methods, gas, big blocks and the HyperCore bridge.

Running a Hyperliquid node#

Anyone can run a non-validating Hyperliquid node, with no permission or stake. The node software and setup steps are in the hyperliquid-dex/node repository, linked from Hyperliquid's nodes page. A node gives you the chain's data without public API rate limits and faster than the API.

Hyperliquid's optimizing latency page recommends at least 32 logical cores, 128 GB of RAM and 500 MB/s of disk throughput for a latency-sensitive node. It also recommends --disable-output-file-buffering to get output as soon as blocks execute, and building the book locally from node output; the order_book_server example shows how, though Hyperliquid says it is not actively maintained. Streaming split_client_blocks can save 70 to 150 ms on inputs, before execution results exist.

The L1 data schemas page says the node writes about 100 GB of logs per day under ~/hl/data:

HyperEVM blocks and receipts land in ~/hl/data/evm_block_and_receipts, per Hyperliquid's raw HyperEVM block data page.

A node needs a peer. The Hyper Foundation runs a best-effort non-validating peer in AWS apne1-az1, and its foundation node page requires, among other criteria, 10,000 staked HYPE and maker rebate tier 1 or above for direct access. Everyone else can peer through the paid providers on Hyperliquid's infra provider peering list, which names 16 as of 2 November 2026 and sets a benchmark price for them of under $1,000 a month. For history, Hyperliquid's historical data page points to requester-pays S3 buckets: hyperliquid-archive for book snapshots and asset contexts uploaded roughly once a month, and hl-mainnet-node-data for fills, explorer blocks and other events.

What we learned running our own node#

Totalis runs its own Hyperliquid mainnet node for production and a testnet node for staging. A Rust feed service tails the node's output into a durable log, rebuilds HIP-4 order books from it, and checks those books against the node's own state snapshots. Our backend records order statuses and cash events from node block streams instead of polling the info endpoint for account history, so account history comes from the same blocks the chain committed. One gap we hit: the node writes no file of perp mark prices, so marks come from a single shared polling path rather than a poller in every service.

Hyperliquid SDKs and testnet#

Hyperliquid maintains one official SDK, in Python, and links community SDKs from its API overview page:

The Python SDK's README starts with a testnet read:

from hyperliquid.info import Info
from hyperliquid.utils import constants

info = Info(constants.TESTNET_API_URL, skip_ws=True)
user_state = info.user_state("0xcd5051944f780a621ee62e39e493c489668acf4d")
print(user_state)

To trade with an API wallet, the README sets the API wallet's private key as secret_key and the main wallet's public address, not the API wallet's, as account_address.

Hyperliquid's testnet runs the same API on api.hyperliquid-testnet.xyz. The testnet faucet page gives 1,000 mock USDC, but only to an address that has deposited on mainnet. Email logins get different addresses on mainnet and testnet, so export the mainnet wallet first. Testnet asset IDs and template details differ from mainnet, so test the code path, not the IDs.

The Totalis Combo API is separate#

Totalis publishes its own REST and WebSocket API for Combos, apart from Hyperliquid's. A Combo joins 2 to 5 HIP-4 outcomes into one position with one payout, quoted by market makers through an RFQ and settled on HyperEVM. If you landed here looking for that, start at the Totalis API overview, or see Combos in use in the Totalis app.

Frequently asked questions#

Can I use the Hyperliquid API from the US?#

The API is a public endpoint, but Hyperliquid's terms of use bar US residents from the Hyperliquid app, and the foundation node page excludes applicants for "certain activities involving the U.S. or Ontario." Our guide to Hyperliquid in the US and KYC covers the rules.

How do I deposit funds to use the Hyperliquid API?#

Fund the HyperCore account first, usually with USDC. Our guide on how to deposit and withdraw on Hyperliquid covers the routes. A new HyperCore account pays a one-time 1 USDC activation charge.