Hyperliquid

Hyperliquid is transparent. Every trade names its buyer and seller, and any account’s positions and orders can be read. The recorder uses that to measure where real positions keep their take-profits, stops and liquidation prices, and what each trade did to open interest. Clients draw these as the Hyperliquid heatmaps and positioning footprints.

Recording runs for the coins in --hl-coins, by default BTC, ETH, SOL and HYPE. Pass --hl-coins "" to turn it off.

Why the recorder does it better

The desktop and browser can collect positions too, but only from samples. The recorder has three advantages:

How it works

Discovery

Every trade names both accounts. The recorder also seeds the leaderboard: about 47 000 accounts, of which those worth at least $50k (about 17 000) are seeded. Each account keeps a measure of its recent traded notional with a one-hour half-life.

Reading

The most overdue account is read first. Position reads repeat faster for larger exposure in the recorded coins and after the account traded:

Never-read accounts alternate with refreshes, largest first. Orders are read only for accounts holding a recorded coin, from every minute ($1M and up) to hourly, and less often after two empty reads.

Keeping positions current

With the complete stream, every trade after a read is applied to both accounts. Trades that arrive while a read is in flight are replayed onto its answer. If the websocket drops, every account is marked unsynced until it is read again, and the connection is retried with a back-off of up to 30 seconds.

Levels

Every 10 seconds each coin is sampled. Per price bucket (0.02 % of the price, rounded to a step that stays fixed per coin) the recorder sums the USD notional of:

Position TP/SL orders count the whole position; sized ones count at most the position. Triggers that cannot close the position, and levels more than 4× away from the mark, are ignored.

Samples become runs like the order-book heatmap. A run is cut when its bucket changes by more than 5 %, empties, reaches UTC midnight, or when sampling stopped for more than 5 minutes.

Footprints

Per minute and price row (0.005 % of the price), from the complete stream:

A flip counts as a close plus an open. Each minute also stores Hyperliquid’s open interest, the mark price, the tracked accounts’ long and short size, and the volume each figure covers.

Budgets

Hyperliquid documents 1 200 weight per minute per IP. Measured from a single machine:

• 3 000 clearinghouseState reads in 72 seconds passed.
• frontendOpenOrders passed at 2 per second for 30 seconds, and was refused (HTTP 429) after about 180 requests at 4 per second. A refusal lasted about 40 seconds.

The recorder’s defaults, 5 position reads and 1 order read per second, are about a third of what passed. A 429 empties the affected budget and pauses it for 60 seconds. Change them with --hl-state-per-min and --hl-orders-per-min.

Coverage

Coverage is the share of Hyperliquid’s open interest held by tracked accounts: the larger of tracked long and tracked short size, divided by open interest. It tells you how complete the maps are.

Measured over 15 minutes live with the recorder budgets on BTC, ETH, SOL and HYPE:

The largest accounts are read first, so coverage rises quickly and then the tail grows slowly.

Check live coverage with GET /v1/hl/status. The recorder also logs the same text once a minute.

Storage and serving

Each coin has its own directory under <dir>/hl/<COIN>/ with a fixed grid and day files of appended payloads. See Storage.

Answers for one hour are about 12 kB of levels and 2–4 kB of footprints per coin.

On the client

The data hub runs this recorder and serves its /v1/hl/ paths. A client on a hub (desktop or browser) loads the last 3 hours of a coin, refreshes the tail every 10 seconds and loads older history six hours per request as the chart scrolls back. If the hub answers 404 for a coin, the client hands that coin to its in-process collector.