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.

Execution order and timing

Expert

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

HyperCore and the HyperEVM are two engines in one L1 block, and they run in a fixed order. Before your contract acts on a read, know what the read reflects, when the action runs and what can happen in between.

Per the docs, on an L1 block that produces a HyperEVM block:

  1. The L1 block is built.
  2. The EVM block is built; every precompile read in it sees HyperCore as of this moment.
  3. EVM to HyperCore transfers are processed.
  4. CoreWriter actions are processed.

Say one transaction reads a balance and sends an order. The read reflects HyperCore at step 2; the order runs at step 4, landing 0.35 to 0.51 s after the EVM block on mainnet. If HyperCore refuses it, your transaction has already succeeded.

A CoreWriter sender must exist on HyperCore before step 2; a same-block transfer that would create it still leaves the action rejected.

DOCUMENTED ORDER, ONE L1 BLOCK 1. L1 block built 2. EVM block built precompile reads fixed 3. EVM to HyperCore transfers credited 4. CoreWriter actions run, no reply MEASURED ON MAINNET: DELAY AFTER THE EVM BLOCK TIMESTAMP actions 6, 7, 13: 0.006 to 0.46 s (n=6 each) orders (action 1): 0.35 to 0.51 s (n=52) vault transfers (action 2): 4.05 to 4.10 s (n=6) 0 s 1 s 2 s 3 s 4 s Testnet: action 17 split and merge landed in the transaction's own block, 0.01 to 0.68 s (n=6).
Only vault transfers carry a multi-second delay. Everything else measured lands within about half a second of the block that sent it.

Each delay is the HyperCore ledger time minus the timestamp of the EVM block holding the RawAction log. Orders leave no ledger update, so fills were matched on the cloid in each action 1 payload. The mainnet sample covered blocks 46,080,800 to 46,154,714; testnet action 17 was polled from before submission, so a known-old sample brackets the transition.

Action Network n Delay after the EVM block In the docs’ delayed set
2 vault transfer mainnet 6 4.052 to 4.104 s yes
1 limit order, cloid-matched fills mainnet 52 0.347 to 0.514 s; mean 0.412, sd 0.039 yes
6 spot send mainnet 6 0.006 to 0.441 s no
7 USD class transfer mainnet 6 0.346 to 0.458 s no
13 send asset mainnet 6 0.009 to 0.419 s no
17 split and merge testnet 6 same block, 0.01 to 0.68 s no
1 resting limit order testnet 3 same block, 0.75 to 0.82 s yes

The 52 fills span 15 accounts and 14 markets, including spot pairs and builder-deployed perps. A fill 0.41 s after its block proves acceptance within 0.41 s, which a 4-second enqueue would make impossible.

Parameter Value
Order within an L1 block L1 block, EVM block, EVM to HyperCore transfers, CoreWriter actions
HyperCore to HyperEVM transfer queued until the next HyperEVM block
HyperEVM to HyperCore transfer same L1 block, right after the EVM block
Vault transfer delay 4.05 to 4.10 s (mainnet, n=6)
Order delay 0.35 to 0.51 s, mean 0.412 s (mainnet, n=52)
Actions 6, 7, 13 under 0.46 s (mainnet, n=6 each)
Action 17 same block (testnet, n=6)
Mainnet sample 5,455 actions, 73,914 blocks, about 20.5 hours
Testnet block interval 0.95 to 1.00 s

Two legs sent through CoreWriter (an order and a hedge, a split and a quote) are two HyperCore actions. They land close together, but either can be refused while the other goes through.

Pair Why
The EVM transaction and the action The transaction has finished before step 4 and succeeds either way
Two actions in one transaction Each is processed alone; a failed second does not roll back the first
A credit and a spend Spending a same-block EVM to HyperCore credit was not measured. One production mainnet deposit supplied its funds 3 blocks after bridging, and the vault contracts behind this site assume an earlier block
A read and an action Reads are as of step 2 and the action runs after step 3, so any ratio computed (a share price, a collateral value) is stale when the action lands

Same-block deposits share one snapshot, since neither action has run when the block is built. A vault that settled each by comparing a fresh read to its own snapshot minted shares for both when only one was funded. The fix is a cumulative figure every settlement must clear, plus one deposit in flight at a time (patterns).

Allow for lateness: one hardened vault design on testnet waits 5 blocks (FAIL_DELAY) before marking a deposit failed, and stops settling a pending deposit after 1,200 blocks (SETTLE_WINDOW).

Caveat Detail
Action 17 on mainnet is inferred, not measured None fell in the 73,914-block window, and only 4 in a 3,000,001-block scan. No testnet action showed any delay, so testnet cannot separate “action 17 is not delayed” from “testnet does not delay”
Two outlier fills were excluded +8.348 s and +16.982 s: resting limit orders that filled later. They bound fill time, not acceptance time
The clock has coarse ticks EVM block timestamps are whole seconds and ledger times milliseconds; the 4-second vault gap is far larger than that rounding
One testnet trial read N-1 Causally impossible: skew between the eth_blockNumber and eth_call round trips. Block counts carry about one block of noise; the timestamp column is tighter
The first action 17 measurement was retracted Sampled once, 3.67 s after submission, it could not tell same-block from any shorter delay; the table above is the re-run
Delayed actions in the explorer Shown twice, per the docs: first the enqueuing, then the execution

For the delayed set and other contradictions, see where the chain and the docs disagree.