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.

Footguns, measured

Expert

Twelve ways a HyperEVM contract loses money or silently does nothing when it touches HyperCore, each with the on-chain evidence and the fix.

Almost every footgun here comes from two properties. CoreWriter reports nothing back, and one token lives on two scales (HyperCore wei, EVM decimals), with a third, 1e8 fixed point, in some action fields.

Unless marked as documented, each item was observed on chain: while building a tokenised lending vault, a rate index and a deployer-collateral facility, or in mainnet traffic scanned for them.

# Footgun What you see Fix
1 CoreWriter never reverts EVM status 1, nothing happened reconcile from HyperCore state
2 Non-round HyperCore to HyperEVM amounts “Invalid number of decimals” floor to 10^abs(offset)
3 Bridge gas comes out of HyperCore full-balance send refused keep a HyperCore reserve
4 Bad precompile input whole gas allowance burned cap gas per call
5 0x811 with no record PrecompileError non-reverting read, treat as zero
6 Scale traps 100x errors one conversion function, 1e8 for actions 1, 15, 17
7 Silent drops action vanishes, no error zero unused fields; verify spot orders
8 Mode gates action refused by account mode set abstraction first
9 Testnet is not mainnet code passes on testnet, fails on mainnet per-network constants, mainnet clocks
10 Docs contradicted by chain design built on a wrong sentence prefer measurement
11 Sources disagree on action 15 ops 2 and 3 unknown behaviour use ops 0 and 1 only
12 No sender on a HyperCore spot send deposit cannot be attributed take deposits on the HyperEVM side

For a contract that uses CoreWriter or the precompiles:

  • Every write: a later-block check against HyperCore state, and a failure path.
  • Every precompile call: an explicit gas cap and an output-length check.
  • Every HyperCore to HyperEVM amount: floored, with a fee reserve left on HyperCore.
  • Every amount: converted by one tested function, never inline.
  • Every network-specific id (token index, template name, contract address): looked up per network.

Each row of the table, with the page that owns it linked.

sendRawAction only emits a log, so the EVM transaction succeeds whatever HyperCore does. On testnet, supplying 100 USDC against under 1 USDC of spot returned status 1 while the explorer showed “Borrow/Lend error: Insufficient spot balance for operation”; on mainnet, a portfolio margin refusal of action 15 used 47,889 gas and returned status 1 (patterns).

2. Non-round amounts are rejected, not burned

Section titled “2. Non-round amounts are rejected, not burned”

With a negative offset (USDC: -2), HyperCore to HyperEVM amounts that are not a multiple of 10^abs(offset) fail with “Invalid number of decimals”; the docs’ burn rule covers only the other direction. The five observed sends are on moving assets.

3. Bridge gas comes out of the HyperCore balance

Section titled “3. Bridge gas comes out of the HyperCore balance”

A full 100 USDC testnet send was refused for want of the 200k-gas fee, charged on HyperCore, while 99 went through for 0.000588 USDC (the crossing fee).

An unsupported input burned the entire 50M allowance (PrecompileOutOfGas(50000000)); narrowed argument widths truncate outcome asset ids (gas, where reads fail).

The revert, the 31,989 USDC case and the first-deposit trap are on precompiles. Beyond that: after a first supply of 500 USDC on testnet, the read returned a basis of 500 and a value already above it.

USDC is 8 decimals on HyperCore and 6 on the HyperEVM, and EVM decimals are weiDecimals + evmExtraWeiDecimals, not szDecimals (moving assets). Actions 1 (limitPx, sz), 15 (wei) and 17 (wei) use 1e8.

One project brief assumed 6 decimals on HyperCore where spotMeta shows weiDecimals 8: a 100x error, caught before any capital moved. An earlier reference note gave action 17’s wei as 1e6; a testnet split with wei = 100,000,000 minted exactly 1 Long and 1 Short and moved 1 USDC.

Action 17 payloads with a non-zero unused field are dropped (per the docs), and so were spot orders on one testnet account (CoreWriter). Verify every order by its cloid in userFills.

No precompile exposes the abstraction mode, yet portfolio margin refuses action 15 and a unified account with open positions cannot be switched off (CoreWriter). Set the mode with action 16 (1 is Standard) before the contract holds anything, and check it with the userAbstraction info request (account modes).

  • The testnet USDC link is dead: every view and transfer reverts.
  • The unstaking queue drained in about 5 minutes on testnet against 7 days on mainnet.
  • HYPE is token 150 on mainnet and 1105 on testnet.
  • Mainnet had 18 outcome templates including scalarPrice; testnet had 66 and no scalarPrice.

Test duration logic against mainnet observations or a clock you control.

  • Orders: documented as delayed from CoreWriter, yet on mainnet they land 0.35 to 0.51 s after the block (n=52); only vault transfers are delayed (execution order).
  • The portfolio margin page says CoreWriter supply comes “in a future upgrade”; action 15 is live.
  • The action table has no 14, yet action 14 appeared 25 times in 3,000,001 mainnet blocks.
  • The mirrored HIP-4 deployer page says “Testnet-only”; mainnet carried 228 active outcomes when checked.

More in where the chain and the docs disagree.

One production client routes 2 as borrow and 3 as repay; a later investigation says action 15 exposes only supply and withdraw. Neither record was settled (CoreWriter).

12. A HyperCore spot send has no EVM-visible sender

Section titled “12. A HyperCore spot send has no EVM-visible sender”

A contract sees its balance rise through 0x801 but cannot tell who paid. Take deposits on the HyperEVM side, where msg.sender is known, then bridge; the operator workaround and its limits are on patterns.

For the designs that absorb these failures, see patterns. For how to see what HyperCore actually did, see CoreWriter.