l2BookDiff

Stream real-time L2 orderbook diffs (incremental updates) per block.

Every live data message includes both routing identifiers with the same value:

{"type": "l2BookDiff", "channel": "l2BookDiff"}

Other payload fields are omitted above. Existing clients may continue routing on either field.

New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

Stream incremental L2 orderbook changes as they happen. Each message contains all changed price levels across all subscribed coins for a single block, making this far more bandwidth-efficient than full snapshots.

For full snapshots, use l2Book. For just top-of-book, use bbo.

Subscribe

{
    "method": "subscribe",
    "subscription": {
        "type": "l2BookDiff",
        "coins": ["ETH", "BTC"]
    }
}

Parameters:

Parameter	Type	Required	Description
coins	string[]	No	Coins to subscribe to. Omit for all markets (requires ws:l2BookDiffAll permission).
marketTypes	string[]	No	All-markets only. Filters delivery by market type — see All-markets filter. Rejected if combined with coins.

All-markets filter

When coins is omitted, the optional marketTypes field restricts the firehose to specific market types. Each entry is "perp", "spot", "outcome", or the wildcard "*" (alone) for "every type the server currently tracks":

{
    "method": "subscribe",
    "subscription": {
        "type": "l2BookDiff",
        "marketTypes": ["perp", "outcome"]
    }
}

Omitting marketTypes defaults to ["perp"] — outcome and spot markets do not appear unless you opt in. The default never grows; new market types must be added to your marketTypes array explicitly. Pass ["*"] to auto-opt-in to future types.

A second subscribe with a different marketTypes value replaces the previous filter rather than coexisting with it.

Unsubscribe

{
    "method": "unsubscribe",
    "subscription": {
        "type": "l2BookDiff",
        "coins": ["ETH", "BTC"]
    }
}

Update data format

Each message contains all changed levels for your subscribed coins in a single block. A message is sent only for blocks that change something you're subscribed to — quiet blocks are skipped, so height is sparse (not contiguous). See Sequencing and gap detection. Levels with sz: "0" indicate that price level has been removed from the book.

{
    "type": "l2BookDiff",
    "channel": "l2BookDiff",
    "seq": 42,
    "cursor": "782007304:1704067200000",
    "data": {
        "height": 782007304,
        "time": 1704067200000,
        "diffs": [
            {
                "coin": "ETH",
                "epoch": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "seq": 108,
                "prev_seq": 107,
                "levels": [
                    [
                        {"px": "3245.5", "sz": "12.4", "n": 3},
                        {"px": "3244.0", "sz": "0", "n": 0}
                    ],
                    [
                        {"px": "3246.0", "sz": "8.1", "n": 2}
                    ]
                ]
            },
            {
                "coin": "BTC",
                "epoch": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "seq": 55,
                "prev_seq": 54,
                "levels": [
                    [{"px": "68605", "sz": "96.9", "n": 5}],
                    []
                ]
            }
        ]
    }
}

Resync signal

When the server detects a block-height gap (e.g., after a service restart, snapshot resync, or stream interruption), it emits a resync message. Discard the affected local book(s) and re-bootstrap from a REST snapshot. A height gap sends one resync per coin for every coin you're subscribed to (not just the coin that gapped) — a gap usually coincides with an epoch change, which invalidates every book.

{
    "type": "l2BookDiff",
    "channel": "l2BookDiff",
    "data": {
        "type": "resync",
        "coin": "ETH",
        "reason": "height_gap",
        "new_epoch": "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
    }
}

Also watch epoch yourself — don't rely on the resync message alone. The resync is driven by height-gap detection, and there is a narrow window (right after the server (re)connects to its diff stream) where a new epoch can appear on diffs without a preceding resync. A robust client treats any change in a coin's epoch — with or without a resync message — as "re-bootstrap that coin from a REST snapshot." See Sequencing and gap detection.

Field reference

Envelope fields (on every message):

Field	Type	Description
seq	number	Per-connection message counter — +1 on every message, across all coins. A jump > 1 means you missed a message. Not per-coin, and not related to the per-coin seq inside diffs (see Sequencing and gap detection).
cursor	string	Cursor for session reconnection replay (format: height:timestamp)

Batch data fields (data):

Field	Type	Description
height	number	Block height
time	number	Block timestamp (milliseconds since epoch)
diffs	array	Array of per-coin diffs (only coins with changes in this block)

Per-coin diff fields (each item in diffs):

Field	Type	Description
coin	string	Market symbol (e.g., "ETH", "BTC")
epoch	string	Server epoch (UUID) — changes on service restart
seq	number	Per-coin sequence number — increments by 1 for each diff for this coin
prev_seq	number	Previous per-coin sequence number (for gap detection)
levels	array	Tuple of [bids, asks] — only changed levels are included
levels[][].px	string	Price as decimal string
levels[][].sz	string	Size as decimal string ("0" means level removed)
levels[][].n	number	Number of orders at this level (0 when level removed)

Resync data fields (data when type is "resync"):

Field	Type	Description
type	string	"resync"
coin	string	Market symbol
reason	string	Why resync occurred (e.g., "height_gap")
new_epoch	string	The new server epoch after restart

Sequencing and gap detection

Every l2BookDiff message carries two independent sequence numbers plus a block height. They do different jobs — a robust client tracks both seqs:

Per message — envelope seq (connection health). The top-level seq increments by 1 on every message your subscription receives, across all coins. If it jumps by more than 1, you missed a message on this connection. It is local to your connection (two clients see different values for the same block) and says nothing about any single coin's book.

