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

Patterns

Expert

A contract that touches HyperCore stays solvent by recording an intent, sending the action, and settling only on HyperCore state that visibly moved.

On the HyperEVM, a HyperCore refusal never reverts your transaction. An action can be refused after the EVM transaction succeeded, reads are a block old when it lands, leaving HyperCore is charged on the other side, and past HyperCore state cannot be re-read.

One tokenised lending vault that already persisted intent, acted, then verified next block was still exploitable four ways under attack on testnet. One needed no HyperCore failure, only two users redeeming. The patterns below survived.

Intent now, settlement in a later block

Section titled “Intent now, settlement in a later block”

Each HyperCore write becomes a state machine spanning blocks:

block N        record intent (amount, snapshot, block number); send the CoreWriter action
block > N      read HyperCore through a precompile; if the position grew past the cumulative
               figure, settle (mint, credit, release)
block >= N+5   if still not credited, mark failed; the depositor can pull the funds back
block > N+1200 a pending intent can only fail, never settle

Say a user deposits in block 100. From block 101 the vault reads HyperCore, minting once the position grows past the cumulative figure. If nothing has moved by block 105, the intent can be marked failed; after block 1,300 it can never settle.

The contract never treats its own EVM success as evidence. Only HyperCore state, read later, moves the books.

The numbers

Section titled “The numbers”
Parameter Value Why
Grace before failing an intent 5 blocks an action landing late is not an action dropped
Settle window 1,200 blocks bounds interest slack behind a stale intent
Deposits in flight 1 same-block intents share a snapshot
Minimum deposit in one design 0.1 USDC (1e7 at 8 decimals) below this, accrued interest can exceed the deposit inside the window
Precompile gas cap about 2 x 2000 + 65 * (in + out) contains a bad input’s all-gas burn
Floor step, HyperCore to HyperEVM 10^abs(evmExtraWeiDecimals); 100 for USDC non-round amounts are rejected
HyperCore-side reserve at least 200k gas x the base fee, in HYPE or the token the crossing fee comes out of HyperCore

Accounting that survives refusal

Section titled “Accounting that survives refusal”
  • Intent, then reconcile. Record the amount, block number and comparison snapshot before sending; decide in a later block from a HyperCore read. The EVM receipt, the RawAction log and a successful status say nothing about the outcome.
  • Mint only what HyperCore credited: 0x811 supply.value for a lending position, 0x801 for a spot balance. Never the amount the user claims, and never 0x812 balance, which includes the protocol’s retained buffer (46.57 USDC above totalSupplied - totalBorrowed when measured).
  • One deposit in flight, cumulative accounting. Same-block intents share a snapshot, so verified separately both pass when only one was funded. Settle against a cumulative figure (accountedAssets in one design) that every earlier settlement has raised; “verify next block” is necessary, not sufficient.
  • Reserve before you price a redemption. Two redeemers, one pot. No HyperCore failure, no adversary, no dropped action. If a request burns shares and fixes a claim but leaves assets untouched, the next redeemer divides the same assets by fewer shares: with 100 shares on 100 assets, the first redeemer of 50 shares is owed 50 and the second 100; so add every open claim to a reserved figure and price off assets net of it.
  • Prove the position fell before paying out. Checking only the spot balance can pay a redeemer with a new depositor’s money when a withdraw was refused and a deposit arrived. Check the lending position fell by the withdrawn amount, allowing for accrual at the reserve’s advertised rate.
  • Grace, then fail, then refund. After a fixed wait, let anyone mark the intent failed, with a permissionless path for the depositor to pull funds out of the contract’s HyperCore balance. Otherwise a refused supply strands the money in the vault’s HyperCore spot balance.

Operating rules

Section titled “Operating rules”
Rule How, and why
Floor before bridging With a negative offset, interest accruing at 8 decimals means a full USDC balance almost never qualifies: floor, send, leave the dust. One mainnet operator supplied 1 EVM wei less than it had bridged (moving assets)
Keep a HyperCore-side reserve for bridge gas In HYPE or the token: “withdraw everything, then bridge everything” cannot work
Cap gas on every read One function with an explicit cap and an output-length check, plus a non-reverting variant for loops and expected failures such as 0x811 before a first supply (precompiles)
Confirm from the outside Poll the explorer’s userDetails for the typed action and its error, or the info API for the effect (userFills by cloid, ledger updates). Record it: the explorer keeps only the last 300 actions per user (CoreWriter)
Span blocks for setup The sender must exist on HyperCore before its EVM block: deploy, activate or fund on HyperCore, set the abstraction mode (action 16, before any position), then send the first working action
Sample forward Precompiles answer only at the latest block: store any rate, index or price you will later need to justify when you see it. A logger started late has lost the history for good
Prefer the deterministic leg A split into Long and Short (action 17) mints a bounded, fully collateralised position and landed in its own block on testnet; a naked perp leg can fill at a moved price or not at all. As legs are not atomic, build split-and-quote before paired perp hedging

Where the patterns stop

Section titled “Where the patterns stop”
  • Attribution is still open. A HyperCore spot send to a contract has no EVM-visible sender, so someone must name the receiver; under these patterns they cannot mint unbacked shares but can credit the wrong address. A fix needs a depositor attestation or a HyperCore sub-account per depositor.
  • A principal ledger is not a solvency gate. Gating payouts on the cumulative deposit figure rejected an honest full redemption whose claim included accrued interest. Use it to check mints, not payouts.
  • Not every design fits. Anything needing an all-or-nothing HyperCore outcome in one transaction has no pattern here (one transaction).
  • Testnet hides duration bugs. The unstaking queue drains in about 5 minutes on testnet against 7 days on mainnet, so queue logic that looks right there is wrong in production.

For a tokenised lending vault built on these patterns, see composable credit.