watchOrderbook

Subscribe to a continuously synchronized order book. Every call to onOrderbook receives a complete book — never a delta — and every one is a fresh object, so a consumer can hold onto one without it mutating underneath them.


import { createBinanceOrderbookSource } from "@symmio/trading-core";
 
const source = createBinanceOrderbookSource();
 
const unwatch = source.watchOrderbook?.({
  marketName: "BTCUSDT",
  levels: 15,
  onOrderbook: (book) => render(book),
  onResync: (reason) => markStale(reason),
  onError: (error) => console.warn(error.code, error.message),
});
 
/** Later: releases the subscription and cancels any in-flight snapshot. */
unwatch?.();

watchOrderbook is optional on the interface — a source with no realtime feed omits it, and a consumer falls back to polling getOrderbook.

Parameters

marketNamestringrequired

Market name as SYMMIO names it.

limitnumberoptional

Levels per side in the snapshot the live book is built on. Deeper snapshots cost more rate-limit weight but survive a large sweep without the far side going blank. Defaults to the source’s defaultLimit.

levelsnumberoptional

Levels per side to emit on each update. Defaults to 50. Independent of limit — the source tracks the full book internally and trims only at the callback, so a 15-row ladder does not pay for 1000 objects per tick.

onOrderbook(orderbook: Orderbook) => voidrequired

Called with a complete book on every applied update.

onResync(reason: OrderbookResyncReason) => voidoptional

Called when the book is about to be rebuilt, before the rebuild completes. The next onOrderbook is the rebuilt book.

onStatusChange(status: SocketStatus) => voidoptional

Called whenever the underlying connection status changes.

onError(error: SymmError) => voidoptional

Called on a transport, parse, or snapshot error. Does not stop the subscription.

Returns

Unwatch

A function that closes the connection, cancels any in-flight snapshot, and stops all callbacks.

Resync reasons

onResync is the honest signal that the ladder on screen has stopped tracking the venue. Handle it.

initialOrderbookResyncReason

The first build. There was no prior book.

sequence-gapOrderbookResyncReason

An update did not chain onto the previous one, so at least one update was missed and the local book can no longer be trusted.

reconnectOrderbookResyncReason

The socket dropped and re-dialled. Updates during the gap are lost.

stale-snapshotOrderbookResyncReason

The snapshot came back older than the buffered updates could bridge, so it was refetched.

During a rebuild the last good book is still the most useful thing on screen. Dim the ladder rather than blanking it — the React layer surfaces this as isResyncing, with the previous rows still returned.

What it handles for you

Ordering. Subscribe and buffer first, then snapshot. Fetching first leaves the window between the snapshot and the first buffered update uncovered, and nothing downstream can detect the hole.
Per-market continuity. USD-M futures chains on pu; spot chains on U. The rules are not interchangeable.
Removal semantics. Quantities are absolute; a zero removes the level. An update removing a level the book never held is normal and ignored.
Reconnects. Binance drops idle connections after 24 hours. The socket re-dials with jittered backoff, re-sends SUBSCRIBE, and the book resyncs.
Snapshot failures. Retried while the socket keeps buffering, so a retry resumes from live updates rather than a cold start.

createBinanceOrderbookSource — the reference source.
getOrderbook — the one-shot equivalent.
useOrderbookStream / useLiveOrderbook — the React hooks.
Orderbook guide — the synchronization procedure in full.