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

Linking a token

Expert

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

Linking tells HyperCore which ERC20 represents a spot token, and how their decimals differ. Until then a HyperCore spot token (HIP-1) and an ERC20 are independent, and anyone can deploy an ERC20 called “PURR”. No token can cross until it is linked.

The link is a handshake: the spot deployer names a contract and the contract’s deployer agrees, because the two may use different keys and deploy in either order.

The handshake in four steps, using PURR

Section titled “The handshake in four steps, using PURR”

The docs’ example links PURR, token 1: 5 wei decimals on HyperCore and 18 on the HyperEVM, so evmExtraWeiDecimals is 18 minus 5, or 13.

1. Put the supply at the system address

Section titled “1. Put the supply at the system address”

Each side’s system address must hold the whole balance that is not on that side. The docs’ sample script mints the maximum HyperCore supply to the system address; their PURR contract mints 600,000,000 PURR at 18 decimals to 0x2000000000000000000000000000000000000001 in its constructor.

Section titled “2. Request the link (spot deployer)”

The spot deployer sends requestEvmContract, which the sample script signs as an L1 action. HyperCore stores the address as pending.

{
  "type": "spotDeploy",
  "requestEvmContract": {
    "token": 1,
    "address": "0x<erc20 address, lowercase>",
    "evmExtraWeiDecimals": 13
  }
}
Section titled “3. Finalise the link (EVM deployer)”

The contract’s deployer confirms with finalizeEvmContract, a top-level action not nested in spotDeploy. Its input says how the sender proves it deployed the contract; in the storage-slot cases the sender must match the stored address.

{"type": "finalizeEvmContract", "token": 1, "input": {"create": {"nonce": 0}}}
{"type": "finalizeEvmContract", "token": 1, "input": "firstStorageSlot"}
{"type": "finalizeEvmContract", "token": 1, "input": "customStorageSlot"}
Variant When What proves it
create the contract was deployed from an EOA the EOA sends the action with the nonce it used to deploy
firstStorageSlot the contract was deployed by another contract, for example create2 from a multisig storage slot 0 of the contract holds the finaliser’s address
customStorageSlot as above the slot at keccak256("HyperCore deployer") holds the finaliser’s address

4. The same finalisation from a contract

Section titled “4. The same finalisation from a contract”

CoreWriter action 8 finalises from the HyperEVM: (uint64 token, uint8 encodedFinalizeEvmContractVariant, uint64 createNonce), with 1 Create, 2 FirstStorageSlot and 3 CustomStorageSlot; only Create reads createNonce. Since CoreWriter acts for msg.sender, a contract can finalise, which suits a slot that names a contract; the docs say no more. The contract must already exist on HyperCore (CoreWriter).

The numbers

Section titled “The numbers”
Parameter Value
evmExtraWeiDecimals range -2 to 18 inclusive
EVM decimals weiDecimals + evmExtraWeiDecimals
Finalise variants create (1), firstStorageSlot (2), customStorageSlot (3)
Custom slot keccak256("HyperCore deployer")
Examples PURR 5 to 18 (13); USDC 8 to 6 (-2); USDT0 8 to 6 (-2)
Action 8 on mainnet 0 sightings in 3,000,001 EVM blocks

Checking that a contract is really linked

Section titled “Checking that a contract is really linked”

A contract calling itself a HyperCore token is that token only if HyperCore links it. Check evmContract.address in spotMeta, or the tokenInfo precompile at 0x80C, which also returns evmExtraWeiDecimals.

Circle’s USDC on the HyperEVM (0xb88339cb7199b77e23db6e890353e22632ba630f), used by lending markets, is not the contract HyperCore USDC is linked to (0x6b9e773128f453f5c2c60935ee2de2cbc5390a24, issuer not established). Moving between them is a swap (the two USDCs).

Choosing the offset

Section titled “Choosing the offset”

Either side may be deployed first. After finalising, verify the link and offset with spotMeta or 0x80C.

Choose the offset for its rounding rule (moving assets):

  • Positive (the HyperEVM is finer): HyperEVM to HyperCore remainders below 10^offset are burned, under 1 wei per the docs.
  • Negative (coarser, as for USDC): HyperCore to HyperEVM amounts that are not a multiple of 10^|offset| are rejected, in five observed sends without exception, so every integrator must floor.

The sample script’s comment says linking “is not reversible”: treat the address and offset as permanent.

The protocol checks the handshake, not the token

Section titled “The protocol checks the handshake, not the token”
Checked Not checked
The finaliser proves deployment, by create nonce or by the address stored in a slot That the system address holds sufficient supply
The requested address is held as pending until a matching finalisation arrives That the contract is a valid ERC20
What the contract’s transfer actually does

Per the docs the linked contract may have arbitrary bytecode, so verify its source and total balance. HyperCore credits from its Transfer log and the HyperEVM side calls its transfer; a contract that lies in either breaks the one-supply property.

A link does not guarantee a working token. Mainnet USDC’s linked contract is an upgradeable transparent proxy (2,175 bytes) whose standard views reverted on two RPCs while transfers flow normally. Testnet USDC’s has the same shape, reverts even on transfer, and kept 99 USDC bridged to it stuck (measured).

Where the docs are out of date

Section titled “Where the docs are out of date”
  • The TypeScript-style interface spells the field Address; the sample script sends address, lowercasing the contract address.
  • The docs say mainnet PURR “will be linked” once linking is enabled on mainnet. That is out of date: spotMeta shows USDC and USDT0 linked on mainnet.

For where the spot deployer comes from, see deploying a spot token.