Hyperliquid data feeds: every real-time stream, explained

Two ways to stream Hyperliquid

Start honest: the official websocket at api.hyperliquid.xyz is free and fine for a lot of jobs. One bot, one coin, a book and a trade stream — use it, skip the rest of this page.

Our feeds exist for everything past that point. They're wire-compatible — an HL client sending the native coin: "BTC" shape works as-is — and they add what builders kept asking us for:

• Multi-coin subscriptions — coins: ["BTC", "ETH", "xyz:SP500"] in one subscription instead of one socket dance per market.
• All-market firehoses — every coin on the exchange, one subscription.
• Four orderbook latency tiers — from L4 with user addresses down to aggregated display books.
• Streams the official API doesn't have — every TP/SL order, every TWAP, every ledger event on the exchange.
• Reconnection that doesn't lose data — gap-free sequence numbers and cursor-based replay.

Quick start: live trades in twenty lines

import websocket, json, os

def on_message(ws, message):
    msg = json.loads(message)
    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "type": "subscribe",
            "subscription": {"type": "trades", "coins": ["BTC", "ETH"]}
        }))
    elif msg['type'] == 'ping':
        ws.send(json.dumps({'type': 'pong'}))   # answer pings or get disconnected
    elif msg['type'] == 'trades':
        for t in msg['trades']:
            buyer, seller = t['users']
            print(f"{t['coin']} {t['side']} {t['sz']}@{t['px']}  buyer={buyer} seller={seller}")

ws = websocket.WebSocketApp(
    f"wss://api.hydromancer.xyz/ws?token={os.environ['HYDROMANCER_API_KEY']}",
    on_message=on_message,
)
ws.run_forever()

Wait for connected, subscribe, answer pings. That's the whole protocol.

The trade feed

Each message is a batch of WsTrade objects — one per matched (buyer, seller) pair, batched per block. The shape matches Hyperliquid exactly, which means it also inherits HL's one genuinely confusing field, so let's spell it out:

• side is the taker's side. "B" means the taker bought; "A" means the taker sold.
• users is always [buyer, seller]. The taker is users[0] when side="B" and users[1] when side="A".
• tid is unique within (coin, time) — for a globally unique trade id, key on (block_time, coin, tid).

Coin strings cover the whole exchange: "BTC" for perps, "xyz:SP500" for HIP-3 venues, "@107" for spot.

One gotcha worth knowing before you hit it: all trades messages share a single channel, so a connection holds one trades subscription. Watching several coins means one subscription with a coins array — not several subscriptions. Omit the filter entirely and you get the all-coins firehose (ws:allTrades add-on).

The orderbook feeds: pick your latency tier

“Stream the Hyperliquid orderbook” means four different things depending on what you're building. We publish the tradeoffs:

l2Book ships every block (~70ms) at 1, 10, 20, or 50 levels per side, with optional price aggregation — nSigFigs 2–5, plus a mantissa snap. With nSigFigs: 5, mantissa: 2, a bid at 70325 becomes 70324 and an ask at 70325 becomes 70326: bids round down, asks round up, always against you, never flattering the spread.

{
    "method": "subscribe",
    "subscription": { "type": "l2Book", "coins": ["BTC"], "nSigFigs": 5, "mantissa": 2 }
}

The all-markets firehose deserves its own paragraph, because it's where bandwidth goes to die if you do it wrong. Omit coins and you get every market — filtered by marketTypes ("perp", "spot", "outcome", or "*" to auto-opt-in to whatever ships next; the default is perps only and never silently grows). Then set pushMode: "delta": a full snapshot of every coin once on subscribe, then only the coins that changed each block. Same data as "full" mode for ~80% less bandwidth. Each delta message is still a complete snapshot for the coins it contains — overwrite your local book per coin, no diff-merging logic needed.

{
    "method": "subscribe",
    "subscription": { "type": "l2Book", "marketTypes": ["perp"], "pushMode": "delta" }
}

Streams that don't exist anywhere else

Three channels marked 💧 in our docs — not part of the original Hyperliquid API, added because builders needed them:

• tpslUpdates — every TP/SL trigger order on the exchange, streamed as add / remove diffs per block. Trigger orders are immutable, so the state machine is trivial: an order appears, then it terminates (triggered, canceled, siblingFilledCanceled, liquidatedCanceled…). This is how you watch stop-loss walls form in real time.
• allTwapStatusUpdates — every TWAP on the exchange through its lifecycle: activated, finished, terminated, error, with executed size and notional as it fills. Large algorithmic flow, visible while it's happening instead of after.
• allUserNonFundingLedgerEvents — exchange-wide ledger stream: deposits, withdrawals, transfers, vault flows, liquidation events, borrow/lend, and (opt-in) staking. Twenty-plus delta types. One subscription replaces the polling loop behind most flow dashboards.

If it's happening on Hyperliquid right now, there's a channel for it.

Built for reconnects

Feeds are only as good as their failure behavior, so the semantics are explicit:

• Every message carries a per-subscription seq, and it's gap-free. A jump in seq means you lost a message — no guessing.
• Sessions replay from a cursor on reconnect. Replay and live can overlap by design; each stream documents its dedup key — (time, txIndex, role) for ledger events, (time, txIndex) for TWAPs — so exactly-once processing is a three-line check, not a research project.
• The server never starts a delta book stream without first delivering the full snapshot. If it can't, the subscribe is rejected with a retryable error instead of leaving you with a silently incomplete book.

Official websocket vs Hydromancer feeds

The latency figures above are our published numbers, and the wire compatibility is checkable in an afternoon: point your existing HL client at our endpoint and diff the streams.

What about historical data?

Feeds are for now. Everything before now — every fill, 1-second candle, position snapshot — lives in Reservoir, our free S3 archive. Full walkthrough: How to get Hyperliquid historical data — for free. The common pattern is both: backfill from the archive, then subscribe and dedupe at the seam.

FAQ