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

Builder codes

Practitioner

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

A builder code is how an app gets paid for the orders it sends. The exchange fee pays the app nothing: it goes to HLP, the assistance fund and market deployers. “Builder” here means an application developer, not a block builder.

Say you approve an app for up to 0.1%, and it sends a $10,000 perp buy for you with f = 50:

  • f = 50 is 5 basis points → the builder earns $5, on top of the exchange fee.
  • Your approval caps f at 100 → the app could have charged up to $10.

From approval to payout

Section titled “From approval to payout”
  1. The builder qualifies on perps account value and account mode (limits below).
  2. The user approves a maximum rate for the builder address with ApproveBuilderFee, signed by the main wallet, not an API wallet, and revocable at any time.
  3. The app routes orders carrying builder: {"b": address, "f": number}, which an API wallet can sign.
  4. The protocol charges the builder fee on each fill, on top of the exchange fee.
  5. The builder claims accrued fees through the referral rewards claim.

Which fills carry a builder fee

Section titled “Which fills carry a builder fee”

Only fees collected in the quote or collateral asset carry a builder fee:

Market Builder fee on Why
Perps buys and sells fees are paid in collateral
Spot sells only a spot buy pays its fee in the asset bought
Outcome markets sells only, as spot builders earn on sells carrying their code

f is in tenths of a basis point

Section titled “f is in tenths of a basis point”

f = 10 is 1 basis point (0.01 per cent); a percentage is f / 1000.

f Basis points Per cent Allowed on
1 0.1 0.001% perps and spot
10 1 0.01% perps and spot
100 10 0.1% perps and spot (perp maximum)
1000 100 1% spot only (spot maximum)

The numbers

Section titled “The numbers”
Parameter Value
Unit of f tenths of a basis point
Maximum f, perps 100 (0.1%)
Maximum f, spot 1000 (1%)
Active approvals per user at most 10
Builder’s minimum perps account value 100 USDC
Builder’s account mode standard
f above the approval whole order rejected

What an app charges you

Section titled “What an app charges you”
  • Each fill’s fee already includes the builder fee; builderFee shows the builder’s part.
  • Your approval is a ceiling: the app picks f per order, up to it and the protocol cap.
  • approvedBuilders lists whom you approved; maxBuilderFee gives the ceiling for one builder.
  • The docs’ staking referral proposal page states that a builder code overrides a referral code for that order (referrals).

Approving and tagging orders

Section titled “Approving and tagging orders”

The approval is user-signed (EIP-712 primary type HyperliquidTransaction:ApproveBuilderFee) from the master key. maxFeeRate is a percent string: "0.1%" approves up to f = 100.

{
  "type": "approveBuilderFee",
  "hyperliquidChain": "Mainnet",
  "signatureChainId": "0xa4b1",
  "maxFeeRate": "0.1%",
  "builder": "0x...",
  "nonce": 1700000000000
}

Orders carry builder after grouping (orders). Key order (type, orders, grouping, builder) is part of the signed hash (signing), and the builder address must be lowercase: a checksummed one recovers the wrong signer.

{
  "type": "order",
  "orders": [{ "a": 0, "b": true, "p": "100000", "s": "0.01", "r": false, "t": { "limit": { "tif": "Gtc" } } }],
  "grouping": "na",
  "builder": { "b": "0x...", "f": 50 }
}
  • {"type": "maxBuilderFee", "user", "builder"} returns the ceiling in tenths of a basis point, 0 if never approved; check it before sending.
  • From a contract, CoreWriter action 12 approves a builder with maxFeeRate as a uint64 in tenths of a basis point.

Observing builder revenue

Section titled “Observing builder revenue”
Source What it gives
builderFee on each fill (userFills, WebSocket fills) the builder’s part of that fill’s fee; absent when 0
referral info request, builderRewards the builder’s accumulated fees
Daily builder fill files every fill carrying the code, as LZ4-compressed CSV at builder_fills/{builder_address}/{YYYYMMDD}.csv.lz4 on Hyperliquid’s stats data host; the address must be lowercase

Builder volume depends on the lens. A code can sit on a match’s taker row or maker row, so count every row carrying it or only taker rows, and say which (measuring Hyperliquid); settlement fills never carry one.

Unit and approval pitfalls

Section titled “Unit and approval pitfalls”
  • One SDK limits a user to 3 approved builders; the docs allow 10.
  • A builder address that leaves standard mode stops accruing builder fees.
  • Approvals are per network: a testnet approval does not exist on mainnet.

For the exchange fee underneath, see Fees, tiers and rebates; for fee sharing tied to users, Referrals.