Hyperliquid API Guide: REST Endpoints, WebSocket, Python SDK, Rate Limits, 422/429 Errors and HyperEVM RPC (2026)

The Hyperliquid API is a free, keyless REST and WebSocket interface at api.hyperliquid.xyz: POST to /info for market and account data, POST signed actions to /exchange to trade, and subscribe to wss://api.hyperliquid.xyz/ws for real-time books, trades and fills. An official Python SDK handles signing, HyperEVM is reachable at https://rpc.hyperliquid.xyz/evm (chain ID 999), and rate limits of 1,200 weight per minute per IP apply. This guide covers every endpoint group, working code snippets, rate-limit math, fixing 422 and 429 errors, RPC providers such as QuickNode, historical data sources and the basics of running a node.

Key takeaways

• Two REST endpoints, both POST with JSON bodies: /info (public data, no signature) and /exchange (orders, cancels, transfers, signed with EIP-712).
• WebSocket at wss://api.hyperliquid.xyz/ws streams order books, trades, candles, user fills and order updates.
• No API key is needed; trading is authorized by a wallet signature or an agent (API) wallet you create in the app.
• Rate limits: 1,200 weight/minute per IP on REST; per-address limits on /exchange scale with volume traded; WebSocket has connection and subscription caps.
• 422 = bad payload or signature; 429 = rate limited. Both are fixable client-side.
• HyperEVM RPC: https://rpc.hyperliquid.xyz/evm, chain ID 999 (testnet 998), gas in HYPE; QuickNode and others provide premium RPC.

Hyperliquid API overview and docs

Hyperliquid's docs live at hyperliquid.gitbook.io/hyperliquid-docs, with the API section under "For developers." The official code, including the Python SDK, Rust SDK and node software instructions, is on the hyperliquid-dex GitHub organization. Because every action on the chain is a signed transaction, the API is not an abstraction over a private matching engine; it is the same interface the Hyperliquid app DEX front end uses. Anything you can do in the app you can do programmatically, and everything you read is on-chain state.

Get free testnet USDC from the faucet; see the testnet and faucet guide.

REST endpoints: /info and /exchange

The /info endpoint

All reads go to /info as a POST with a JSON body whose type selects the query. No authentication is required. The most used request types:

Example: fetch every mid price with curl.

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

Response (truncated):

{"BTC": "112345.5", "ETH": "4123.45", "SOL": "198.32", "HYPE": "41.87", "@107": "0.1234"}

Perp coins are keyed by symbol; spot pairs are keyed by @index (map them with spotMeta). HIP-3 markets use a deployer:SYMBOL style name such as xyz:XYZ100, so query meta with the deployer's dex name to list them.

Example: a BTC order book with five significant figures.

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

Example: your perp account state.

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

The /exchange endpoint

Every state change is a POST to /exchange with three parts: an action object, a nonce (millisecond timestamp, strictly increasing per address) and a signature. Action types include order, cancel, cancelByCloid, modify, batchModify, updateLeverage, updateIsolatedMargin, usdSend, spotSend, withdraw3, vaultTransfer, approveAgent, approveBuilderFee, twapOrder and scheduleCancel. Orders reference assets by integer index from meta, and prices and sizes are strings that must respect each asset's tick and lot rules (up to 5 significant figures for price, szDecimals for size).

Signing is the part that trips people up, which is why the SDK exists.

Hyperliquid Python SDK

Install the official client:

pip install hyperliquid-python-sdk

Read data and place a limit order:

from hyperliquid.info import Info
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
import eth_account

# --- read-only ---
info = Info(constants.MAINNET_API_URL, skip_ws=True)
mids = info.all_mids()
print("ETH mid:", mids["ETH"])

state = info.user_state("0xYourAddress")
print("Account value:", state["marginSummary"]["accountValue"])

# --- trading with an agent (API) wallet ---
agent = eth_account.Account.from_key("0xAGENT_PRIVATE_KEY")
exchange = Exchange(
    agent,
    constants.MAINNET_API_URL,
    account_address="0xYourMainAddress",   # the account the agent trades for
)

