Protocol rule versions
Every rule the tools apply lives in @hl-tools/core as a versioned rule set with the date it was last checked against its primary sources. This page is generated from that metadata.
Asset IDs & coin names
Perps: index in meta.universe. Spot: 10000 + spotMeta.universe[].index (the explicit index, which is not the array position on either network). HIP-3: 100000 + perpDexIndex × 10000 + index in that dex's universe. HIP-4 outcomes: encoding = 10 × outcome + side; coin '#<encoding>', token '+<encoding>', asset ID 100000000 + encoding. Spot coins are 'PURR/USDC' or '@<index>'. Token index, spot index and asset ID differ, and differ between mainnet and testnet.
Changelog
- 1.1.02026-10-19An outcome share sits among an account's spot balances under its token name '+<encoding>' (seen on testnet). Its name: an outcome or question named 'template:<id>' is that template's name from `outcomeTemplates`, filled with the description's key:value pairs; a question's outcome is read with its question; a side named 'template:<text>' is filled the same way.
- 1.0.02026-09-28Perp, spot, HIP-3 and HIP-4 formulas. Spot universe normalised by explicit `index` after observing position ≠ index on both networks.
Tick & lot size
Prices: at most 5 significant figures and at most MAX_DECIMALS − szDecimals decimal places (MAX_DECIMALS = 6 for perps, 8 for spot and outcomes). Integer prices are always valid regardless of significant figures. Sizes: at most szDecimals decimal places. Signed numbers must have trailing zeros removed.
Changelog
- 1.0.02026-09-28Initial encoding of perp/spot price and size rules.
- 1.1.02026-09-28HIP-3 dexes use perp MAX_DECIMALS; HIP-4 outcomes use spot MAX_DECIMALS.
Order types, grouping & limits
Limit TIFs (Gtc/Ioc/Alo), trigger orders (tp/sl, isMarket, triggerPx), grouping (na/normalTpsl/positionTpsl, priority {p}), reduce-only, cloid format, builder fee units, minimum notional, open-order limits and cancel `f` flag rules.
Sources
Changelog
- 1.0.02026-09-28Initial encoding, including priority grouping and cancel `f` flag.
Signing schemes
Two schemes. L1 actions: keccak256(msgpack(action) ‖ nonce(u64 BE) ‖ vault marker [‖ vault address] [‖ 0x00 ‖ expiresAfter(u64 BE)]) becomes `connectionId` of an EIP-712 `Agent{source,connectionId}` message in domain Exchange/1/chainId 1337. User-signed actions: the action fields themselves are an EIP-712 `HyperliquidTransaction:*` message in domain HyperliquidSignTransaction/1/chainId = signatureChainId. Nonces must be within (T − 2 days, T + 1 day) and unique among the signer's 100 highest.
Sources
Changelog
- 1.0.02026-09-28L1 + 16 user-signed action types; vectors checked against hyperliquid-python-sdk 0.24.0.
Native multi-sig
A multi-sig user is an ordinary account whose own key can no longer send; up to 10 authorized users sign, a leader (an authorized user, or a funded API wallet of one) collects at least `threshold` distinct signatures and submits a `multiSig` envelope. Inner L1 actions are hashed as `[multiSigUser, outerSigner, action]` with the envelope's nonce, vault and expiry; inner user-signed actions gain `payloadMultiSigUser` and `outerSigner` after `hyperliquidChain`. The leader signs `HyperliquidTransaction:SendMultiSig{hyperliquidChain, multiSigActionHash, nonce}` over the envelope with inner signatures trimmed. Only the leader's nonce set is used; the multi-sig user's rate limit is charged. An envelope Hyperliquid refuses still uses up its number for that leader, so a refused proposal has to be made again. An account's USDC sends (`usdSend`) are taken only in increasing order of their `time`: once a newer one is carried out, an older pending send or bridge withdrawal is refused. Every other kind of action is taken in any order.
Sources
Changelog
- 1.0.02026-10-07Envelope hashing, signer-set rules, nonce window, agent and leader behaviour verified on testnet (163 recorded requests).
- 1.1.02026-10-11USDC sends are ordered: after an account carried out a `usdSend`, a `usdSend` with an older `time` is refused with "Nonce already used.", whoever leads and whatever the destination (12 pairs recorded on testnet through multi-sig envelopes). `usdClassTransfer`, `spotSend` and `approveAgent` are taken in any order; a failed attempt does not move the mark. Not documented by Hyperliquid.
- 1.2.02026-10-11The order lab: 247 questions put to a plain account and to a multi-sig on testnet (fixtures/multisig/nonce-order.json), 27 kinds of action. Only `usdSend` is ordered, on a plain account exactly as through an envelope, and its mark stays with the account when it becomes a multi-sig or a plain account again. The mark is the highest `time` carried out: a send dated ahead shuts out every send dated earlier until the clock has passed it. A bridge withdrawal (`withdraw3`) older than the mark is refused the same way; whether a withdrawal moves the mark was not measured (no withdrawal is made in testing). `sendAsset`, `spotSend`, `usdClassTransfer`, approvals, staking, account settings and every L1 kind tried are taken in any order, before or after a send. The order check comes before the balance check. Separately: an envelope that was refused (threshold not met, a stranger's signature, an action that failed, a number outside the window) is answered "duplicate nonce" when sent again, so a refused proposal cannot be retried; and the leader's 100 highest numbers bound what it can still lead.
- 1.3.02026-10-12What an API wallet reaches, and who can be a signer (fixtures/multisig/agent-reach.json, plain-convert.json). An API wallet approved for an account, a multi-sig included, can with no signer deposit the account's USDC into a vault (`vaultTransfer`) and move it between the account's own balances (`agentSendAsset`); it cannot send to another account, and a user-signed action it signs counts as coming from the API wallet's own account. So "trades, cannot withdraw" was true but left out the vaults. As authorized users Hyperliquid accepts ordinary accounts, other multi-sig users and API wallet addresses that have received funds; it refuses an API wallet that never received funds, a vault and a sub-account. An account that is already a signer elsewhere can convert itself and keeps signing and leading for the others. The first conversion is accepted under any signing chain, and an account that never received funds cannot send it. Not measured: a vault other than the testnet HLP vault, an API wallet's vault withdrawal after the lock-up, sub-accounts.
- 1.4.02026-10-13Switching the account mode through an envelope (fixtures/multisig/mode-switch.json). For `userSetAbstraction`, Hyperliquid hashes the envelope with `abstraction` written as a one-letter code ("u" for unifiedAccount, "i" for disabled) while the posted action and the signers' own signatures keep the long name: a leader who signs the envelope as posted is answered "Invalid multi-sig outer signer". Not documented. To unified is taken with a position and resting orders open (the perps and spot USDC become one balance); back to manual is refused while anything is open ("Cannot disable unified account with open positions, open orders, or active TWAP orders") and taken otherwise, the USDC staying in spot. Asking for the mode the account is already in is accepted and changes nothing. Not measured: portfolio margin, the letter for any other mode.
- 1.5.02026-10-13The form of the inner action Hyperliquid hashes (fixtures/multisig/inner-form.json). Hyperliquid reads a multi-sig request, writes the inner action out in its own form (its fields in its own order, an address in lowercase) and checks every signature against that: the signers' and the leader's signatures made over the canonical form were accepted whatever form the body carried, and signatures made over the fields in another order or over an address in capitals were refused ("Invalid multi-sig outer signer" when the leader's was, "Invalid multi-sig inner signer" when only the signers' were). Measured with a vault deposit under the minimum, which is refused after the signatures are checked. So a pasted request is judged over the canonical action, as a proposal document always was (`requestAsJudged`). Not measured: a decimal string with trailing zeros inside a multi-sig request (a vault action has none).
Account modes, transfers and the activation fee
An account is in one mode (`userAbstraction`): `default` and `disabled` keep a perps and a spot balance apart, `unifiedAccount` has one balance, reported as spot. A manual account can send with `usdSend` (perps to perps), `spotSend` (spot to spot) and `sendAsset` (any pocket to any pocket). A unified account can send only with `sendAsset` from the spot balance. The receiver's mode never refuses a send: a manual receiver gets it in the pocket named, a unified one in its single balance. Sending to an address never used costs 1 USDC once: `usdSend` takes it out of the amount, `spotSend` and `sendAsset` charge it on top. Sending to an address in use costs nothing.
Sources
Used by
Changelog
- 1.0.02026-10-11Measured on testnet (fixtures/multisig/send-modes.json, activation-fee.json): three sender modes against three receiver modes for six ways of sending, own-account moves, a token that is not the collateral, the same through a multi-sig; and sends to addresses never used, per method. Beyond the docs: `default` behaves as `disabled`; in unified mode `usdSend`, `spotSend` and `usdClassTransfer` are switched off and `sendAsset` works only from spot; what a unified account can send is its spot total minus `hold`; the 1 USDC for a new address comes out of the amount for `usdSend` and on top for the others, from spot USDC when what is left there covers it and from perps otherwise. Not measured: portfolio margin, the discontinued DEX abstraction, mainnet.
- 1.1.02026-10-12Sends of an account to itself (fixtures/multisig/self-send.json): into the same balance every way is refused ("Cannot self-transfer." for usdSend and spotSend, "Invalid send" for sendAsset), on a plain account and through a multi-sig. Between a manual account's two balances a sendAsset to itself moves the money; on a unified account a sendAsset to itself from spot to perps is accepted and changes nothing.
- 1.2.02026-10-12A bridge withdrawal (withdraw3) pays the bridge's 1 USDC fee out of the amount: 2 USDC withdrawn, 1 USDC arrived on Arbitrum (seen on mainnet and on testnet, through a multi-sig). A withdrawal of exactly 1 USDC is refused with "Withdrawal is smaller than fee." (testnet); a smaller one was not sent and is taken to be refused the same way. The ledger row of a withdrawal carries the action's `time` times 1000 as its `nonce`, and a hash of its own that is not the action's.
- 1.3.02026-10-13A multi-sig account cannot move a token to HyperEVM (fixtures/multisig/evm-transfer.json, testnet): a spotSend or sendAsset to the token's own system address (0x2222…2222 for HYPE, 0x20 followed by the token index for the others) is refused with "Multi-sig user cannot transfer token to EVM", and one to another token's system address with "EVM transfer not configured". A plain account's spotSend of HYPE to 0x2222…2222 was accepted the same day. Not measured: usdSend to a system address, taken to be refused the same way.
- 1.4.02026-10-14A bridge withdrawal from a unified account comes out of its one balance, which Hyperliquid reports as spot USDC: 2 USDC withdrawn through a multi-sig on mainnet took spot USDC from 3 to 1 and left perps at 0 (fixtures/multisig/unified-withdrawal.json). Its ledger row names what arrives (`usdc`, 1) and the bridge's fee (`fee`, 1): what was requested is their sum.
Staking HYPE
HYPE is in one of three places: the spot balance, the staking balance, or staked with a validator. Three user-signed actions move it: `cDeposit` (spot to the staking balance), `tokenDelegate` (stake with a validator, or unstake) and `cWithdraw` (the staking balance back to spot). Amounts are integers with 8 decimals. A stake cannot be removed for a while after it is made, and adding to a stake starts that wait again for all of it. A return to spot waits in a queue and then lands by itself; at most five can wait at once. Hyperliquid accepts a stake with a validator that is jailed or outside the working set, and such a stake earns nothing.
Sources
Used by
Changelog
- 1.0.02026-10-12Measured on testnet through a multi-sig (fixtures/multisig/staking.json): all three actions go through the envelope, and the second step of a pair can follow the first within seconds (move in then stake, unstake then return, unstake from one validator then stake with another). Beyond the docs: adding to a stake restarts the lockup of everything staked with that validator; a stake removed completely leaves the list of delegations; a stake with a jailed or an inactive validator is accepted; the lockup ends sharply (refused 2 seconds before, accepted 1.5 seconds after); testnet's lockup is 2 minutes and its return queue 5 minutes. Seven refusals recorded word for word (rule set "errors" 1.8.0). From the docs and not measured: the mainnet lengths (1 day, 7 days). Not in the docs: the request that lists validators (`validatorSummaries`).
Vault deposits and withdrawals
A vault is an account a leader trades with; others deposit USDC into it and share its profit and loss. One action moves the money both ways: `vaultTransfer` with `isDeposit` and the amount as an integer of millionths of a dollar. It is an L1 action: it is signed as a hash under chain 1337, and it carries no number of its own. A deposit is taken from the perps balance (from the one balance of a unified account) and has to be at least 5 USDC; it cannot be withdrawn for a while, and adding to a deposit starts that wait again for all of it. A withdrawal arrives in the perps balance (the one balance of a unified account), less the leader's share of the profit.
Sources
Used by
Changelog
- 1.0.02026-10-13Measured on testnet through 2-of-3 multi-sigs, the inner signatures made as L1 hashes (fixtures/multisig/vaults.json, 17 requests). A deposit takes from what the perps balance can release, not from the account value and not from spot: in a manual account with the USDC in spot it is refused until some is moved to perps; in a unified account it takes from the one balance. Recorded word for word: "Vault deposits must be at least $5.", "Vault is closed.", "This vault does not accept deposits.", "Vault not registered: <address>", "Insufficient funds available to deposit." (the same text a staking deposit gets), "Cannot withdraw during lockup period after depositing." and "Insufficient vault equity for withdrawal". The HLP vault locked a deposit for exactly 96 hours and a user vault for 20 seconds on testnet; adding to a deposit moved the lockup of all of it. A withdrawal after the lockup came back less the leader's commission (a tenth of the profit in the vault used), and withdrawing everything left a fraction of a cent behind. Ledger rows: `vaultDeposit {vault, usdc}` and `vaultWithdraw {vault, user, requestedUsd, commission, closingCost, basis, netWithdrawnUsd}`. From the docs and not measured: a user vault's lockup on mainnet (1 day), HLP's on mainnet (4 days). Not measured: which refusal Hyperliquid names when two apply at once.
Rate-limit classes
Per-IP REST weight budget of 1200/min (exchange weight 1 + floor(batch/40); info weight 2, 20 or 60 plus per-item surcharges; explorer requests 40), WebSocket connection/subscription caps, 100 req/min on the public HyperEVM RPC, and per-address action budgets tied to traded volume.
Changelog
- 1.0.02026-09-28Initial encoding.
- 1.1.02026-10-08Explorer API requests (userDetails, txDetails, blockDetails) weigh 40 each; blockList adds 1 per block.
- 1.2.02026-10-13Measured on testnet, not in the docs (which say only that older blocks "may be weighted more heavily"). `txDetails` answers "More than 100 archived blocks queried in one day" once a network address has asked for about a hundred older transactions, and from then on for every hash that day, a transaction seconds old included; 130 look-ups of transactions under half an hour old went through before that. `userDetails` kept answering while `txDetails` was refused. It returns an account's newest 300 transactions (300 on mainnet too; 101 when first observed on 2026-10-08) and ignores `startTime`, `endTime`, `from`, `to`, `before`, `limit`, `offset` and `page`: there is no way to page further back, and Hyperliquid's own explorer page does not either.
Exchange error catalog
Documented order/cancel error strings with their historical-status codes, signing/deposit errors, HTTP-level failures (422 deserialisation, 429 rate limiting) and a small number of pattern-matched messages that are not in the docs (flagged as undocumented).
Sources
Changelog
- 1.0.02026-09-28Initial catalog.
- 1.1.02026-10-07Multi-sig errors (threshold, inner/outer signer, leader, signer-set rules, revert shape), nonce window messages with extracted bounds, network signature mismatch and unregistered vault — all recorded on testnet.
- 1.2.02026-10-09"Insufficient balance for withdrawal." — the answer to a usdSend larger than the withdrawable perps balance (recorded on testnet through a multi-sig envelope; the chain uses the withdrawal wording for sends too).
- 1.3.02026-10-11"Nonce already used." — the answer to a usdSend whose `time` is older than a usdSend the account has already carried out, even though that number was never used (recorded on testnet through multi-sig envelopes, with the same and with another leader). Not the leader's duplicate check, which reads "Invalid nonce: duplicate nonce N". Also "User has pending agent removal": a second API wallet removal sent a second after the first.
- 1.4.02026-10-11From the order lab (fixtures/multisig/nonce-order.json). "Nonce already used." is also the answer to a bridge withdrawal older than a carried-out send, and plain accounts get it like multi-sigs. A refused envelope uses up its number: "Multi-sig threshold not met" no longer says "resubmit". Replacing an API wallet counts as a removal for "User has pending agent removal". New: "Too many extra agents for cumulative volume traded", "Action disabled when unified account is active" (a usdSend from an account in unified mode), "Error withdrawing from bridge".
- 1.4.12026-10-11Unified account mode, measured on testnet: usdSend, spotSend and usdClassTransfer are all answered "Action disabled when unified account is active" (1.4.0 wrongly suggested a spot send), sendAsset works when its source is the spot balance, and with the perps balance as source it is answered "Unified account only supports sending assets through spot" (new entry).
- 1.5.02026-10-11Refusals met while measuring sends (fixtures/multisig/activation-fee.json, send-modes.json): "Usd transfer is smaller than fee." (a usdSend of 1 USDC or less to an address never used), "Insufficient USDC balance for token transfer gas." (neither balance can pay the 1 USDC for a new address), "Insufficient balance for token transfer" (a sendAsset above what the balance can release) and "Invalid token" (a token that is not the collateral sent into perps).
- 1.6.02026-10-12Recorded on testnet (fixtures/multisig/self-send.json, agent-reach.json, plain-convert.json): "Cannot self-transfer." (a usdSend or spotSend to the sender itself), "Invalid send" (a sendAsset to the sender itself into the same balance), "Multi-sig authorized user cannot be vault or sub-account", and "Agent can only send asset to same user or their sub-accounts." (an API wallet trying to send to another account).
- 1.7.02026-10-12Recorded on testnet through a multi-sig: "Withdrawal is smaller than fee." (a withdraw3 of exactly the bridge's 1 USDC fee).
- 1.8.02026-10-12Staking, recorded on testnet through a multi-sig (fixtures/multisig/staking.json): "Insufficient funds available to deposit." (moving more HYPE into staking than spot can release), "Insufficient balance to delegate" (staking more than the staking balance holds unstaked), "Unknown validator", "Cannot undelegate during lockup period after delegating or voting." (an unstake before the stake's lockup has ended, which a top-up restarts), "Insufficient balance to undelegate", "Insufficient balance to withdraw from CStaking" (returning more than is unstaked) and "Too many concurrent CStaking withdrawals" (a sixth return while five wait).
- 1.9.02026-10-13Recorded on testnet through a multi-sig (fixtures/multisig/evm-transfer.json): "Multi-sig user cannot transfer token to EVM" (a send to the token's own HyperEVM system address) and "EVM transfer not configured" (a send to another token's system address).
- 1.10.02026-10-13Recorded on testnet through a multi-sig: "Extra agent does not exist." (an approveAgent of the zero address, which removes an API wallet, under a name no API wallet of the account has).
- 1.11.02026-10-13Recorded on testnet through a multi-sig (fixtures/multisig/mode-switch.json): "Cannot disable unified account with open positions, open orders, or active TWAP orders" (a switch back to a manual account while anything is open; the same answer to userSetAbstraction and to userDexAbstraction).
- 1.12.02026-10-13Vaults, recorded on testnet through a multi-sig (fixtures/multisig/vaults.json): "Vault deposits must be at least $5.", "Vault is closed.", "This vault does not accept deposits.", "Vault not registered: <address>", "Cannot withdraw during lockup period after depositing." and "Insufficient vault equity for withdrawal". "Insufficient funds available to deposit." is also what a vault deposit gets when the perps balance cannot release that much, so its entry no longer speaks of staking alone (id `deposit-funds`, before `staking-deposit-funds`).
- 1.13.02026-10-19"Insufficient vault equity for withdrawal" was also the answer to a mainnet withdrawal of exactly the deposit's worth as `userVaultEquities` reported it (10.005691 USDC, while `vaultDetails` with the depositor's address said `maxWithdrawable` 10.005689). That worth sat above the deposit's precise value for 22 of 25 HLP depositors read the same day, while `maxWithdrawable` was always the precise value cut down to 6 decimals. The entry now names `maxWithdrawable` as the limit; it no longer advises reading `userVaultEquities`.
CoreWriter action encoding
sendRawAction(bytes) on 0x3333…3333. Byte 0 = encoding version (only 1 is defined), bytes 1–3 = big-endian action ID, remaining bytes = raw ABI encoding of the action's field tuple. The contract emits RawAction(address indexed user, bytes data); HyperCore processes it after the EVM block (orders and vault transfers are delayed a few seconds).
Sources
Changelog
- 1.0.02026-09-28Version 1 actions 1–13, 15–17. Units for limitPx/sz (1e8) and usdClassTransfer ntl (1e6) confirmed against live mainnet transactions.
HyperEVM read precompiles
Read precompiles at 0x…0800 upwards return HyperCore state as of EVM block construction. Inputs and outputs are raw ABI (no function selector). Gas = 2000 + 65 × (input_len + output_len); invalid inputs revert and consume all gas passed. Perp prices divide by 10^(6 − szDecimals), spot prices by 10^(8 − base szDecimals).
Used by
Changelog
- 1.0.02026-09-280x800–0x813. Addresses and output layouts verified by live eth_call on mainnet and testnet.
HyperEVM JSON-RPC & timing
The default RPC (rpc.hyperliquid.xyz/evm) serves eth_call, eth_getCode, eth_getBalance, eth_getStorageAt, eth_getTransactionCount and eth_estimateGas at the latest block only; eth_getLogs allows up to 4 topics and 50 blocks per query. Custom methods: eth_bigBlockGasPrice, eth_usingBigBlocks, eth_getSystemTxsByBlockHash/Number. Dual blocks: 1 s / 3M gas small blocks and 1 min / 30M gas big blocks.
Changelog
- 1.0.02026-09-28Initial encoding.
HyperEVM ↔ HyperCore transfers
EVM → Core: an ERC-20 Transfer(from, to, value) emitted by a token's linked contract with to = the token's system address (0x20…<token index>; HYPE is native, sent to 0x2222…2222) credits the from address on HyperCore with value ÷ 10^(weiDecimals + evmExtraWeiDecimals). The credit lands in the same L1 block, right after the EVM block, and appears in the recipient's userNonFundingLedgerUpdates as a spotTransfer whose user is the system address. A transfer HyperCore does not credit leaves no record on either side: the EVM receipt still says success. Core → EVM: sendAsset to the system address; a system transaction mints on the EVM in the next EVM block.
Sources
Used by
Changelog
- 1.0.02026-10-05Initial encoding, from tracing CoreDepositWallet.depositFor payouts on testnet: credited transfers appear 0.001–0.141 s after the block; dropped ones leave no ledger entry. Native HYPE sent to 0x2222…2222 emits no Transfer log and is not detected.
WebSocket channels & semantics
Subscribe with {method:'subscribe', subscription:{type,…}}; the server acks on channel 'subscriptionResponse'. No channel carries a sequence number or resume cursor: after a reconnect you re-subscribe and rebuild state from the next snapshot. Streaming user channels send a first message with isSnapshot: true. The server closes connections idle for 60 s; send {method:'ping'} to keep alive.
Changelog
- 1.0.02026-09-28Initial encoding of 20 channels.
- 1.1.02026-09-28trades: the first message replays recent trades without an isSnapshot flag (observed on mainnet, not in the docs); modelled as snapshot-then-deltas.
- 1.2.02026-10-11Two account channels added: userHistoricalOrders (not in the docs; observed on mainnet and testnet) and allDexsClearinghouseState. Recorded on testnet: clearinghouseState, openOrders and spotState are pushed again about every 5 s and at once when they change; their amounts are decimal strings; the history snapshots hold the newest 30 fills and the newest 30 order status entries. The documented cap of 10 distinct users per IP was not enforced (13 accepted on one connection, a 14th on a second).
Testnet faucet & account activation
The testnet faucet pays 1,000 mock USDC to an address that has deposited on mainnet. Sending USDC with `sendAsset` to an address that does not yet exist on HyperCore charges the sender a flat activation fee on top of the amount (a `usdSend` takes it out of the amount instead: see the transfers rule set). The faucet miner relies on both.
Changelog
- 1.0.02026-09-28Initial encoding.
- 1.0.12026-10-11Wording only: the fee is on top of the amount for `sendAsset`, which the faucet miner uses; measured per method in the transfers rule set.