Skip to content
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.

Priority fees and the activation fee

Expert

Hyperliquid 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.

Being early means reading blocks and mempool transactions first, or landing orders first, and both can be bought. The docs present priority fees as a way for market makers to focus on strategy instead of hyper-optimising infrastructure.

Say you send a 100,000 USDC IOC with "grouping": {"p": 10000}, a 1 bp rate. Per the docs’ mainnet figure, it cuts about 45 ms of latency. If it fills, you pay 10 USDC, charged in HYPE.

Both fees are burned, and neither overrides the protocol’s ordering: whatever the fee, all cancels go before all immediately executable orders.

Gossip priority lets a node order its peers by an on-chain auction, and the docs say the foundation non-validator opts in. It applies equally to all mempool-stream data, including split and normal client blocks carrying responses. It does nothing for orders, just as order priority does nothing for market data.

  • 2 independent Dutch auctions, one per slot (schedule and prices in the numbers). Each result applies for the duration of the next auction.
  • Lower slots are strictly prioritised, and slots are not additive: an IP that wins several ranks by its lowest.
  • The winning IP must exactly match the IP the sending peer sees. Behind a chain of nodes, each hop respects the ordering or not, per its configuration.
  • Any address may bid for any IP.
{"type": "gossipPriorityBid", "slotId": 0, "ip": "1.2.3.4", "maxGas": 100000000}

maxGas is in HYPE wei, so 100000000 caps the bid at 1 HYPE. {"type": "gossipPriorityAuctionStatus"} returns the winners in force and the live auctions; fees paid are in a node’s replica_cmds files.

Order priority buys time or queue position

Section titled “Order priority buys time or queue position”

Order priority is bought through the grouping field of an order action (orders):

{"type": "order", "orders": [{"a": 4, "b": true, "p": "1100", "s": "0.2", "r": false, "t": {"limit": {"tif": "Ioc"}}}], "grouping": {"p": 10000}}
  • Rate: p / 100000000, so p: 10000 is 1 bp.
  • Eligible only if every order is on a non-outcome asset, so HIP-4 books can’t be prioritised, and either all are Ioc or all are non-reduce-only Alo.
  • Charged from the undelegated staking balance on filled notional (IOC) or resting notional (ALO), converted to HYPE at the spot mark price. In USDC: order_price * order_sz * rate.

IOC priority buys time. The mempool sorts transactions by

effective_time = arrival_time + f(action, priority_fee)

where f is strictly decreasing in the fee and zero for prioritised actions such as cancels. Up to 8 bps (p = 80000) the effect is linear, about 45 ms per bp. Block boundaries do not matter for a given action type: transactions within a block are still sorted by effective_time.

Above 8 bps (up to 100 per cent) no more time is bought: IOC orders at 8 bps or more that the proposer would execute in the same 70 ms unix-time bucket sort by decreasing fee. Docs’ example: arrivals at T, T + 30 ms and T + 69 ms paying 8, 9 and 10 bps execute in reverse order.

ALO priority buys queue position. ALO orders pass the mempool first in, first out, about as fast as cancels, whatever the fee. After execution, each price level’s tail (orders placed within the last 400 ms) is sorted by decreasing rate, each new order comparing against it as it lands: a continuous window, not buckets. The fee is deducted at placement, even if the order never fills or is cancelled a moment later.

FRONT OF QUEUE AT LEVEL L t' A lands, no fee A first at the level t' + 399 ms B lands, fee p B A A is under 400 ms old, so B sorts ahead of it t' + 401 ms C lands, fee above p B A C A, now at the tail, is over 400 ms old: C joins the back
The docs' ALO example. A higher fee only reorders orders that are still inside the 400 ms tail, so B keeps a place that C, paying more, cannot take.

In node data, the IOC fee paid per fill is priorityGas in the user_fills file; the ALO ordering can be rebuilt from insertBefore on new-order entries in the raw book diffs.

What this means for you. Above 8 bps only ties within 70 ms are decided, so 20 bps pays off only against others at 8 bps or more. A maker who reprices often pays ALO priority on every placement.

A new account costs 1 quote token to activate

Section titled “A new account costs 1 quote token to activate”

The first transaction naming a new HyperCore account as destination costs 1 quote token (1 USDC, 1 USDT), whatever asset is sent, once per account (transfers). Node data records it as an AccountActivationGas ledger entry with amount and token.

Measured fee recorded
Testnet (controlled): first send to a fresh address 1.0
Testnet: second send to the same address 0.0
Testnet: first send to a second fresh address 1.0
Mainnet: sends to two freshly deployed contracts, sender’s ledger "1.0" each
Mainnet: payout to an existing account "0.0"

Unactivated accounts can’t send CoreWriter actions. CoreWriter never reverts, so a contract acting from a fresh address silently does nothing until its address receives a HyperCore transaction; the docs suggest deployers send it themselves. The account must already exist when the EVM block that emits its first CoreWriter action is built.

Separately, the API refuses a never-funded address: Must deposit before performing actions.

Item Value
Gossip auctions 2 slots, Dutch, on a shared 3-minute schedule
Gossip auction start 10 x the slot’s previous winning price
Gossip minimum price 0.1 HYPE
maxGas unit 1e-8 HYPE
Gossip effect (mainnet, per docs) about 25 ms per slot
Order priority rate p / 100000000 of notional
IOC linear range 0 to 8 bps (p 0 to 80000)
IOC effect (mainnet, per docs) about 45 ms per 1 bp
Maximum rate 100%
IOC tie-break bucket 70 ms of unix time, for orders at 8 bps or more
ALO priority window 400 ms
Priority fees paid from undelegated staking balance (order); spot balance (gossip)
Activation fee 1 quote token, once per new account
  • Fund priority with cDeposit into the undelegated staking balance (not spot or perps), without a tokenDelegate (staking).
  • Split batches by type: one mixed or ineligible order disqualifies the whole batch.
  • Bid with the IP the upstream peer sees; behind NAT or a load balancer that is not the machine’s own.
  • Poll gossipPriorityAuctionStatus before bidding: the start price follows the last winning price, so a slot’s cost changes every 3 minutes.
  • Compare priorityGas from node fills against the latency gained.

Before paying for priority, see Optimising latency for what to fix in code. For priority as a trading decision, see Latency, priority and infrastructure.