l2Book

Stream real-time L2 orderbook snapshots per coin.

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

{"type": "l2Book", "channel": "l2Book"}

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

Stream L2 orderbook snapshots at configurable depth. Sent every block (~70ms blocks). Supports optional price aggregation via significant figures and mantissa parameters.

For single-coin subscriptions, data is a single snapshot object. For multi-coin subscriptions, data is an array of snapshot objects batched per block.

Choosing the right orderbook stream

Stream	Latency	Best for
l4BookUpdates	Fastest	HFT, market making — lowest latency, includes user address per level
l2BookDiff	~2ms after L4	Building local orderbooks — low bandwidth, client maintains state
bbo	Same as l2Book	Price tracking — minimal bandwidth
l2Book (raw)	~5ms after L4	Stateless consumers — every message is a complete snapshot
l2Book (aggregated)	~15ms after L4	Display/charting — slightly slower than raw because of aggregations

Subscribe

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

Parameters:

Parameter	Type	Required	Description
coins	string[]	No	Coins to subscribe to. Omit for all markets (requires permission).
nSigFigs	number	No	Aggregate price levels to N significant figures (2-5). Bids round down, asks round up.
mantissa	number	No	Snap to mantissa step (2 or 5). Only valid when nSigFigs=5.
nLevels	number	No	Number of levels per side: 1 (BBO), 10, 20 (default), or 50. 50 is allowed on per-coin/multi-coin subs; on the all-markets firehose it requires pushMode: "delta".
marketTypes	string[]	No	All-markets only. Filters delivery by market type — see All-markets filter. Rejected if combined with coins.
pushMode	string	No	Delivery cadence for the all-markets firehose: "delta" (recommended) or "full" (current default) — see Push modes.

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": "l2Book",
        "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.

Push modes

For the all-markets firehose (coins omitted), pushMode sets delivery cadence (raw and aggregated alike). It has no effect on single- or multi-coin subscriptions — those already send a coin only when it changes.

Use "delta" — same data as "full" for ~80% less bandwidth. "full" re-sends every coin every block and stays the default only for backward compatibility while consumers migrate.

Mode	Behavior
"delta" (recommended)	Full snapshot of all coins once on subscribe, then only the coins that changed each block. Keep a local book keyed by coin.
"full" (current default)	Complete snapshot for every coin every block. Legacy; being phased out.

nLevels: 50 is available on per-coin and multi-coin subscriptions directly, and on the firehose in "delta" mode.

In "delta" mode each message is still a complete snapshot for the coins it contains — there are no incremental level diffs. A client simply overwrites its stored book for each coin it receives. Coins that never change after subscribe are covered by the initial snapshot. The per-subscription seq is gap-free, so a seq jump signals a lost message — reconnect to receive a fresh full snapshot and resync. (For true per-level diffs and the lowest bandwidth, use l2BookDiff instead.)

The server never starts a delta stream without first sending that initial snapshot; in the rare case it can't be produced at subscribe (e.g. briefly during an internal resync), the subscribe is rejected with a retryable error — resubscribe.

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

Aggregation example:

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

With nSigFigs=5, mantissa=2, prices are rounded to 5 significant figures then snapped to the nearest multiple of 2 at the last digit. Bids round down, asks round up. For example, bid 70325 becomes 70324, ask 70325 becomes 70326.

Unsubscribe

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

Update data format

For single-coin subscriptions, data is a single snapshot object (with coin, time, levels). For multi-coin or all-markets subscriptions, data is an array of snapshot objects batched per block.

When the subscription includes aggregation parameters, the response includes nSigFigs and (if applicable) mantissa so clients can distinguish messages from multiple concurrent l2Book subscriptions at different aggregation levels.

Single-coin subscription (raw):

{
    "type": "l2Book",
    "channel": "l2Book",
    "seq": 15,
    "cursor": "0",
    "data": {
        "coin": "ETH",
        "time": 1704067200000,
        "levels": [
            [
                {"px": "3245.5", "sz": "12.4", "n": 3},
                {"px": "3244.0", "sz": "8.7", "n": 5},
                {"px": "3243.5", "sz": "25.1", "n": 8}
            ],
            [
                {"px": "3246.0", "sz": "6.2", "n": 2},
                {"px": "3247.5", "sz": "15.3", "n": 4},
                {"px": "3248.0", "sz": "9.8", "n": 6}
            ]
        ]
    }
}