# limit buy 0.01 ETH at $4000, good-till-cancel, post-only
result = exchange.order(
    "ETH", True, 0.01, 4000.0,
    {"limit": {"tif": "Alo"}},
)
print(result)

# cancel it
oid = result["response"]["data"]["statuses"][0]["resting"]["oid"]
print(exchange.cancel("ETH", oid))

Notes:

• Create the agent wallet in the app under More → API, or with exchange.approve_agent(). The agent can trade but cannot withdraw, which is the safe pattern for bots.
• tif values: Gtc (good till cancel), Ioc (immediate or cancel), Alo (add liquidity only, i.e. post-only).
• Use exchange.market_open() and exchange.market_close() for slippage-capped market orders, and exchange.update_leverage(leverage, coin, is_cross) before opening.
• For HIP-3 and spot assets, the SDK resolves names to indices for you.

A Rust SDK and community TypeScript/Go clients also exist on the hyperliquid-dex GitHub.

Hyperliquid WebSocket API

Connect to wss://api.hyperliquid.xyz/ws and send JSON subscription messages. Key subscription types:

Subscribe to the BTC book and trades:

{"method": "subscribe", "subscription": {"type": "l2Book", "coin": "BTC"}}
{"method": "subscribe", "subscription": {"type": "trades", "coin": "BTC"}}

Unsubscribe with "method": "unsubscribe", and send {"method": "ping"} every 50 seconds or the server will close idle connections. You can also post signed actions over the WebSocket using {"method": "post", "id": 1, "request": {"type": "action", "payload": {...}}}, which shaves a round trip for latency-sensitive bots. Limits: a maximum number of concurrent connections per IP and subscriptions per connection (both in the low hundreds), so multiplex rather than opening a socket per market.

With the Python SDK:

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

info = Info(constants.MAINNET_API_URL)
info.subscribe({"type": "l2Book", "coin": "ETH"}, lambda msg: print(msg["data"]["levels"][0][:3]))

Hyperliquid rate limits

Rate limits protect the chain, and they are generous if you design around them.

The address-based rule matters most for bots: an address that has traded $1M cumulatively has earned roughly 1,010,000 /exchange requests over its lifetime; if you spam cancels without trading, you will exhaust the 10,000 buffer and receive 429s until you generate volume. Batch orders (up to 40 per weight unit), use modify instead of cancel-and-replace, and lean on WebSocket for data.

Full details: Hyperliquid API docs, rate limits.

Fixing Hyperliquid 422 and 429 errors

A reliable debugging routine for "hyperliquid api 422": log the exact request body, compare it field by field with the SDK's output for the same action, and test on testnet first. Nine times out of ten the culprit is a price string like "4000.123456" (too many significant figures) or a stale nonce from a clock drift.

EIP-712 signing and EIP-7702

Hyperliquid authenticates /exchange actions with EIP-712 typed-data signatures. Two flavors exist:

• L1 actions (orders, cancels, leverage) are signed over a hash of the msgpack-encoded action, the nonce and an optional vault address, using the "Exchange" domain with chain ID 1337. The SDK handles this.
• User-signed actions (USDC transfers, withdrawals, agent approvals) are signed as human-readable EIP-712 messages with the Arbitrum chain ID so wallets display them clearly.

EIP-7702, the Ethereum account-abstraction upgrade that lets an EOA temporarily act as a smart-contract wallet, is relevant on HyperEVM: wallets can batch approvals and calls in one signature. As of September 2026 HyperCore itself still expects standard EOA or agent signatures; 7702-delegated accounts interact with HyperCore via the CoreWriter system contract from HyperEVM. If you see "hyperliquid 7702" in wallet prompts, it refers to delegating your EOA on HyperEVM, not to HyperCore trading.

👉 Open the Hyperliquid app and save 4% on fees

HyperEVM RPC: chain ID 999

HyperEVM is a standard EVM chain, so any Ethereum tooling works.

Add it to MetaMask or Rabby with those values. The public RPC is rate-limited and suits wallets and light scripts; for indexers, bots and dApps use a provider.

QuickNode Hyperliquid RPC and other providers

