l2Book

Stream real-time L2 orderbook snapshots per coin.

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, or 20 (default).
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": "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.

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

Common errors

1. Too many coins - Reduce number of coins or upgrade tier

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, or 20

6. Rate limit exceeded - Reduce subscription frequency