Skip to content
DFUHL Docs
BuildStart here2 pages
Start here: building apps and front endsFoundationWhere an app or front end sits in the house, what it touches on HyperCore and the HyperEVM, which interfaces you use, and a reading order from a first request to contracts.Builder codesPractitionerA builder code lets an app add its own fee to the orders it routes, up to a ceiling the user signed for, capped by the protocol at 0.1% on perps and 1% on spot.
BuildBuild on HyperCore16 pages
Architecture: info, exchange, WebSocketFoundationHyperliquid's API has three surfaces: an unsigned read endpoint, a signed write endpoint, and a WebSocket that streams data and can carry both.Your first requestFoundationReading Hyperliquid needs no key, no account and no risk: three unsigned POST requests return the list of markets, an order book and any address's positions.Asset ids and namingPractitionerOrders name a market by an integer asset id and info requests by a coin string, and perps, spot, HIP-3 and outcomes each derive both by a different rule.Precision: tick size, lot size, significant figuresPractitionerA HyperCore price has at most 5 significant figures and a decimal cap set by szDecimals, a size at most szDecimals decimals, and outcomes use a 0.00001 grid.Signing from first principlesExpertL1 actions sign a keccak hash of their msgpack bytes, user-signed actions sign readable EIP-712 data, and one wrong byte in either recovers a stranger's address.Nonces, expiry and API walletsPractitionerHyperCore keeps each signer's 100 highest nonces and accepts a new one only if unused, above the smallest, and within 2 days before and 1 day after block time.Orders: place, modify, cancel, batch, dead man's switchPractitionerAn order is a signed action carrying a batch of compact orders; modify, cancel, TWAP and the dead man's switch are separate actions, each with its own response.Transfers and withdrawalsPractitionerEvery HyperCore transfer is a signed action: sends and withdrawals need the account's own key, and an API wallet's transfer actions keep value inside the account.Multi-sig actionsExpertA multi-sig action carries enough authorised users' signatures over one nonce and one named leader, in an envelope only the leader signs and submits.WebSocket: subscriptions, post requests, heartbeatsPractitionerOne WebSocket streams book, trade and account updates as blocks execute and carries signed actions, but drops without warning and forgets every subscription.Rate limits and user limitsPractitionerHyperliquid meters each IP by request weight, 1200 per minute, and each address by actions: 10,000 plus one per USDC traded.Priority fees and the activation feeExpertHyperliquid sells latency in two burned auctions, read priority per IP and write priority per order, and charges 1 quote token to activate a new account.Error responsesPractitionerHyperliquid reports errors at four layers, from HTTP status to a string inside a successful response, and several name a cause other than the real one.Debugging signatures and wire shapesExpertA signature over wrong bytes still verifies, so HyperCore recovers a stranger's address and says it does not exist; the fix is almost always the encoding.Optimising latencyExpertMost of an order's round trip is consensus; code wins by streaming reads, cutting serial round trips, using the fast order class and never stalling orders.Data: historical, node and explorerPractitionerThe API keeps only recent history; a full record needs pagination, archived node data or your own node, and each trade counted once by its trade id.
BuildBuild on the HyperEVM9 pages
What the HyperEVM is, and is notFoundationThe HyperEVM is Hyperliquid's smart contract environment: it reads HyperCore state and queues HyperCore actions, but never executes them atomically.Blocks, gas and RPCPractitionerThe HyperEVM produces small blocks every second and big blocks every minute, prices gas with EIP-1559 in HYPE, and serves a JSON-RPC with no historical state.Moving assets between HyperCore and the HyperEVMPractitionerLinked tokens cross between HyperCore and the HyperEVM via per-token system addresses, with a decimal offset and a 200k-gas fee when leaving HyperCore.Linking a tokenExpertLinking binds a HyperCore token to one ERC20 through the spot deployer's request and the contract deployer's finalisation; the protocol checks almost nothing else.Reading HyperCore: precompilesExpertRead precompiles are 21 fixed addresses, 0x800 to 0x814, that return HyperCore state as of the EVM block's construction, and only at the latest block.Writing to HyperCore: CoreWriterExpertCoreWriter turns a contract call into a HyperCore action for the caller's own account, run after the EVM block, with no result returned and no revert on refusal.Execution order and timingExpertEach L1 block runs the EVM block, then EVM to HyperCore transfers, then CoreWriter actions; on mainnet most actions land within half a second, vault transfers in about 4 s.PatternsExpertA contract that touches HyperCore stays solvent by recording an intent, sending the action, and settling only on HyperCore state that visibly moved.Footguns, measuredExpertTwelve ways a HyperEVM contract loses money or silently does nothing when it touches HyperCore, each with the on-chain evidence and the fix.
LearnWhat Hyperliquid is and how it works
Start here
First principles
Consensus and validators
HyperCore
Research
For the press
TradeMarkets, margin and risk
Start here
Trading fundamentals
Perpetuals
Spot
Outcome markets
Accounts and credit
Advanced trading
Incentives
BuildApps, bots and contracts
Start here
Build on HyperCore
Build on the HyperEVM
DeployLaunch and run markets
Start here
The HIPs
Deploy markets
ReferenceEvery number, action and term
Look up
Protocol tables