QuickNode offers dedicated HyperEVM endpoints (HTTP and WebSocket) with archive access, higher rate limits and add-ons, and it has also wrapped HyperCore /info calls as a QuickNode Hyperliquid API for teams who want one billing relationship. Alchemy-style providers, dRPC, Chainstack, Ankr and several community nodes also serve chain 999. When choosing, check for archive state (needed for historical balance queries), eth_getLogs range limits, and whether the provider exposes the HyperCore precompiles that let contracts read exchange state.

HyperEVM specifics worth knowing: blocks alternate between small fast blocks (about 1 second, 2M gas) and large slow blocks (about 1 minute, 30M gas); contracts read HyperCore data through precompiles at reserved addresses and write to it through CoreWriter; and HYPE is bridged between HyperCore and HyperEVM through a system address. See the HyperEVM guide.

Hyperliquid historical data

For Hyperliquid data beyond live feeds:

• candleSnapshot returns up to 5,000 candles per call at intervals from 1m to 1M; page with startTime.
• userFillsByTime and fundingHistory page through account and funding history.
• Public S3 archive: Hyperliquid publishes raw L2 book snapshots, trades and node data to a public bucket (hyperliquid-archive), useful for backtesting order-flow strategies; expect terabytes.
• Third-party datasets: Coinglass (liquidations, OI, funding), Hyperdash and Hypurrscan (wallet and vault history), DefiLlama (volume and fees), Dune (community dashboards), Amberdata and Kaiko (institutional feeds).
• Your own node: the only way to get complete, verifiable history of all state transitions.

Funding and open-interest interpretation is covered in the funding rates guide, and whale tracking sources in the whale tracker guide.

Running a Hyperliquid node

Hyperliquid Labs publishes the node binaries and setup guide in the hyperliquid-dex/node repository. The essentials as of September 2026:

• Hardware: a modern multi-core server, 32 GB+ RAM, fast NVMe storage (state grows quickly at billions of dollars of daily volume), and a low-latency connection; Tokyo-region hosting minimizes latency to the validator set.
• Modes: a non-validating node replays blocks and serves local /info-style data and raw state to your applications; a validator requires substantial HYPE stake and being admitted to the active set.
• Outputs: the node writes block data, trades, fills and order-book updates to local files that you can stream into a database, which is how the serious market-data firms build their Hyperliquid datasets.
• HyperEVM: the node also exposes the EVM RPC locally, giving you an unthrottled rpc hyperliquid endpoint.

Node software is distributed as binaries rather than full source as of this writing, a point critics raise; see Is Hyperliquid safe?.

Builder codes and bot platforms

If you are building a front end or bot for other people, builder codes let you attach a fee (approved once per user via approveBuilderFee) to orders you route, up to the user's cap. This is how Lootbase, Dexari, 3commas and Freqtrade integrations monetize. Our trading bots and builder codes guide covers the approval flow, and remember fees are set on top of the base schedule in Hyperliquid fees.

Practical tips for API traders

1. Develop on testnet (chain 998, testnet API) with faucet USDC before touching mainnet.
2. Use an agent wallet so your bot can never withdraw funds.
3. Cache meta once per session; asset indices change when markets are added.
4. Round correctly: price to 5 significant figures (and at most 6 decimals for perps), size to szDecimals.
5. Keep clocks synced; nonces are timestamps.
6. Prefer Alo orders for maker fees and Ioc with a slippage cap for fills.
7. Reconcile via userFills after reconnects; WebSocket messages can be missed.
8. Respect risk: an API bot can lose money faster than a human. Read the leverage and liquidation guide and start with small size. Nothing here is financial advice.

Bottom line

The Hyperliquid API gives you the full exchange, keyless and free: POST /info for any market or account data, POST signed actions to /exchange to trade, and stream everything over wss://api.hyperliquid.xyz/ws. The official Python SDK removes the signing pain, rate limits of 1,200 weight per minute and a volume-linked address budget are easy to live within if you batch and subscribe rather than poll, and 422/429 errors almost always trace back to payload formatting or request pacing. HyperEVM adds a standard RPC at chain ID 999 with QuickNode and others for scale, and a node gives you complete historical data. Build on testnet, trade through an agent wallet, and you have the same infrastructure the biggest market makers on Hyperliquid use.