04 · Trading & Exchange
Hyperliquid is the exchange boundary for native perpetuals and Market Bender-allowlisted HIP-3 markets. Dynamic discovery, typed conversion, signer-scoped nonces and reconciliation are implementation requirements—not footnotes.
One adapter, network-explicit transports
Pin @nktkas/hyperliquid behind Market Bender interfaces. Separate read-only info, exchange-action and subscription clients while reusing configured transports. Every client is constructed from explicit testnet/mainnet environment configuration; accounts, asset IDs, signer registrations and fixtures never cross networks.
Resolve metadata at runtime
- Fetch native perp metadata and the current DEX list.
- Fetch metadata for each supported builder-deployed DEX.
- Normalize canonical name, DEX prefix, tick/lot precision, collateral/quote, max leverage and status.
- Apply the Market Bender allowlist after discovery.
- Cache with network, metadata hash and observed timestamp; reject stale/unknown instruments.
Streams plus snapshot recovery
Subscribe to the needed mids/book/asset-context channels and user order/fill/funding streams. Heartbeats and connection state determine freshness. On reconnect, process the snapshot marker with stable event deduplication, then query info endpoints for orders, fills, positions and account state. A stream is low-latency evidence; reconciliation is account truth.
Intent → verdict → request → exchange → reconciliation
Supported MVP actions are GTC/IOC/ALO limit orders where verified by the adapter, cancel, modify only through a cancel/replace or supported atomic path, close and deterministic flatten. Unsupported exchange actions are absent from the tool schema.
Decimal-safe, deduplicated, exchange-reconciled
Store unique exchange trade/order identifiers. Rebuild positions from authoritative account state when stream gaps occur. A portfolio snapshot includes account value/equity, positions valued at approved marks, open orders/reserved exposure, realized and unrealized PnL, cumulative fees, funding payments, withdrawable balance, source timestamp and freshness. Never use binary floating point for financial equality or settlement.
Single writer per signer
Hyperliquid tracks nonce state per signer. Assign a fresh agent wallet to each trading process/account scope, generate nonces through an atomic single-writer sequencer, batch compatible actions deliberately and never reuse a deregistered address. On conflict, stop submissions and reconcile; rotating a signer is a master-authorized lifecycle, not an automatic retry.
Prove both market classes and every terminal action
- Record metadata fixtures and asset-resolution evidence for one native and one supported HIP-3 perp.
- Place, partially fill if controllable, cancel, close and verified flatten with recorded transaction/order/fill IDs.
- Disconnect subscriptions, recover snapshots and prove portfolio convergence.
- Exercise stale metadata, invalid precision, nonce collision, unknown response, fee and funding cases.
- Require an explicit production configuration/allowlist review; testnet success never authorizes mainnet.