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

Transfers and withdrawals

Practitioner

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

In standard mode your account holds separate balances, and nothing moves between them by itself. There’s spot, one per perp dex (the validator-operated USDC dex and each HIP-3 dex it uses), staking and vault positions, plus sub-accounts, which are accounts in their own right.

Say 100 USDC sits in spot and you want it as margin on the USDC perp dex. You sign one sendAsset from "spot" to "" with your own key.

The action fixes the key. Every send to someone else or off the chain is user-signed (EIP-712, readable in a wallet) by the account’s own key, as are a few internal moves such as usdClassTransfer and staking deposits. The documented L1 transfers, which an API wallet may sign, stay inside the account: a leaked trading key can’t withdraw.

Two kinds of transfer action

Section titled “Two kinds of transfer action”

On the wire (bytes on signing):

User-signed L1 action
hyperliquidChain ("Mainnet"), signatureChainId inside the action absent
Nonce inside the action time for usdSend, spotSend, withdraw3; nonce for the rest; equal to the outer nonce absent
vaultAddress, expiresAfter not accepted accepted, as on an order
Action Moves Signed by Notes
usdSend USDC to another address own key disabled on unified and portfolio margin accounts
spotSend a spot token to another address own key token as "NAME:0x<32 hex>"; disabled on unified and portfolio margin
usdClassTransfer USDC between spot and perp, same account own key toPerp; disabled on unified and portfolio margin
sendAsset any token between perp dexes, spot, users and sub-accounts own key the general form; works in every mode
agentSendAsset as sendAsset, but destination must equal the source API wallet
withdraw3 USDC out to Arbitrum own key $1 fee
vaultTransfer USDC into or out of a vault API wallet or own key usd integer, 1e6 per USDC
subAccountTransfer USDC between master and sub-account API wallet or own key not in the official docs
subAccountSpotTransfer a spot token between master and sub-account API wallet or own key not in the official docs
cDeposit, cWithdraw HYPE between spot and staking own key cWithdraw enters a 7-day queue
hip3LiquidatorTransfer quote tokens to or from a HIP-3 dex’s backstop liquidator API wallet or own key only principal is withdrawable
sendToEvmWithData a token to a linked HyperEVM contract, with a payload own key see HyperEVM transfers

A user-signed transfer can’t carry expiresAfter, so once signed but unsubmitted it stays valid while its nonce is within 2 days before to 1 day after block time and above the lowest of the signer’s 100 stored. Hand one out only if you accept its execution.

sendAsset and the dex strings

Section titled “sendAsset and the dex strings”

sendAsset generalises the older sends. Balances are strings: "" is the validator-operated USDC perp dex, "spot" the spot balance, anything else a HIP-3 dex. Only a dex’s collateral token can enter or leave it.

The move above:

{
  "type": "sendAsset",
  "hyperliquidChain": "Mainnet",
  "signatureChainId": "0xa4b1",
  "destination": "0x0000000000000000000000000000000000000000",
  "sourceDex": "spot",
  "destinationDex": "",
  "token": "USDC:0x6d1e7cde53ba9467b783cb7c530ce054",
  "amount": "100",
  "fromSubAccount": "",
  "nonce": 1716531066415
}

destination is your own address for internal moves, or another to pay; lowercase it, because its case is hashed. fromSubAccount sends from a sub-account. amount is a decimal string, not wei.

Sub-accounts and vaults sign through the master

Section titled “Sub-accounts and vaults sign through the master”

Sub-accounts and vaults have no keys. L1 actions are signed by the master (or its API wallet) with vaultAddress set to the sub-account or vault; user-signed actions name the sub-account inside, as fromSubAccount on sendAsset or an amount of "1 subaccount:0x..." on usdClassTransfer. One API wallet signing for several sub-accounts shares one nonce set. Vault lock-ups are under The numbers (vaults).

Action Fields Notes
vaultTransfer {vaultAddress, isDeposit, usd} the docs type usd only as a number; SDKs send an integer in millionths, so 10 USDC is 10000000
subAccountTransfer {subAccountUser, isDeposit, usd} L1 action in SDK code, not in the official docs
subAccountSpotTransfer {subAccountUser, isDeposit, token, amount} L1 action in SDK code, not in the official docs

Withdrawing to Arbitrum

Section titled “Withdrawing to Arbitrum”

withdraw3 carries {amount, time, destination} plus the two chain fields, and signs as HyperliquidTransaction:Withdraw per the docs’ Rust type (one SDK used Withdraw3). Validators submit it to the Arbitrum bridge contract; you send no Arbitrum transaction.

The docs file it under the Arbitrum bridge, now legacy and deprecated, and prefer CCTP for native USDC.

Crossing to the HyperEVM

Section titled “Crossing to the HyperEVM”

Send with spotSend or sendAsset to the token’s system address, 0x20 followed by the token index (HYPE is 0x2222...2222).

  • With sendAsset the dex must be "spot"; "" returns Invalid token.
  • The crossing costs 200k gas at the next EVM block’s base fee, taken from the HyperCore balance, so a balance never bridges in full.
  • USDC not in whole HyperEVM units is rejected with Invalid number of decimals (5 of 5 cases measured).
  • A HyperEVM transfer that fails on HyperCore does not revert: the EVM transaction succeeds and the money stays put (footguns).

The activation fee

Section titled “The activation fee”

The first transaction to a new HyperCore account costs 1 quote token (1 USDC, 1 USDT), whatever is sent. Measured: two sends to one fresh testnet destination recorded fee 1.0 then fee 0.0; mainnet sends to fresh contracts each carried "fee": "1.0" in the sender’s ledger. Unactivated accounts cannot send CoreWriter actions (activation fee).

The numbers

Section titled “The numbers”
Item Value
Activation fee 1 quote token, once, on the first transaction to a new account
withdraw3 fee $1, “at the time of this writing”
withdraw3 time about 5 minutes (exchange docs); 3 to 4 minutes (bridge docs)
Legacy bridge deposit credited in under 1 minute; minimum 5 USDC, smaller deposits are lost
vaultTransfer.usd, subAccountTransfer.usd integer, 1e6 per USDC
hip3LiquidatorTransfer.ntl integer in 1e-6 quote tokens; a multiple of 1000 quote tokens
HLP deposit lock-up 4 days; user vaults 1 day
Unstaking queue 7 days
Unified and portfolio margin accounts 50k user actions per day
HyperCore to HyperEVM gas 200k gas x next EVM block base fee
USDC decimals 8 on HyperCore, 6 on the HyperEVM

Where your USDC can margin

Section titled “Where your USDC can margin”

In standard mode, USDC margins only the balance it sits on: spot, the USDC perp dex, or one HIP-3 dex. Unified and portfolio margin accounts have one balance per asset, so these moves disappear, but the older sends stop working.

Sending transfers from code

Section titled “Sending transfers from code”
  • Default to sendAsset, which works in every mode. usdSend, spotSend and usdClassTransfer fail on unified and portfolio margin accounts with Action disabled when unified account is active.
  • On those accounts, all balances and holds are in spotClearinghouseState; per-dex perp states are not meaningful.
  • Price the activation fee into payouts to fresh addresses: at small sizes 1 USDC can exceed months of yield.
  • Reconcile from the ledger, not your request log (data):
Entry Source
internalTransfer (a usdSend), spotTransfer (with its fee), accountClassTransfer, subAccountTransfer, withdraw, vault entries userNonFundingLedgerUpdates
AccountActivationGas, PerpDexClassTransfer node data

For system addresses, decimals and the crossing fee, see HyperCore and HyperEVM transfers. For what sub-accounts are, see Sub-accounts.