bbo

Stream real-time best bid and offer for a coin.

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

{"type": "bbo", "channel": "bbo"}

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

Stream the best bid and offer (top-of-book) for a single coin. Updated on change (only sent when the best bid or ask changes). This is the most bandwidth-efficient way to track live prices.

For deeper orderbook data, use l2Book. For incremental diffs, use l2BookDiff.

Subscribe

{
    "method": "subscribe",
    "subscription": {
        "type": "bbo",
        "coin": "BTC"
    }
}

Parameters:

Parameter	Type	Required	Description
coin	string	No	Coin symbol (e.g., "BTC", "ETH"). One subscription per coin. Omit to subscribe to all coins (requires add-on, see below).
marketTypes	string[]	No	All-coins only. Filters delivery by market type — see All-coins BBO. Rejected if combined with coin.

All-coins BBO (add-on)

Omit the coin field to receive BBO updates for every market in a single subscription:

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

This requires the bboAll add-on on your API key. Without it the subscription will be rejected.

The optional marketTypes filter restricts the firehose to specific market types. Each entry is "perp", "spot", "outcome", or the wildcard "*" (alone) for "every type the server currently tracks." Omitting the field 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 all-coins subscribe with a different marketTypes value replaces the previous filter rather than coexisting with it. Per-coin BBO subscriptions coexist independently with the all-coins subscription.

Unsubscribe

{
    "method": "unsubscribe",
    "subscription": {
        "type": "bbo",
        "coin": "BTC"
    }
}

Update data format

Each message contains the best bid and best ask for the subscribed coin:

{
    "type": "bbo",
    "channel": "bbo",
    "seq": 5,
    "cursor": "0",
    "data": {
        "coin": "BTC",
        "time": 1704067200000,
        "bbo": [
            {"px": "70325", "sz": "12.5", "n": 3},
            {"px": "70326", "sz": "8.3", "n": 2}
        ]
    }
}

The bbo array always contains exactly 2 elements: [best_bid, best_ask]. If a side is empty (no bids or no asks), that element is null.

Field reference

Field	Type	Description
coin	string	Market symbol
time	number	Block timestamp (milliseconds since epoch)
bbo	array	[best_bid, best_ask] — each is an L2 level or null
bbo[].px	string	Price as decimal string
bbo[].sz	string	Total size at this price level
bbo[].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: 'bbo', coin: 'BTC' }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.channel === 'bbo') {
        const { coin, time, bbo } = msg.data;
        const [bid, ask] = bbo;
        console.log(`${coin}: bid=${bid?.px} ask=${ask?.px}`);
    }
});

Python

import websocket
import json
import os

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

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "bbo", "coin": "BTC"}
        }))
    elif msg['type'] == 'ping':
        ws.send(json.dumps({'type': 'pong'}))
    elif msg.get('channel') == 'bbo':
        d = msg['data']
        bid, ask = d['bbo']
        print(f"{d['coin']}: bid={bid['px'] if bid else 'n/a'} ask={ask['px'] if ask else 'n/a'}")

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. An invalid coin returns invalid_coin_names and names the rejected value. A well-formed inactive name succeeds with an inactive_coins warning instead of silently producing no data.

1. Rate limit exceeded - Too many BBO subscriptions for your tier

2. Permission denied - All-coins BBO requires the bboAll add-on