Per coin — data.diffs[].seq / prev_seq (book integrity). Each coin carries its own seq and prev_seq. For each coin, the next diff's prev_seq must equal the last seq you applied for that coin; a mismatch means you missed a diff for that coin — re-bootstrap it from l2BookDiffSnapshot. This value is global (identical for every client).

The two are not relatable — one envelope step bumps each included coin by 1, but which coins appear varies per block, so you cannot derive one from the other. Track them separately.

height (block position — sparse). data.height is the block height. Messages are sent only for blocks that change something you're subscribed to, so height skips blocks; gaps are normal, not a loss. Never use height + 1 as a completeness check — use the envelope seq for that. height is for aligning a REST snapshot only (discard diffs where height <= snapshot.height).

Field	Location	Scope	Gapless?	Use it to detect
seq	top-level (envelope)	per connection	yes — +1 per message	a dropped message
seq / prev_seq	data.diffs[]	per coin (global)	yes — per coin	a missed diff for that coin
height	data	block	no — sparse	(snapshot alignment only, not completeness)

Building a local orderbook

Align the snapshot to the stream on height (always present and shared by both), then use the per-coin seq/prev_seq for ongoing gap detection — see Sequencing and gap detection.

1. Subscribe to l2BookDiff for your coin(s) — start buffering messages.

2. Fetch snapshot via the REST l2BookDiffSnapshot endpoint. Note height, epoch, and the per-coin seq.

3. Discard already-applied diffs: drop any buffered batch whose data.height <= snapshot.height.

4. Verify epoch: every remaining diff's epoch must equal the snapshot's epoch. A different epoch means the server restarted after the snapshot — re-fetch and restart from step 1.

5. Apply remaining diffs in height order. The first diff for each coin should have prev_seq == snapshot.seq (the per-coin seq, not the envelope seq):

   • For each level in bids and asks:

     • If sz is "0", remove that price level.

     • Otherwise, upsert the price level with the new sz and n.

6. Ongoing gap detection: per coin, check prev_seq == your last applied seq for that coin on each diff; on a mismatch, re-bootstrap that coin. Optionally watch the envelope seq for dropped messages.

7. Resync: if you receive a resync message, discard local state and re-bootstrap from step 1.

Examples

Python (SDK)

import asyncio
from hydromancer_sdk import L2BookClient

def on_update(client, height):
    for coin in client.get_coins():
        book = client.get_book(coin)
        bid = book.best_bid()
        ask = book.best_ask()
        print(f"{coin} @ {height}: {bid.px if bid else 'n/a'} / {ask.px if ask else 'n/a'}")

async def main():
    client = L2BookClient(coins=["ETH", "BTC"], on_update=on_update)
    await client.run()

asyncio.run(main())

JavaScript

const WebSocket = require('ws');

const ws = new WebSocket(`wss://api.hydromancer.xyz/ws?token=${process.env.HYDROMANCER_API_KEY}`);

// Per-coin state: { epoch, seq }
const coinState = {};

ws.on('message', (raw) => {
    const msg = JSON.parse(raw);

    if (msg.type === 'connected') {
        ws.send(JSON.stringify({
            method: 'subscribe',
            subscription: { type: 'l2BookDiff', coins: ['ETH', 'BTC'] }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ method: 'pong' }));
    } else if (msg.type === 'l2BookDiff') {
        const batch = msg.data;

        // Handle resync
        if (batch.type === 'resync') {
            console.log(`Resync for ${batch.coin}: ${batch.reason}`);
            delete coinState[batch.coin];
            return;
        }

        for (const diff of batch.diffs) {
            // Check for gaps
            const state = coinState[diff.coin];
            if (state && (diff.epoch !== state.epoch || diff.prev_seq !== state.seq)) {
                console.log(`Gap for ${diff.coin}, re-bootstrapping`);
                delete coinState[diff.coin];
                continue;
            }

            coinState[diff.coin] = { epoch: diff.epoch, seq: diff.seq };

            const [bidChanges, askChanges] = diff.levels;
            console.log(`${diff.coin} @ ${batch.height}: ${bidChanges.length} bid, ${askChanges.length} ask changes`);
        }
    }
});

Python (raw)

import websocket
import json
import os

coin_state = {}

def on_message(ws, message):
    msg = json.loads(message)

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "method": "subscribe",
            "subscription": { "type": "l2BookDiff", "coins": ["ETH", "BTC"] }
        }))
    elif msg['type'] == 'ping':
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'l2BookDiff':
        batch = msg['data']

        if batch.get('type') == 'resync':
            print(f"Resync for {batch['coin']}: {batch['reason']}")
            coin_state.pop(batch['coin'], None)
            return

        for diff in batch['diffs']:
            coin = diff['coin']
            state = coin_state.get(coin)
            if state and (diff['epoch'] != state['epoch'] or diff['prev_seq'] != state['seq']):
                print(f"Gap for {coin}, re-bootstrapping")
                del coin_state[coin]
                continue

            coin_state[coin] = {'epoch': diff['epoch'], 'seq': diff['seq']}
            bid_changes, ask_changes = diff['levels']
            print(f"{coin} @ {batch['height']}: {len(bid_changes)} bid, {len(ask_changes)} ask changes")

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

Common errors

The subscription feedback and warning shapes are documented in the WebSocket overview. Invalid names are rejected together, for example invalid coin name(s): ["BTC-USD","ETH USD"]. More than 200 names in one request returns too_many_coins with requested and maximum details. A well-formed inactive name succeeds with an inactive_coins warning instead of silently producing no data.

1. Too many coins - A request may contain at most 200 names; tier limits may be lower

2. Subscribing to all markets requires permission - Needs ws:l2BookDiffAll add-on

3. Rate limit exceeded - Reduce subscription frequency

4. Authentication failed - Check API key