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

Blocks, gas and RPC

Practitioner

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

HyperCore and the HyperEVM share one state, so the HyperEVM launched with deliberately low throughput, to be raised in steps. The docs call heavy HyperEVM bandwidth use technically risky and tie gas spikes under heavy demand to that limit. Users want fast blocks and deployers want big ones, so throughput is split into two streams.

Small blocks often, big blocks rarely

Section titled “Small blocks often, big blocks rarely”

Say your deployment needs 10M gas. No small block (3M) fits it, so it waits for a big block (30M), which comes once a minute.

Both kinds share one increasing sequence of EVM block numbers; with a block duration of x, the first L1 block in each x-second slot produces one. Each kind has its own mempool, held as on-chain state. Headers carry no kind flag; one production indexer calls a block big when its gas limit is at least 5,000,000.

Opting in to big blocks

Section titled “Opting in to big blocks”

Small blocks are the default. Big blocks need this HyperCore L1 action (signing), so the sender must already be a HyperCore user; an EOA becomes one by receiving a HyperCore asset such as USDC.

{"type": "evmUserModify", "usingBigBlocks": true}

The flag is HyperCore account state, not a transaction parameter. It survives restarts and applies to every transaction from the address until set back with "usingBigBlocks": false (eth_usingBigBlocks reads it).

So set it, deploy, unset: a forgotten flag leaves every later transaction waiting up to a minute.

Gas is HYPE, and the tip is burned too

Section titled “Gas is HYPE, and the tip is burned too”

EIP-1559 is on and the base fee is burned. Unlike most EVM chains, the priority fee is burned too, to the zero address’s EVM balance, which the docs attribute to HyperBFT consensus.

Method Returns
eth_gasPrice base fee for the next small block
eth_bigBlockGasPrice base fee for the next big block (the dual-block page calls it bigBlockGasPrice)
eth_feeHistory base fee history, as on any EIP-1559 chain

Building a transaction

Section titled “Building a transaction”

Pinned byte for byte against viem in one production client:

type        2 (EIP-1559), empty access list
chainId     999 mainnet, 998 testnet
nonce       eth_getTransactionCount(address, "pending")
tip         eth_maxPriorityFeePerGas              (0 today)
maxFee      2 * latest base fee from eth_feeHistory + tip
gas         eth_estimateGas * 1.3

Big-block senders take the base fee from eth_bigBlockGasPrice. The docs list eth_getTransactionCount as latest-block only, so track your own nonces when several transactions are in flight.

The RPC answers only at the latest block

Section titled “The RPC answers only at the latest block”

The official JSON-RPC is rpc.hyperliquid.xyz/evm (mainnet) and rpc.hyperliquid-testnet.xyz/evm (testnet), with no websocket. The same host’s rpc.hyperliquid.xyz/explorer shows what HyperCore did with a CoreWriter action (CoreWriter).

There is no historical state: eth_call, eth_estimateGas, eth_getBalance, eth_getCode, eth_getStorageAt and eth_getTransactionCount answer only at the latest block. Custom methods:

Method Purpose
eth_bigBlockGasPrice base fee for the next big block
eth_usingBigBlocks whether an address is sending to big blocks
eth_getSystemTxsByBlockHash, eth_getSystemTxsByBlockNumber the system transactions that originate from HyperCore, such as the credit of a HyperCore to HyperEVM transfer

To index without the RPC, a non-validating node writes blocks and receipts to ~/hl/data/evm_block_and_receipts. The requester-pays S3 buckets hl-mainnet-evm-blocks and hl-testnet-evm-blocks hold the same data, one LZ4-compressed MessagePack file per block (running a node, data).

Wrapped HYPE

Section titled “Wrapped HYPE”

WHYPE (18 decimals) is an immutable system contract, abbreviated 0x555...5 in the docs: the WETH9 source with name and symbol changed.

The numbers

Section titled “The numbers”
Parameter Value
Chain id 999 (0x3e7) mainnet, 998 (0x3e6) testnet
Small block 1 s, 3M gas
Big block 60 s, 30M gas
Pending nonces accepted per address next 8
Mempool expiry 1 day
HYPE decimals on the HyperEVM 18
Priority fee burned; eth_maxPriorityFeePerGas returns 0
eth_getLogs up to 4 topics; block range cap recorded as 50 and as 1,000 (see below)
Public RPC rate limit docs: same IP limits as the API server; one production tool records 100 requests per minute per IP
Boundary error code 10055
Wrapped HYPE 0x5555555555555555555555555555555555555555

Wallet setup

Section titled “Wallet setup”

Use chain id 999, currency symbol HYPE and RPC URL rpc.hyperliquid.xyz/evm. Gas is HYPE, not ETH; a wallet asking for ETH usually has the network misconfigured.

One popular wallet builds a type 2 transaction with a legacy gas price field and fails with “Invalid transaction envelope type: specified type 0x2 but included a gasPrice instead of maxFeePerGas and maxPriorityFeePerGas”. The docs call it a known issue and suggest switching wallets.

Boundary errors and log scans

Section titled “Boundary errors and log scans”
  • Pre-EIP-155 transactions are accepted, with no chain id in the signature; the docs advise against any wallet that has ever sent one.
  • Error code 10055 is a boundary error between HyperCore and the HyperEVM: nonce errors, insufficient funds, duplicate transaction hashes, underpriced replacements.
  • Chunk eth_getLogs and record which ranges succeeded; a skipped range is a hole. The 3,000,001-block scan behind this site had zero gaps.

Limits to plan around

Section titled “Limits to plan around”

Two limits are recorded inconsistently, unresolved:

Limit Docs Recorded Plan for
eth_getLogs block range 50 blocks official RPC 1,000; one third-party RPC 50,000 (3,000,001-block mainnet scan) 50 until verified on your endpoint
RPC rate limit same IP limits as the API server (rate limits) 100 requests per minute per IP (one production tool) 100 per minute until measured
  • Archive nodes serve historical blocks and code, not precompile history: a read precompile at an explicit block number fails (precompiles).
  • Testnet S3 data starts at block 18,000,000. Earlier blocks were not backfilled.

For the other gas cost, charged on HyperCore, see moving assets.