Hyperliquid knowledge base

A reference to account entities on Hyperliquid (HL): the master wallet, agent/API wallet, sub-accounts, vaults, builder address, collateral modes (manual / Unified Account / legacy dex abstraction, portfolio margin), permissions, and address formats. Facts were verified against SDK @nktkas/hyperliquid 0.27.x and viem; items verified live have a date, and items taken from documentation are marked.

General pitfalls in developing trading bots on HL that do not fit the topics of orders, WS, limits, or accounts: number precision in JS, “not read” versus “empty,” replica lag, races, caches, remembered state, closes, restarts, duplicate processes, networking, and observability. Every rule includes the failure mechanism and how to prevent it.

A concise reference on API latency, per-IP limits, safe client shutdown, and telemetry. It contains no key-storage designs, process-specific configurations, scaling recipes, or strategy launch checklists.

How to correctly read the balance and equity of an HL account through the public info API (https://api.hyperliquid.xyz/info). Here, we explain the differences between numbers from different endpoints and UIs, which formula to use for what task (position sizing, risk-cap, display, protective triggers), and how to avoid misinterpreting broken readings as events on the account. Facts are verified with live queries; dates of verifications are noted, and information taken from documentation is marke…

1. Base HL perp tier: maker 1.5 bp (0.015%), taker 4.5 bp (0.045%). Verified through userFees on a fresh subaccount (2026-09-14). Tiers are calculated from 14-day volume. Maker 0 starts at $500M over 14 days. A rebate is granted only when the account's share exceeds 0.5% of the exchange's total maker volume. 2. Actual account rates come from info {type:'userFees', user} (weight 20): userAddRate is the maker rate, userCrossRate is the taker rate, and activeReferralDiscount is the referral discou…

Reference for reading account history on HL: userFills / userFillsByTime, fill fields, partial fills grouping, position reconstruction and PnL, TWAP slices, historicalOrders, openOrders / frontendOpenOrders, ledger, public dump builder fills, leaderboard and its blind spots.

A reference for HL historical data: what the public API returns (candles, account fills, funding), where its limits are, how to cache data for reproducible runs, and why it is difficult to build an honest backtest on HL.

A guide to HL market-data info requests (POST https://api.hyperliquid.xyz/info): market metadata, price and size precision, mid prices, order books, candles, HIP-3 dexes (xyz: and others), spot (@index), tokenized-equity trading hours, and delisted/isolated-only markets. Identifiers are preserved exactly as they appear in the API.

Order placement, types, tif, reduceOnly, native TP/SL, price and size rounding, minimums, exchange responses, cancellations, statuses, and rejections. SDK used in snippets: @nktkas/hyperliquid 0.27.x.

A reference for developers of bots and tools on HL: how to calculate load, avoid 429, retry without doubling a position, and decide when a second IP is needed. Figures come from HL documentation and measurements; measurements include dates.

A guide to risk management on Hyperliquid (HL): leverage (updateLeverage), cross and isolated margin, ROE and position margin, liquidation, the utilization ceiling and rejection loop, portfolio drawdown, unprotected “naked” positions, native exchange TP/SL versus software stops, reliable closing, and exit priority. Code examples target SDK @nktkas/hyperliquid 0.27.x. Collateral modes (Unified Account, portfolio margin, and dex abstraction) are covered in detail in accounts.md.

1. There are two endpoints for everything. POST https://api.hyperliquid.xyz/info (reads, body {type, ...}) and POST https://api.hyperliquid.xyz/exchange (signed actions). WS: wss://api.hyperliquid.xyz/ws. Testnet: the same paths at api.hyperliquid-testnet.xyz. Header: Content-Type: application/json. CORS permits calls directly from a browser (exact headers in §3.6). 2. Known-working stack (verified through 2026-09): @nktkas/hyperliquid 0.27.1 (prefer an exact pin, without ^), viem 2.50–2.52 (pr…

- TWAP executions (slices) do not appear in userFills / userFillsByTime. This is true with both aggregateByTime: true and false. They live in the separate info feed {"type":"userTwapSliceFills","user":"0x…"}. These are two distinct feeds, and the first does not contain the second. Verified live (2026-09-05). - Calculate account PnL, volume, and trading direction from the union of both feeds. If you look only at userFills, TWAP-executed volume disappears, distorting both account direction and Pn…

Reference guide to the WebSocket API of Hyperliquid (HL) for those who are writing trading tools: bots, account monitoring, and market-data clients. Facts are from working with a live socket; where a fact is taken from documentation and not re-verified, it is marked as such.

Practical knowledge about Hyperliquid (HL): API, SDK, accounts, balances, orders, TWAP, WebSocket, limits, fees, risk, historical data, backtesting limits, and API operational facts. This is hands-on HL API practice: mechanics, formulas, thresholds, and pitfalls. Every rule has a reason, and every fact verified live has a verification date.

Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). Attribution is required: credit “markpaper — Hyperliquid knowledge base”, link to the original and to the license, and indicate if changes were made.