Partial Order Book

Real-time order book snapshots with top levels of bids and asks.

Channel: orderbook

Overview

The orderbook channel provides real-time snapshots of the order book showing configurable price levels on both bid and ask sides. Upon subscription, the current order book state is sent immediately. Afterward, updates are sent when the book changes.

Connection

Connect to the WebSocket endpoint:

wss://marketdata.app.hello.trade/ws

Subscription Request

{
  "type": "subscribe",
  "channel": "orderbook",
  "symbols": ["BTC", "ETH"],
  "levels": 10,
  "orderbookInterval": 100
}

Field	Type	Required	Description
type	string	Yes	Must be "subscribe"
channel	string	Yes	Must be "orderbook"
symbols	string[]	Yes	List of instrument symbols
levels	Number	No	Number of levels: 1, 5, 10, 20, or 100 (default: 10). Max 20 with orderbookInterval: 0.
orderbookInterval	Number	No	Update interval in milliseconds: 100, 1000, or 2000 (default: 100). 0 selects the live stream.
decimals	Number	No	Group price levels to this many decimal places: bids round down, asks round up, equal buckets merge. Omit for raw price levels. 0 groups to whole prices. Max 8 on the live stream.

Live Stream (orderbookInterval: 0)

Setting orderbookInterval to 0 switches from sampled snapshots to an event-driven stream. Instead of polling the venue every N milliseconds, the server maintains the full book from the exchange's order-by-order feed and pushes a new top-levels snapshot every time the displayed book changes.

{
  "type": "subscribe",
  "channel": "orderbook",
  "symbols": ["BTC"],
  "levels": 10,
  "orderbookInterval": 0
}

• The response shape is identical to the sampled stream (bids, asks, timeStamp), so existing parsers work unchanged.

• The current book is sent immediately on subscribe, then whenever the top levels of either side change. Changes deeper than your requested levels do not produce a message.

• Messages are coalesced with a 10 ms window per symbol (capped at 100 messages per second per symbol): several changes inside the window arrive as one message carrying the newest book, never a backlog. Every message is a complete snapshot.

• levels is capped at 20. Deeper event-driven data is not offered on this channel because full snapshots scale with depth times change rate.

• timeStamp is the server-side time of the last applied change.

• If the server's upstream feed reconnects, there is a brief pause and then a fresh snapshot. Treat any gap longer than a few seconds as a signal to fall back to the sampled stream or the ticker channel.

• decimals works the same as on the sampled stream. levels: 100, decimals above 8, and unknown symbols are rejected with a 400. The subscribed confirmation lists only the symbols that were attached.

• For a few seconds after a server restart the live stream answers 503 with "Live orderbook is loading, retry shortly". Retry with backoff, or use the sampled stream meanwhile.

Unsubscription Request

{
  "type": "unsubscribe",
  "channel": "orderbook",
  "symbols": ["BTC"]
}

Response

{
  "type": "marketData",
  "channel": "orderbook",
  "data": {
    "symbol": "BTC",
    "bids": [
      { "price": "45000.50", "quantity": "1.5", "numberOfOrders": "3" },
      { "price": "45000.00", "quantity": "2.3", "numberOfOrders": "5" },
      { "price": "44999.50", "quantity": "1.8", "numberOfOrders": "2" }
    ],
    "asks": [
      { "price": "45001.00", "quantity": "1.2", "numberOfOrders": "2" },
      { "price": "45001.50", "quantity": "2.1", "numberOfOrders": "4" },
      { "price": "45002.00", "quantity": "1.6", "numberOfOrders": "3" }
    ],
    "timeStamp": 1705596400000
  }
}

Field	Type	Description
symbol	string	Instrument symbol
bids	Array	Bid price levels, sorted by price descending (best bid first)
asks	Array	Ask price levels, sorted by price ascending (best ask first)
timeStamp	Number	Unix timestamp (milliseconds) of order book snapshot

Price Level Structure:

Field	Type	Description
price	string	Price level
quantity	string	Total quantity at this price level
numberOfOrders	string	Number of orders at this price level

Error Response

{
  "type": "error",
  "message": "Invalid subscription request",
  "code": 400
}

Code	When
400	Invalid request, levels: 100 or decimals above 8 on the live stream, or unknown symbol
503	Live stream not yet loaded after a server restart; retry

Unknown symbols are rejected with a 400 that names them. See Unknown symbols.

Notes

• Configurable depth: 1, 5, 10, 20, or 100 levels per side

• Bids are sorted highest price first

• Asks are sorted lowest price first

• Empty arrays indicate no orders on that side

• Updates are sent only when the order book changes

• Update interval controls snapshot frequency (100ms, 1000ms, or 2000ms), or 0 for a push on every change