Architecture: info, exchange, WebSocket

Foundation

Hyperliquid's API has three surfaces: an unsigned read endpoint, a signed write endpoint, and a WebSocket that streams data and can carry both.

Your code reads and changes Hyperliquid through this API. Every balance, position and resting order is HyperCore replicated state. Anyone may read any account; only the owner, or a key it approved, may change it.

Three surfaces behind one API server

Section titled “Three surfaces behind one API server”

Your requests go to an API server, which keeps a copy of a node’s state. Data freshness is covered on API servers.

Your code reads need no key actions are signed POST /info POST /exchange wss /ws API server keeps state from a node answers /info itself forwards /exchange signed actions blocks, state Node gossips the action into HyperBFT result after commit
Reads are answered from the API server's copy of the state. Signed actions travel on to a node and are answered only once their block commits.
Surface Path What it does Signed
Info POST /info Reads markets, books, balances, positions, orders and fills, for any address No
Exchange POST /exchange Writes: orders, cancels, transfers, approvals, deployments Yes
WebSocket /ws Streams subscriptions; can also carry info requests and signed actions as post messages Only the actions it carries

Every HTTP request is a POST with a JSON body and Content-Type: application/json. There are no per-resource URLs: a type field picks the query or action.

Think of /info as a public records office and /exchange as a counter for signed instructions. Unlike a counter, a write waits for consensus; a read never does.

The numbers

Section titled “The numbers”
Mainnet Testnet
REST base https://api.hyperliquid.xyz https://api.hyperliquid-testnet.xyz
Reads <base>/info <base>/info
Writes <base>/exchange <base>/exchange
WebSocket wss://api.hyperliquid.xyz/ws wss://api.hyperliquid-testnet.xyz/ws
Case Shape
Info request The requested JSON itself, with no envelope
Exchange action with a result {"status":"ok","response":{"type":"order","data":{"statuses":[...]}}}
Exchange action with nothing to report {"status":"ok","response":{"type":"default"}}
Exchange action refused {"status":"err","response":"<plain string>"}
Body that does not parse HTTP 422 with a plain-text body beginning Failed to deserialize

One IP’s REST requests share a weight budget of 1200 per minute; actions also draw on a per-address budget. See rate limits.

Every write is one signed JSON body

Section titled “Every write is one signed JSON body”

Here is an order as your code sends it:

{
  "action": {
    "type": "order",
    "orders": [{ "a": 0, "b": true, "p": "50000", "s": "0.001", "r": false, "t": { "limit": { "tif": "Gtc" } } }],
    "grouping": "na"
  },
  "nonce": 1713825891591,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 },
  "vaultAddress": "0x...",
  "expiresAfter": 1713825951591
}

vaultAddress and expiresAfter are optional and exist only for L1 actions, one of two kinds:

L1 action User-signed action
Examples order, cancel, modify, scheduleCancel, updateLeverage, vaultTransfer, twapOrder usdSend, spotSend, sendAsset, withdraw3, usdClassTransfer, approveAgent, approveBuilderFee
What is signed a hash of the action’s msgpack bytes, the nonce and the optional fields the action’s fields as readable EIP-712 typed data
EIP-712 domain Exchange, chain id 1337 HyperliquidSignTransaction, chain id from signatureChainId
Network bound by source: "a" mainnet, "b" testnet hyperliquidChain: "Mainnet" or "Testnet"
Who may sign the account, or an API wallet it approved the account’s own key
Optional body fields vaultAddress, expiresAfter none

Sub-accounts and vaults have no keys: the master account signs with vaultAddress set to the sub-account or vault. Byte-level detail is on signing.

Read every response defensively

Section titled “Read every response defensively”
  • "status":"ok" doesn’t mean every order worked: each gets its own resting, filled or {"error": "..."}. The docs’ ok example carries "Order must have minimum value of $10.".
  • Read the body as text first: a 422 is plain text.
  • Query by the account’s address; an API wallet’s address returns nothing.

One WebSocket for streams and posts

Section titled “One WebSocket for streams and posts”

One connection carries three messages; details are on WebSocket.

Message Use
{"method":"subscribe", "subscription": {...}} streams
{"method":"ping"} liveness
{"method":"post","id":N,"request":{"type":...,"payload":{...}}} anything HTTP can send; type is "info" or "action"

Replies to a post arrive on the post channel with your id, wrapped one level deeper than over HTTP. API servers drop WebSockets without notice and don’t replay posts: reconcile them over HTTP.

Test on the network you ship to

Section titled “Test on the network you ship to”
  • The networks can parse shapes differently: they diverged while the HIP-4 deploy moved from {"type":"spotDeploy","outcome":{...}} to top-level outcomeDeploy.
  • Testnet is separate state: asset ids, token indices, HIP-3 dexes and API wallet approvals differ. Key caches by network.

For your first unsigned read, see Your first request. For how both kinds of action are signed, see Signing from first principles.