Hyperliquid API: A Practical Developer Guide (Info, Exchange, WebSockets)
5 min readHyperRadar
The Hyperliquid API is one of the quiet reasons the ecosystem around the exchange exploded. Every position, order, trade and liquidation on Hyperliquid is queryable over a clean HTTP + WebSocket interface — reads need no API key, no signup, no rate-limit token. You POST a JSON body and get JSON back. That's the whole integration story.
This guide covers the parts you'll actually use: the info endpoint for reading state, the exchange endpoint for signing actions, WebSockets for real-time streams, rate limits, and the SDKs that make it all easy. HyperRadar itself is built on this API, and we open-sourced pieces of our tooling along the way — more on that below.
The architecture in one paragraph
Hyperliquid exposes two HTTP surfaces. Reads go to the *info* API at api.hyperliquid.xyz/info — a single POST endpoint where the request body's type field selects the query (there is no REST-style URL tree). Writes — placing orders, canceling, transfers, staking — go to the *exchange* API at api.hyperliquid.xyz/exchange, where every action is an EIP-712 signature from your wallet (or an API wallet). Real-time updates arrive over WebSocket at api.hyperliquid.xyz/ws. Everything is JSON; everything is documented in the official docs.
Reading state: the info endpoint
The info API is where every analytics tool starts. The workhorse requests:
- {"type": "clearinghouseState", "user": "0x…"} — open perp positions, entry prices, leverage, unrealized PnL, margin
- {"type": "userFills", "user": "0x…"} — recent fills with fees and closed PnL
- {"type": "metaAndAssetCtxs"} — every market with mark price, funding, open interest, and the day's volume in one call
- {"type": "allMids"} — mid prices for all assets, the cheapest live tick you can poll
- {"type": "userFunding", "user": "0x…"} — funding payments, the line item most PnL trackers forget
For example, fetching a trader's live positions in Python is four lines — POST the body, read assetPositions from the response. No auth, no key rotation, no whitelist. This openness is why whale trackers like HyperRadar can show every wallet's positions in real time: the data model has no concept of a private position. Check any address on the leaderboard and you're looking at the same payloads the API returns.
Writing state: the exchange endpoint and signing
Placing an order means constructing an action object, signing it with EIP-712 (the primary type is HyperliquidTransaction:Order), and POSTing the signature plus action to the exchange endpoint. Two practices the docs hammer and every production system follows:
- Use an API wallet for automated trading — an agent key generated with {"type": "generateApiKey"} on the exchange endpoint. It can trade but cannot withdraw, and you can approve a specific nonce range to prevent replay. Signing straight from your main wallet in a bot is asking for a drain.
- Handle the response's status field. The API returns ok, err, or a status like frontEndIndex mismatch — treat anything not ok as a failed action and reconcile. Silent assumption is how bots double-position.
The same signing scheme covers cancels, batch orders, transfers between Spot and Perp accounts, vault deposits and staking actions — and with builder codes, third-party frontends can append their own code to orders for fee-share attribution, which is how much of the Hyperliquid frontend ecosystem funds itself.
Real-time: WebSockets
Polling allMids is fine for slow dashboards; anything reactive should use the WebSocket. Subscribe to channels like activeAssetCtx (per-market context), trades (fills), candle (OHLC), userEvents or userFills for a specific address, and webData2 for a full portfolio snapshot. The server also sends pong heartbeats — answer them or the connection drops. For liquidation-watch tools, the trades stream plus large-fill filtering is the standard recipe; we cover the mechanics in Hyperliquid Liquidations.
Rate limits, and staying inside them
Rate limits are weight-based: each info request type has a cost, and both per-IP and per-user budgets apply. The practical rules that keep bots alive: prefer metaAndAssetCtxs over looping meta + per-asset calls, batch user queries where possible, cache aggressively (most public state changes slowly), and back off on 429s. Write actions have their own limits. If you find yourself fighting the limits, the answer is almost always caching, not retrying harder.
SDKs and tooling
You don't have to hand-roll the signing. The official hyperliquid-python-sdk and community SDKs for TypeScript/Go/Rust handle EIP-712 signing, agent wallets and the WebSocket plumbing. For analytics, Dune has decoded Hyperliquid tables, and every wallet explorer in the ecosystem — us included — sits on the info API.
About our own tools: HyperRadar is built entirely on the public API above, and we've released parts of our stack as open-source tools on GitHub (search "hyperradar") — including the client patterns we use for polite bulk fetching of leaderboard and wallet data. Use them as a starting point rather than re-solving rate limits from scratch.
A first project to build
The API is friendly enough that a useful first project takes an afternoon:
- Pull metaAndAssetCtxs every minute and log open interest by market — you now have a dataset for finding squeezes
- Add clearinghouseState for the top accounts from the HyperRadar leaderboard and you have a whale watcher
- Wire Telegram alerts on position changes and you've rebuilt the core of what HyperRadar alerts do — or just use ours and spend your time on strategy instead
Full reference documentation lives at the official Hyperliquid docs site; the endpoint catalog there stays current as new request types ship.
Try HyperRadar free → [https://hyperradar.org](https://hyperradar.org) — wallet tracking, leaderboards and alerts built on this exact API.
Track Hyperliquid smart money in real time — leaderboard, wallet pages and whale alerts.
Try HyperRadar free →