Single-coin subscription (aggregated, nSigFigs=5, mantissa=2):

{
    "type": "l2Book",
    "channel": "l2Book",
    "nSigFigs": 5,
    "mantissa": 2,
    "seq": 15,
    "cursor": "0",
    "data": {
        "coin": "BTC",
        "time": 1704067200000,
        "levels": [
            [
                {"px": "68604", "sz": "96.9", "n": 5},
                {"px": "68602", "sz": "42.1", "n": 3}
            ],
            [
                {"px": "68606", "sz": "15.3", "n": 4},
                {"px": "68608", "sz": "9.8", "n": 6}
            ]
        ]
    }
}

Multi-coin subscription:

{
    "type": "l2Book",
    "channel": "l2Book",
    "seq": 15,
    "cursor": "0",
    "data": [
        {
            "coin": "ETH",
            "time": 1704067200000,
            "levels": [
                [{"px": "3245.5", "sz": "12.4", "n": 3}],
                [{"px": "3246.0", "sz": "6.2", "n": 2}]
            ]
        },
        {
            "coin": "BTC",
            "time": 1704067200000,
            "levels": [
                [{"px": "68605", "sz": "96.9", "n": 5}],
                [{"px": "68610", "sz": "42.1", "n": 3}]
            ]
        }
    ]
}

Field reference

Envelope fields (on every message):

Field	Type	Description
seq	number	Per-subscription sequence number
cursor	string	Always "0" — l2Book is stateless (every message is a complete snapshot, no replay)
nSigFigs	number	Present only on aggregated subscriptions. Echoes the nSigFigs value from the subscribe request.
mantissa	number	Present only when the subscribe request included mantissa. Echoes the value.

Per-coin data fields (each item in data):

Field	Type	Description
coin	string	Market symbol (e.g., "ETH", "BTC")
time	number	Block timestamp (milliseconds since epoch)
levels	array	Tuple of [bids, asks]. Bids sorted descending, asks ascending.
levels[][].px	string	Price as decimal string
levels[][].sz	string	Total size at this price level as decimal string
levels[][].n	number	Number of orders at this price level

Examples

JavaScript

const WebSocket = require('ws');

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

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

    if (msg.type === 'connected') {
        ws.send(JSON.stringify({
            method: 'subscribe',
            subscription: {
                type: 'l2Book',
                coins: ['ETH', 'BTC']
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'l2Book') {
        const { coin, time, levels } = msg.data;
        const [bids, asks] = levels;
        const bestBid = bids[0]?.px || 'n/a';
        const bestAsk = asks[0]?.px || 'n/a';
        console.log(`${coin} @ ${new Date(time).toISOString()}: bid=${bestBid} ask=${bestAsk} (${bids.length}/${asks.length} levels)`);
    }
});

Python

import websocket
import json
import os
from datetime import datetime, timezone

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

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {
                "type": "l2Book",
                "coins": ["ETH", "BTC"]
            }
        }))
    elif msg['type'] == 'ping':
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'l2Book':
        d = msg['data']
        bids, asks = d['levels']
        best_bid = bids[0]['px'] if bids else 'n/a'
        best_ask = asks[0]['px'] if asks else 'n/a'
        ts = datetime.fromtimestamp(d['time'] / 1000, tz=timezone.utc)
        print(f"{d['coin']} @ {ts.isoformat()}: bid={best_bid} ask={best_ask} ({len(bids)}/{len(asks)} levels)")

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:l2BookAll add-on

3. Invalid nSigFigs value - Must be 2, 3, 4, or 5

4. Invalid mantissa value - Must be 2 or 5, only valid with nSigFigs=5

5. Invalid nLevels value - Must be 1, 10, 20, or 50. On the all-markets firehose, 50 requires pushMode: "delta".

6. Rate limit exceeded - Reduce subscription frequency

7. l2Book snapshot not ready, please resubscribe - Retryable. A pushMode: "delta" firehose subscribe arrived while the initial snapshot couldn't be produced (e.g. during an internal resync). Resubscribe.