Orderbook hooks

React bindings over the orderbook slice. The hooks own the source’s memoization, the subscription lifecycle, and error normalization; everything about how a book is kept correct lives in core.

All reads.

Import

import {
  useBinanceOrderbookSource,
  useLiveOrderbook,
  useOrderbook,
  useOrderbookStream,
  type UseBinanceOrderbookSourceParameters,
  type UseLiveOrderbookParameters,
  type UseLiveOrderbookReturnType,
  type UseOrderbookParameters,
  type UseOrderbookReturnType,
  type UseOrderbookStreamParameters,
  type UseOrderbookStreamReturnType,
} from "@symmio/trading-react";

Value types (Orderbook, OrderbookLevel, OrderbookSource, OrderbookSpread) come from @symmio/trading-core.

Choosing a hook

All three need a source. Build it once with useBinanceOrderbookSource.

useBinanceOrderbookSource

Creates a memoized Binance OrderbookSource.

A source caches the venue’s exchangeInfo for its lifetime, so recreating it per render refetches that on every symbol resolve — and, worse, a new source identity tears down and re-dials any live subscription built on it.

const source = useBinanceOrderbookSource();

Parameters

Takes the same options as createBinanceOrderbookSource.

Return type

An OrderbookSource, stable for as long as its options are unchanged.

useLiveOrderbook

The hook most ladders want. It resolves the market’s symbol metadata, holds one synchronized subscription, collapses the book onto the requested tick, attaches cumulative depth to every row, and reports the spread.

const source = useBinanceOrderbookSource();
 
const { bids, asks, spread, symbol, tickSizeOptions, isResyncing } = useLiveOrderbook({
  source,
  marketName: "BTCUSDT",
  tickSize: 0.1,
  rows: 15,
});

Parameters

Return type

Row count and grouping

rows is per side, so rows: 5 returns five bids and five asks.

Grouping collapses levels, so the number of raw levels needed to fill those rows scales with how coarse the grouping is: at ten times the venue tick each row can swallow ten levels. levels is therefore derived from rows and the active grouping rather than fixed — a fixed budget that fills the ladder at the venue tick starves it at a coarse one, leaving dead space where the missing rows should be.

The derived budget is quantized into a few buckets, because levels is a subscription parameter and recomputing it exactly would re-dial the socket every time the grouping nudged. Pass levels yourself only to cap the per-update cost deliberately, accepting that a coarse grouping may then render fewer than rows rows.

Checking coverage first

isUnsupported is the source’s own answer to “do you carry this market”, and it is the check to run before rendering. Asking a venue for a market it does not list is an HTTP error, not an empty book. The hook waits for that answer before subscribing, so an unlisted market never costs a wasted socket — and fails open if the check itself errors, so a transient metadata failure does not hide a listed market’s depth.

useOrderbookStream

The raw synchronized book, without grouping or accumulation.

const { orderbook, isResyncing, status } = useOrderbookStream({
  source,
  marketName: "BTCUSDT",
  levels: 50,
  onOrderbook: (book) => depthChart.update(book),
});

Parameters

Return type

{ orderbook, isResyncing, resyncReason, status, error } — the same fields useLiveOrderbook re-exposes, without the derived rows.

Use onOrderbook to drive a canvas depth chart imperatively without re-rendering the tree on every tick.

useOrderbook

A point-in-time snapshot through TanStack Query.

const { data, isLoading, error } = useOrderbook({
  source,
  marketName: "BTCUSDT",
  limit: 20,
});

Parameters

Return type

UseQueryResult<Orderbook, SymmioRequestError>.

Staying correct

The book behind these hooks is not a stream of deltas applied on faith. The source verifies that every update chains onto the last and rebuilds from a fresh snapshot when one does not — on a missed update, a reconnect, or a snapshot that lands too old to bridge.

That is surfaced as isResyncing and resyncReason. While a rebuild is in flight the last good book is still returned, which is deliberate: it is the most useful thing you can show. Dim the ladder rather than blanking it, and let resyncReason explain the pause if the UI has room for it.

Related

• Orderbook — the framework-agnostic slice.
• Orderbook guide — building a ladder end to end.
• watchOrderbook — what the synchronization guarantees.