@symmio/trading-core 1.1.0 → 3.0.0

package/dist/orderbook/aggregate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.js","names":[],"sources":["../../src/orderbook/aggregate.ts"],"sourcesContent":["import { roundToTick } from \"./tick-size\";\nimport type { Orderbook, OrderbookDepthLevel, OrderbookDepthSummary, OrderbookLevel, OrderbookSpread } from \"./types\";\n\n/**\n * Collapse a book onto a coarser price grid.\n *\n * Bids round **down** and asks round **up**, so a grouped level never claims\n * liquidity at a better price than actually rests there — a bid group labelled\n * `63018.0` holds orders from `63018.0` up to just under the next tick, all of\n * which a seller can hit at `63018.0` or better.\n *\n * Level ordering is preserved: bids stay descending, asks ascending.\n *\n * @param orderbook - The book to group.\n * @param tickSize - Grid spacing. Must be positive.\n * @returns A new book on the coarser grid. `lastUpdateId`, `timestamp`, and\n *   `marketName` are carried through unchanged.\n * @throws {SymmError} when `tickSize` is not a positive finite number.\n *\n * @example\n * ```ts\n * const grouped = groupOrderbook(book, 1);\n * // levels at 63018.1 / 63018.4 / 63018.9 collapse into one ask at 63019\n * ```\n */\nexport function groupOrderbook(orderbook: Orderbook, tickSize: number): Orderbook {\n  return {\n    ...orderbook,\n    bids: groupLevels(orderbook.bids, tickSize, \"down\"),\n    asks: groupLevels(orderbook.asks, tickSize, \"up\"),\n  };\n}\n\nfunction groupLevels(levels: readonly OrderbookLevel[], tickSize: number, mode: \"down\" | \"up\"): OrderbookLevel[] {\n  /**\n   * A Map preserves insertion order, and the input is already sorted by price,\n   * so the grouped output comes out sorted without a second sort pass.\n   */\n  const buckets = new Map<number, number>();\n\n  for (const level of levels) {\n    const price = roundToTick(level.price, tickSize, mode);\n    buckets.set(price, (buckets.get(price) ?? 0) + level.size);\n  }\n\n  return Array.from(buckets, ([price, size]) => ({ price, size }));\n}\n\n/**\n * Annotate each level with the depth resting at or better than it.\n *\n * Totals are **inclusive** of the level's own size. That matters: an exclusive\n * running total leaves the best bid and best ask reading `0`, and normalizing\n * a depth bar against it silently understates every row by one level's size.\n *\n * @param levels - One side of a book, best price first.\n * @returns The same levels with `total` and `totalQuote` attached.\n *\n * @example\n * ```ts\n * accumulateOrderbook([\n *   { price: 100, size: 2 },\n *   { price: 99, size: 3 },\n * ]);\n * // [{ price: 100, size: 2, total: 2, totalQuote: 200 },\n * //  { price: 99, size: 3, total: 5, totalQuote: 497 }]\n * ```\n */\nexport function accumulateOrderbook(levels: readonly OrderbookLevel[]): OrderbookDepthLevel[] {\n  let total = 0;\n  let totalQuote = 0;\n\n  return levels.map((level) => {\n    total += level.size;\n    totalQuote += level.price * level.size;\n    return { ...level, total, totalQuote };\n  });\n}\n\n/**\n * Best prices and the gap between them.\n *\n * @param orderbook - The book to measure.\n * @returns The spread, or `undefined` when either side is empty — a one-sided\n *   book has no spread, and reporting `0` would read as a locked market.\n *\n * @example\n * ```ts\n * const spread = getOrderbookSpread(book);\n * if (spread) console.log(`${spread.spread} (${spread.spreadBps.toFixed(1)} bps)`);\n * ```\n */\nexport function getOrderbookSpread(orderbook: Orderbook): OrderbookSpread | undefined {\n  const bestBid = orderbook.bids[0]?.price;\n  const bestAsk = orderbook.asks[0]?.price;\n\n  if (bestBid === undefined || bestAsk === undefined) return undefined;\n\n  const midPrice = (bestBid + bestAsk) / 2;\n  const spread = bestAsk - bestBid;\n\n  return {\n    bestBid,\n    bestAsk,\n    spread,\n    /** A mid of zero cannot happen on a real market, but division by it would poison the value. */\n    spreadBps: midPrice > 0 ? (spread / midPrice) * 10_000 : 0,\n    midPrice,\n  };\n}\n\n/**\n * Measure the depth resting within a price band around the mid.\n *\n * More robust than top-of-book size: a single large order five percent away\n * moves top-of-book not at all and this figure not at all, while a wall of\n * small orders next to the mid moves this a lot. The `imbalance` it returns is\n * the usual read on which side is leaning.\n *\n * @param orderbook - The book to measure.\n * @param percent - Half-width of the band as a fraction of mid (`0.01` = ±1%).\n * @returns Per-side size, notional, and imbalance. All zero when the book has\n *   no mid (one side empty).\n *\n * @example\n * ```ts\n * const { imbalance } = getOrderbookDepthWithin(book, 0.01);\n * // imbalance > 0 → more bid notional than ask within ±1% of mid\n * ```\n */\nexport function getOrderbookDepthWithin(orderbook: Orderbook, percent: number): OrderbookDepthSummary {\n  const empty: OrderbookDepthSummary = {\n    percent,\n    bidSize: 0,\n    askSize: 0,\n    bidQuote: 0,\n    askQuote: 0,\n    imbalance: 0,\n  };\n\n  const spread = getOrderbookSpread(orderbook);\n  if (!spread) return empty;\n\n  const floor = spread.midPrice * (1 - percent);\n  const ceiling = spread.midPrice * (1 + percent);\n\n  let bidSize = 0;\n  let bidQuote = 0;\n  for (const level of orderbook.bids) {\n    /** Bids descend, so the first level below the floor ends the window. */\n    if (level.price < floor) break;\n    bidSize += level.size;\n    bidQuote += level.price * level.size;\n  }\n\n  let askSize = 0;\n  let askQuote = 0;\n  for (const level of orderbook.asks) {\n    if (level.price > ceiling) break;\n    askSize += level.size;\n    askQuote += level.price * level.size;\n  }\n\n  const totalQuote = bidQuote + askQuote;\n\n  return {\n    percent,\n    bidSize,\n    askSize,\n    bidQuote,\n    askQuote,\n    imbalance: totalQuote > 0 ? (bidQuote - askQuote) / totalQuote : 0,\n  };\n}\n"],"mappings":";;AAyBA,SAAgB,EAAe,GAAsB,GAA6B;CAChF,OAAO;EACL,GAAG;EACH,MAAM,EAAY,EAAU,MAAM,GAAU,MAAM;EAClD,MAAM,EAAY,EAAU,MAAM,GAAU,IAAI;CAClD;AACF;AAEA,SAAS,EAAY,GAAmC,GAAkB,GAAuC;CAK/G,IAAM,oBAAU,IAAI,IAAoB;CAExC,KAAK,IAAM,KAAS,GAAQ;EAC1B,IAAM,IAAQ,EAAY,EAAM,OAAO,GAAU,CAAI;EACrD,EAAQ,IAAI,IAAQ,EAAQ,IAAI,CAAK,KAAK,KAAK,EAAM,IAAI;CAC3D;CAEA,OAAO,MAAM,KAAK,IAAU,CAAC,GAAO,QAAW;EAAE;EAAO;CAAK,EAAE;AACjE;AAsBA,SAAgB,EAAoB,GAA0D;CAC5F,IAAI,IAAQ,GACR,IAAa;CAEjB,OAAO,EAAO,KAAK,OACjB,KAAS,EAAM,MACf,KAAc,EAAM,QAAQ,EAAM,MAC3B;EAAE,GAAG;EAAO;EAAO;CAAW,EACtC;AACH;AAeA,SAAgB,EAAmB,GAAmD;CACpF,IAAM,IAAU,EAAU,KAAK,IAAI,OAC7B,IAAU,EAAU,KAAK,IAAI;CAEnC,IAAI,MAAY,KAAA,KAAa,MAAY,KAAA,GAAW;CAEpD,IAAM,KAAY,IAAU,KAAW,GACjC,IAAS,IAAU;CAEzB,OAAO;EACL;EACA;EACA;EAEA,WAAW,IAAW,IAAK,IAAS,IAAY,MAAS;EACzD;CACF;AACF;AAqBA,SAAgB,EAAwB,GAAsB,GAAwC;CACpG,IAAM,IAA+B;EACnC;EACA,SAAS;EACT,SAAS;EACT,UAAU;EACV,UAAU;EACV,WAAW;CACb,GAEM,IAAS,EAAmB,CAAS;CAC3C,IAAI,CAAC,GAAQ,OAAO;CAEpB,IAAM,IAAQ,EAAO,YAAY,IAAI,IAC/B,IAAU,EAAO,YAAY,IAAI,IAEnC,IAAU,GACV,IAAW;CACf,KAAK,IAAM,KAAS,EAAU,MAAM;EAElC,IAAI,EAAM,QAAQ,GAAO;EAEzB,AADA,KAAW,EAAM,MACjB,KAAY,EAAM,QAAQ,EAAM;CAClC;CAEA,IAAI,IAAU,GACV,IAAW;CACf,KAAK,IAAM,KAAS,EAAU,MAAM;EAClC,IAAI,EAAM,QAAQ,GAAS;EAE3B,AADA,KAAW,EAAM,MACjB,KAAY,EAAM,QAAQ,EAAM;CAClC;CAEA,IAAM,IAAa,IAAW;CAE9B,OAAO;EACL;EACA;EACA;EACA;EACA;EACA,WAAW,IAAa,KAAK,IAAW,KAAY,IAAa;CACnE;AACF"}

package/dist/orderbook/index.d.ts

@@ -0,0 +1,7 @@
+export * from './aggregate.js';
+export * from './query.js';
+export * from './sources/binance/index.js';
+export * from './tick-size.js';
+export * from './types.js';
+export * from './walk.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/orderbook/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orderbook/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC"}

package/dist/orderbook/query.d.ts

@@ -0,0 +1,55 @@
+import { Compute } from '../shared/types/properties.js';
+import { QueryParameter, SymmioQueryOptions } from '../shared/types/query.js';
+import { GetOrderbookParameters, Orderbook, OrderbookSource } from './types.js';
+/** Data resolved by the {@link getOrderbookQueryOptions} query. */
+export type GetOrderbookData = Orderbook;
+/**
+ * The identifying half of {@link GetOrderbookOptions}: everything that decides
+ * which book is being asked for.
+ *
+ * `signal` is excluded — cancellation is TanStack's concern, not part of the
+ * request's identity.
+ */
+export type GetOrderbookQueryKeyParameters = Compute<Omit<GetOrderbookParameters, "signal"> & {
+    /** {@link OrderbookSource.id}, so two sources never share a cache entry. */
+    sourceId: string;
+}>;
+/**
+ * Build the TanStack Query key for {@link getOrderbookQueryOptions}.
+ *
+ * @param options - Source id, market, and depth.
+ * @returns A stable, hashable query key.
+ */
+export declare function getOrderbookQueryKey(options: GetOrderbookQueryKeyParameters): readonly ["getOrderbook", Record<string, unknown>];
+/** Query-key type produced by {@link getOrderbookQueryKey}. */
+export type GetOrderbookQueryKey = ReturnType<typeof getOrderbookQueryKey>;
+/**
+ * Options accepted by {@link getOrderbookQueryOptions}: the book to fetch plus
+ * TanStack overrides.
+ */
+export type GetOrderbookOptions = Compute<Omit<GetOrderbookParameters, "signal"> & QueryParameter<GetOrderbookData, Error, GetOrderbookData, GetOrderbookQueryKey>>;
+/** TanStack Query options returned by {@link getOrderbookQueryOptions}. */
+export type GetOrderbookQueryOptions = SymmioQueryOptions<GetOrderbookData, Error, GetOrderbookData, GetOrderbookQueryKey>;
+/**
+ * Build TanStack Query options for an {@link OrderbookSource} snapshot.
+ *
+ * Unlike the chain-scoped factories in the SDK, this takes a source rather than
+ * a `Config`: which venue's depth to read is the consumer's choice, not a
+ * property of the SYMMIO deployment. The source's `id` is folded into the query
+ * key so switching venues does not read another venue's cached book.
+ *
+ * A snapshot goes stale the moment it lands. For anything a user watches, use
+ * `useLiveOrderbook` (or `watchOrderbook` directly) instead of polling this —
+ * a synchronized diff stream is both fresher and far cheaper in rate-limit weight.
+ *
+ * @param source - The order-book source to read from.
+ * @param options - Market, depth, and TanStack overrides.
+ * @returns Options to pass to `useQuery` / `queryClient.fetchQuery`.
+ *
+ * @example
+ * ```ts
+ * useQuery(getOrderbookQueryOptions(source, { marketName: "BTCUSDT", limit: 20 }));
+ * ```
+ */
+export declare function getOrderbookQueryOptions(source: OrderbookSource, options: GetOrderbookOptions): GetOrderbookQueryOptions;
+//# sourceMappingURL=query.d.ts.map

package/dist/orderbook/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/orderbook/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhF,OAAO,KAAK,EAAE,sBAAsB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAElF,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAClD,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC,GAAG;IACvC,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;CAClB,CACF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,8BAA8B,sDAE3E;AAED,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC,GACpC,cAAc,CAAC,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,CAAC,CAClF,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CACvD,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EAChB,oBAAoB,CACrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,mBAAmB,GAC3B,wBAAwB,CAS1B"}

package/dist/orderbook/query.js

@@ -0,0 +1,25 @@
+import { filterQueryOptions as e } from "../shared/utils/query.js";
+//#region src/orderbook/query.ts
+function t(t) {
+	return ["getOrderbook", e(t)];
+}
+function n(e, n) {
+	let { marketName: r, limit: i } = n;
+	return {
+		...n.query,
+		queryKey: t({
+			sourceId: e.id,
+			marketName: r,
+			limit: i
+		}),
+		enabled: n.query?.enabled ?? !0,
+		queryFn: () => e.getOrderbook({
+			marketName: r,
+			limit: i
+		})
+	};
+}
+//#endregion
+export { t as getOrderbookQueryKey, n as getOrderbookQueryOptions };
+
+//# sourceMappingURL=query.js.map

package/dist/orderbook/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","names":[],"sources":["../../src/orderbook/query.ts"],"sourcesContent":["import type { Compute } from \"../shared/types/properties\";\nimport type { QueryParameter, SymmioQueryOptions } from \"../shared/types/query\";\nimport { filterQueryOptions } from \"../shared/utils/query\";\nimport type { GetOrderbookParameters, Orderbook, OrderbookSource } from \"./types\";\n\n/** Data resolved by the {@link getOrderbookQueryOptions} query. */\nexport type GetOrderbookData = Orderbook;\n\n/**\n * The identifying half of {@link GetOrderbookOptions}: everything that decides\n * which book is being asked for.\n *\n * `signal` is excluded — cancellation is TanStack's concern, not part of the\n * request's identity.\n */\nexport type GetOrderbookQueryKeyParameters = Compute<\n  Omit<GetOrderbookParameters, \"signal\"> & {\n    /** {@link OrderbookSource.id}, so two sources never share a cache entry. */\n    sourceId: string;\n  }\n>;\n\n/**\n * Build the TanStack Query key for {@link getOrderbookQueryOptions}.\n *\n * @param options - Source id, market, and depth.\n * @returns A stable, hashable query key.\n */\nexport function getOrderbookQueryKey(options: GetOrderbookQueryKeyParameters) {\n  return [\"getOrderbook\", filterQueryOptions(options)] as const;\n}\n\n/** Query-key type produced by {@link getOrderbookQueryKey}. */\nexport type GetOrderbookQueryKey = ReturnType<typeof getOrderbookQueryKey>;\n\n/**\n * Options accepted by {@link getOrderbookQueryOptions}: the book to fetch plus\n * TanStack overrides.\n */\nexport type GetOrderbookOptions = Compute<\n  Omit<GetOrderbookParameters, \"signal\"> &\n    QueryParameter<GetOrderbookData, Error, GetOrderbookData, GetOrderbookQueryKey>\n>;\n\n/** TanStack Query options returned by {@link getOrderbookQueryOptions}. */\nexport type GetOrderbookQueryOptions = SymmioQueryOptions<\n  GetOrderbookData,\n  Error,\n  GetOrderbookData,\n  GetOrderbookQueryKey\n>;\n\n/**\n * Build TanStack Query options for an {@link OrderbookSource} snapshot.\n *\n * Unlike the chain-scoped factories in the SDK, this takes a source rather than\n * a `Config`: which venue's depth to read is the consumer's choice, not a\n * property of the SYMMIO deployment. The source's `id` is folded into the query\n * key so switching venues does not read another venue's cached book.\n *\n * A snapshot goes stale the moment it lands. For anything a user watches, use\n * `useLiveOrderbook` (or `watchOrderbook` directly) instead of polling this —\n * a synchronized diff stream is both fresher and far cheaper in rate-limit weight.\n *\n * @param source - The order-book source to read from.\n * @param options - Market, depth, and TanStack overrides.\n * @returns Options to pass to `useQuery` / `queryClient.fetchQuery`.\n *\n * @example\n * ```ts\n * useQuery(getOrderbookQueryOptions(source, { marketName: \"BTCUSDT\", limit: 20 }));\n * ```\n */\nexport function getOrderbookQueryOptions(\n  source: OrderbookSource,\n  options: GetOrderbookOptions,\n): GetOrderbookQueryOptions {\n  const { marketName, limit } = options;\n\n  return {\n    ...options.query,\n    queryKey: getOrderbookQueryKey({ sourceId: source.id, marketName, limit }),\n    enabled: options.query?.enabled ?? true,\n    queryFn: () => source.getOrderbook({ marketName, limit }),\n  };\n}\n"],"mappings":";;AA4BA,SAAgB,EAAqB,GAAyC;CAC5E,OAAO,CAAC,gBAAgB,EAAmB,CAAO,CAAC;AACrD;AA2CA,SAAgB,EACd,GACA,GAC0B;CAC1B,IAAM,EAAE,eAAY,aAAU;CAE9B,OAAO;EACL,GAAG,EAAQ;EACX,UAAU,EAAqB;GAAE,UAAU,EAAO;GAAI;GAAY;EAAM,CAAC;EACzE,SAAS,EAAQ,OAAO,WAAW;EACnC,eAAe,EAAO,aAAa;GAAE;GAAY;EAAM,CAAC;CAC1D;AACF"}

package/dist/orderbook/sources/binance/constants.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Which Binance market an order-book source reads from.
+ *
+ * `usd-m-futures` is the default and the correct choice for a SYMMIO perp: its
+ * symbols are perpetual contracts, so the depth matches what the instrument
+ * actually is. `spot` is offered for markets with no futures listing.
+ */
+export type BinanceOrderbookMarket = "usd-m-futures" | "spot";
+/** Default REST hosts per market. */
+export declare const BINANCE_DEPTH_REST_URL: Record<BinanceOrderbookMarket, string>;
+/**
+ * Default combined-stream WebSocket endpoints per market.
+ *
+ * **The futures path is `/public/`, and it is not interchangeable with the
+ * candles slice's `/market/`.** Binance routes futures streams by class:
+ * `/public` carries `@depth`, partial depth and `@bookTicker`, while `/market`
+ * carries `@kline_*`, `@aggTrade`, `@markPrice` and `@ticker`. Subscribing on
+ * the wrong route is not an error — the server acknowledges with
+ * `{"result":null}` and then never pushes a single frame, so the book reports
+ * `open` and stays empty forever. Verified against the live endpoint:
+ * `@depth@500ms` delivers on `/public/stream` and delivers nothing on
+ * `/market/stream`; `@kline_1m` does the exact opposite.
+ *
+ * The legacy unrouted `/stream` still carries depth because depth is a public
+ * stream, but it was decommissioned for everything else in April 2026 and is
+ * not what new code should dial.
+ *
+ * Spot has no such routing — one combined-stream endpoint serves everything.
+ */
+export declare const BINANCE_DEPTH_WS_URL: Record<BinanceOrderbookMarket, string>;
+/** Depth-snapshot REST path per market. */
+export declare const BINANCE_DEPTH_PATH: Record<BinanceOrderbookMarket, string>;
+/** Exchange-info REST path per market, used to resolve tick size and precision. */
+export declare const BINANCE_ORDERBOOK_EXCHANGE_INFO_PATH: Record<BinanceOrderbookMarket, string>;
+/**
+ * Snapshot depths each market accepts.
+ *
+ * Futures takes an **enum**, not a range: anything else fails outright with
+ * `-4021 "<n> is not valid depth limit"` rather than being clamped. Spot takes
+ * any limit and clamps at its maximum, so only the ceiling is listed.
+ */
+export declare const BINANCE_DEPTH_LIMITS: Record<BinanceOrderbookMarket, readonly number[]>;
+/**
+ * Default snapshot depth per market.
+ *
+ * 1000 levels on both. Deep enough that a large sweep does not empty the
+ * visible ladder before the next snapshot, and it is the depth Binance's own
+ * local-order-book procedure specifies.
+ */
+export declare const BINANCE_DEPTH_DEFAULT_LIMIT: Record<BinanceOrderbookMarket, number>;
+/**
+ * Diff-stream update speeds each market serves, in milliseconds.
+ *
+ * Futures offers 250ms (the suffix-less default), 500ms and 100ms; spot offers
+ * only 1000ms and 100ms. Asking for a speed the market does not serve yields a
+ * stream name that is accepted and never delivers.
+ */
+export declare const BINANCE_DEPTH_UPDATE_SPEEDS: Record<BinanceOrderbookMarket, readonly number[]>;
+/** Default diff-stream update speed per market, in milliseconds. */
+export declare const BINANCE_DEPTH_DEFAULT_UPDATE_SPEED: Record<BinanceOrderbookMarket, number>;
+/**
+ * Levels per side emitted on each update when a caller does not say.
+ *
+ * The internal book tracks every level the venue sends; this only bounds what
+ * crosses the callback, so a 15-row ladder does not allocate 2000 objects a tick.
+ */
+export declare const BINANCE_DEPTH_DEFAULT_LEVELS = 50;
+/**
+ * Buffered diff events retained while a snapshot is in flight.
+ *
+ * At the slowest update speed this is well over a minute of runway, far more
+ * than a snapshot needs. The cap exists so a snapshot that never resolves
+ * cannot grow the buffer without bound; when it trips, the **oldest** events
+ * are dropped and the resulting gap is caught by the continuity check rather
+ * than silently corrupting the book.
+ */
+export declare const BINANCE_DEPTH_MAX_BUFFERED_EVENTS = 200;
+//# sourceMappingURL=constants.d.ts.map

package/dist/orderbook/sources/binance/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/orderbook/sources/binance/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG,MAAM,CAAC;AAE9D,qCAAqC;AACrC,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAGzE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAGvE,CAAC;AAEF,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAGrE,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,oCAAoC,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAGvF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAGlF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAG9E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAGzF,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,kCAAkC,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAGrF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,MAAM,CAAC"}

package/dist/orderbook/sources/binance/constants.js

@@ -0,0 +1,51 @@
+//#region src/orderbook/sources/binance/constants.ts
+var e = {
+	"usd-m-futures": "https://fapi.binance.com",
+	spot: "https://api.binance.com"
+}, t = {
+	"usd-m-futures": "wss://fstream.binance.com/public/stream",
+	spot: "wss://stream.binance.com:9443/stream"
+}, n = {
+	"usd-m-futures": "/fapi/v1/depth",
+	spot: "/api/v3/depth"
+}, r = {
+	"usd-m-futures": "/fapi/v1/exchangeInfo",
+	spot: "/api/v3/exchangeInfo"
+}, i = {
+	"usd-m-futures": [
+		5,
+		10,
+		20,
+		50,
+		100,
+		500,
+		1e3
+	],
+	spot: [
+		5,
+		10,
+		20,
+		50,
+		100,
+		500,
+		1e3,
+		5e3
+	]
+}, a = {
+	"usd-m-futures": 1e3,
+	spot: 1e3
+}, o = {
+	"usd-m-futures": [
+		100,
+		250,
+		500
+	],
+	spot: [100, 1e3]
+}, s = {
+	"usd-m-futures": 500,
+	spot: 1e3
+}, c = 50, l = 200;
+//#endregion
+export { c as BINANCE_DEPTH_DEFAULT_LEVELS, a as BINANCE_DEPTH_DEFAULT_LIMIT, s as BINANCE_DEPTH_DEFAULT_UPDATE_SPEED, i as BINANCE_DEPTH_LIMITS, l as BINANCE_DEPTH_MAX_BUFFERED_EVENTS, n as BINANCE_DEPTH_PATH, e as BINANCE_DEPTH_REST_URL, o as BINANCE_DEPTH_UPDATE_SPEEDS, t as BINANCE_DEPTH_WS_URL, r as BINANCE_ORDERBOOK_EXCHANGE_INFO_PATH };
+
+//# sourceMappingURL=constants.js.map

package/dist/orderbook/sources/binance/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../../../src/orderbook/sources/binance/constants.ts"],"sourcesContent":["/**\n * Which Binance market an order-book source reads from.\n *\n * `usd-m-futures` is the default and the correct choice for a SYMMIO perp: its\n * symbols are perpetual contracts, so the depth matches what the instrument\n * actually is. `spot` is offered for markets with no futures listing.\n */\nexport type BinanceOrderbookMarket = \"usd-m-futures\" | \"spot\";\n\n/** Default REST hosts per market. */\nexport const BINANCE_DEPTH_REST_URL: Record<BinanceOrderbookMarket, string> = {\n  \"usd-m-futures\": \"https://fapi.binance.com\",\n  spot: \"https://api.binance.com\",\n};\n\n/**\n * Default combined-stream WebSocket endpoints per market.\n *\n * **The futures path is `/public/`, and it is not interchangeable with the\n * candles slice's `/market/`.** Binance routes futures streams by class:\n * `/public` carries `@depth`, partial depth and `@bookTicker`, while `/market`\n * carries `@kline_*`, `@aggTrade`, `@markPrice` and `@ticker`. Subscribing on\n * the wrong route is not an error — the server acknowledges with\n * `{\"result\":null}` and then never pushes a single frame, so the book reports\n * `open` and stays empty forever. Verified against the live endpoint:\n * `@depth@500ms` delivers on `/public/stream` and delivers nothing on\n * `/market/stream`; `@kline_1m` does the exact opposite.\n *\n * The legacy unrouted `/stream` still carries depth because depth is a public\n * stream, but it was decommissioned for everything else in April 2026 and is\n * not what new code should dial.\n *\n * Spot has no such routing — one combined-stream endpoint serves everything.\n */\nexport const BINANCE_DEPTH_WS_URL: Record<BinanceOrderbookMarket, string> = {\n  \"usd-m-futures\": \"wss://fstream.binance.com/public/stream\",\n  spot: \"wss://stream.binance.com:9443/stream\",\n};\n\n/** Depth-snapshot REST path per market. */\nexport const BINANCE_DEPTH_PATH: Record<BinanceOrderbookMarket, string> = {\n  \"usd-m-futures\": \"/fapi/v1/depth\",\n  spot: \"/api/v3/depth\",\n};\n\n/** Exchange-info REST path per market, used to resolve tick size and precision. */\nexport const BINANCE_ORDERBOOK_EXCHANGE_INFO_PATH: Record<BinanceOrderbookMarket, string> = {\n  \"usd-m-futures\": \"/fapi/v1/exchangeInfo\",\n  spot: \"/api/v3/exchangeInfo\",\n};\n\n/**\n * Snapshot depths each market accepts.\n *\n * Futures takes an **enum**, not a range: anything else fails outright with\n * `-4021 \"<n> is not valid depth limit\"` rather than being clamped. Spot takes\n * any limit and clamps at its maximum, so only the ceiling is listed.\n */\nexport const BINANCE_DEPTH_LIMITS: Record<BinanceOrderbookMarket, readonly number[]> = {\n  \"usd-m-futures\": [5, 10, 20, 50, 100, 500, 1000],\n  spot: [5, 10, 20, 50, 100, 500, 1000, 5000],\n};\n\n/**\n * Default snapshot depth per market.\n *\n * 1000 levels on both. Deep enough that a large sweep does not empty the\n * visible ladder before the next snapshot, and it is the depth Binance's own\n * local-order-book procedure specifies.\n */\nexport const BINANCE_DEPTH_DEFAULT_LIMIT: Record<BinanceOrderbookMarket, number> = {\n  \"usd-m-futures\": 1000,\n  spot: 1000,\n};\n\n/**\n * Diff-stream update speeds each market serves, in milliseconds.\n *\n * Futures offers 250ms (the suffix-less default), 500ms and 100ms; spot offers\n * only 1000ms and 100ms. Asking for a speed the market does not serve yields a\n * stream name that is accepted and never delivers.\n */\nexport const BINANCE_DEPTH_UPDATE_SPEEDS: Record<BinanceOrderbookMarket, readonly number[]> = {\n  \"usd-m-futures\": [100, 250, 500],\n  spot: [100, 1000],\n};\n\n/** Default diff-stream update speed per market, in milliseconds. */\nexport const BINANCE_DEPTH_DEFAULT_UPDATE_SPEED: Record<BinanceOrderbookMarket, number> = {\n  \"usd-m-futures\": 500,\n  spot: 1000,\n};\n\n/**\n * Levels per side emitted on each update when a caller does not say.\n *\n * The internal book tracks every level the venue sends; this only bounds what\n * crosses the callback, so a 15-row ladder does not allocate 2000 objects a tick.\n */\nexport const BINANCE_DEPTH_DEFAULT_LEVELS = 50;\n\n/**\n * Buffered diff events retained while a snapshot is in flight.\n *\n * At the slowest update speed this is well over a minute of runway, far more\n * than a snapshot needs. The cap exists so a snapshot that never resolves\n * cannot grow the buffer without bound; when it trips, the **oldest** events\n * are dropped and the resulting gap is caught by the continuity check rather\n * than silently corrupting the book.\n */\nexport const BINANCE_DEPTH_MAX_BUFFERED_EVENTS = 200;\n"],"mappings":";AAUA,IAAa,IAAiE;CAC5E,iBAAiB;CACjB,MAAM;AACR,GAqBa,IAA+D;CAC1E,iBAAiB;CACjB,MAAM;AACR,GAGa,IAA6D;CACxE,iBAAiB;CACjB,MAAM;AACR,GAGa,IAA+E;CAC1F,iBAAiB;CACjB,MAAM;AACR,GASa,IAA0E;CACrF,iBAAiB;EAAC;EAAG;EAAI;EAAI;EAAI;EAAK;EAAK;CAAI;CAC/C,MAAM;EAAC;EAAG;EAAI;EAAI;EAAI;EAAK;EAAK;EAAM;CAAI;AAC5C,GASa,IAAsE;CACjF,iBAAiB;CACjB,MAAM;AACR,GASa,IAAiF;CAC5F,iBAAiB;EAAC;EAAK;EAAK;CAAG;CAC/B,MAAM,CAAC,KAAK,GAAI;AAClB,GAGa,IAA6E;CACxF,iBAAiB;CACjB,MAAM;AACR,GAQa,IAA+B,IAW/B,IAAoC"}

package/dist/orderbook/sources/binance/create-binance-orderbook-source.d.ts

@@ -0,0 +1,78 @@
+import { WebSocketConstructor } from '../../../shared/types/websocket.js';
+import { OrderbookSource } from '../../types.js';
+import { BinanceOrderbookMarket } from './constants.js';
+/**
+ * Parameters for {@link createBinanceOrderbookSource}.
+ */
+export interface BinanceOrderbookSourceParameters {
+    /**
+     * Which Binance market to read. Defaults to `"usd-m-futures"` — its symbols
+     * are perpetual contracts, matching what a SYMMIO market actually is.
+     */
+    market?: BinanceOrderbookMarket;
+    /** Override the REST host (a regional mirror, or your own caching proxy). */
+    restUrl?: string;
+    /**
+     * Override the WebSocket endpoint.
+     *
+     * Only do this if you know the route serves depth. Binance routes futures
+     * streams by class, and a depth subscription on the wrong route is
+     * acknowledged and then silently never delivers — see {@link BINANCE_DEPTH_WS_URL}.
+     */
+    wsUrl?: string;
+    /**
+     * Diff-stream update speed in ms. Must be one the market serves — futures
+     * `100 | 250 | 500`, spot `100 | 1000`. Defaults to the market's own default.
+     */
+    updateSpeed?: number;
+    /**
+     * Map a SYMMIO market name onto a Binance symbol, or return `undefined` when
+     * the market has no Binance listing.
+     *
+     * Defaults to an upper-case identity mapping, which holds for current SYMMIO
+     * deployments where market names are already Binance USD-M symbols. Override
+     * it rather than relying on that coincidence if your deployment's names can
+     * diverge — an unmapped name otherwise resolves to a symbol that does not
+     * exist and the book simply stays empty.
+     */
+    resolveSymbol?: (marketName: string) => string | undefined;
+    /**
+     * WebSocket implementation for {@link OrderbookSource.watchOrderbook}.
+     * Defaults to `globalThis.WebSocket`; pass the `ws` package in Node
+     * environments without one.
+     */
+    webSocketConstructor?: WebSocketConstructor;
+}
+/**
+ * Create an {@link OrderbookSource} backed by Binance depth.
+ *
+ * Snapshots come from the REST `/depth` endpoint and live updates from the
+ * diff-depth WebSocket stream, combined into a continuously synchronized book
+ * by {@link watchBinanceDepth}. Both are reachable directly from a browser —
+ * Binance serves permissive CORS headers on market data, so no proxy or API key
+ * is involved.
+ *
+ * Two caveats worth surfacing to users of a ladder built on this:
+ * - The book is `priceBasis: "reference-exchange"`. It is Binance's resting
+ *   liquidity, not the depth a SYMMIO trade executes against.
+ * - `api.binance.com` and `fapi.binance.com` are blocked in some jurisdictions.
+ *   Supply `restUrl`/`wsUrl` to route through your own proxy where that matters.
+ *
+ * @param parameters - Market selection, endpoint overrides, and symbol mapping.
+ * @returns A source usable by `getOrderbookQueryOptions`, `useOrderbook`, or
+ *   `useLiveOrderbook`.
+ * @throws {SymmError} when `updateSpeed` is not one the chosen market serves.
+ *
+ * @example
+ * ```ts
+ * const source = createBinanceOrderbookSource();
+ * const book = await source.getOrderbook({ marketName: "BTCUSDT", limit: 20 });
+ * const unwatch = source.watchOrderbook!({
+ *   marketName: "BTCUSDT",
+ *   levels: 15,
+ *   onOrderbook: (next) => render(next),
+ * });
+ * ```
+ */
+export declare function createBinanceOrderbookSource(parameters?: BinanceOrderbookSourceParameters): OrderbookSource;
+//# sourceMappingURL=create-binance-orderbook-source.d.ts.map

package/dist/orderbook/sources/binance/create-binance-orderbook-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-binance-orderbook-source.d.ts","sourceRoot":"","sources":["../../../../src/orderbook/sources/binance/create-binance-orderbook-source.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE5E,OAAO,KAAK,EAGV,eAAe,EAGhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAQL,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AAKrB;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC3D;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,GAAE,gCAAqC,GAAG,eAAe,CA2H/G"}

package/dist/orderbook/sources/binance/create-binance-orderbook-source.js

@@ -0,0 +1,87 @@
+import { SymmError as e } from "../../../shared/errors/symm-error.js";
+import { BINANCE_DEPTH_DEFAULT_LIMIT as t, BINANCE_DEPTH_DEFAULT_UPDATE_SPEED as n, BINANCE_DEPTH_LIMITS as r, BINANCE_DEPTH_REST_URL as i, BINANCE_DEPTH_UPDATE_SPEEDS as a, BINANCE_DEPTH_WS_URL as o } from "./constants.js";
+import { fetchBinanceDepth as s } from "./fetch-binance-depth.js";
+import { fetchBinanceSymbolFilters as c } from "./fetch-binance-symbol-filters.js";
+import { watchBinanceDepth as l } from "./watch-binance-depth.js";
+//#region src/orderbook/sources/binance/create-binance-orderbook-source.ts
+function u(e) {
+	return e.toUpperCase();
+}
+function d(t) {
+	let n = t ?? globalThis.WebSocket;
+	if (!n) throw new e("config", "NO_WEBSOCKET_IMPLEMENTATION", "No WebSocket implementation available. Pass `webSocketConstructor` to createBinanceOrderbookSource (e.g. the `ws` package in Node).");
+	return n;
+}
+function f(f = {}) {
+	let p = f.market ?? "usd-m-futures", m = f.restUrl ?? i[p], h = f.wsUrl ?? o[p], g = f.resolveSymbol ?? u, _ = r[p], v = t[p], y = f.updateSpeed ?? n[p];
+	if (!a[p].includes(y)) throw new e("validation", "UNSUPPORTED_DEPTH_UPDATE_SPEED", `Binance ${p} has no ${y}ms depth stream. Supported: ${a[p].join(", ")}ms.`);
+	let b = null;
+	function x() {
+		return b ||= c(m, p).catch((e) => {
+			throw b = null, e;
+		}), b;
+	}
+	function S(t) {
+		let n = g(t);
+		if (!n) throw new e("validation", "UNMAPPED_ORDERBOOK_MARKET", `No Binance symbol is mapped for market "${t}".`);
+		return n;
+	}
+	function C(t) {
+		let n = t ?? v;
+		if (!_.includes(n)) throw new e("validation", "UNSUPPORTED_DEPTH_LIMIT", `Binance ${p} rejects a depth limit of ${n}. Supported: ${_.join(", ")}.`);
+		return n;
+	}
+	return {
+		id: `binance:${p}`,
+		priceBasis: "reference-exchange",
+		supportedLimits: _,
+		defaultLimit: v,
+		async getSymbol(e) {
+			let t = g(e);
+			if (!t) return;
+			let n = (await x()).get(t.toUpperCase());
+			if (n) return {
+				marketName: e,
+				sourceSymbol: n.symbol,
+				baseAsset: n.baseAsset,
+				quoteAsset: n.quoteAsset,
+				pricePrecision: n.pricePrecision,
+				sizePrecision: n.sizePrecision,
+				tickSize: n.tickSize
+			};
+		},
+		async getOrderbook(e) {
+			let { marketName: t, limit: n, signal: r } = e;
+			return s({
+				restUrl: m,
+				market: p,
+				symbol: S(t),
+				marketName: t,
+				limit: C(n),
+				signal: r
+			});
+		},
+		watchOrderbook(e) {
+			let { marketName: t, limit: n, levels: r, onOrderbook: i, onResync: a, onStatusChange: o, onError: s } = e;
+			return l({
+				restUrl: m,
+				wsUrl: h,
+				market: p,
+				symbol: S(t),
+				marketName: t,
+				limit: C(n),
+				levels: r && r > 0 ? r : 50,
+				updateSpeed: y,
+				webSocketConstructor: d(f.webSocketConstructor),
+				onOrderbook: i,
+				onResync: a,
+				onStatusChange: o,
+				onError: s
+			});
+		}
+	};
+}
+//#endregion
+export { f as createBinanceOrderbookSource };
+
+//# sourceMappingURL=create-binance-orderbook-source.js.map

package/dist/orderbook/sources/binance/create-binance-orderbook-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-binance-orderbook-source.js","names":[],"sources":["../../../../src/orderbook/sources/binance/create-binance-orderbook-source.ts"],"sourcesContent":["import { SymmError } from \"../../../shared/errors/symm-error\";\nimport type { WebSocketConstructor } from \"../../../shared/types/websocket\";\nimport type { Unwatch } from \"../../../websocket/notifications/watch-notifications\";\nimport type {\n  GetOrderbookParameters,\n  Orderbook,\n  OrderbookSource,\n  OrderbookSymbol,\n  WatchOrderbookParameters,\n} from \"../../types\";\nimport {\n  BINANCE_DEPTH_DEFAULT_LEVELS,\n  BINANCE_DEPTH_DEFAULT_LIMIT,\n  BINANCE_DEPTH_DEFAULT_UPDATE_SPEED,\n  BINANCE_DEPTH_LIMITS,\n  BINANCE_DEPTH_REST_URL,\n  BINANCE_DEPTH_UPDATE_SPEEDS,\n  BINANCE_DEPTH_WS_URL,\n  type BinanceOrderbookMarket,\n} from \"./constants\";\nimport { fetchBinanceDepth } from \"./fetch-binance-depth\";\nimport { fetchBinanceSymbolFilters, type BinanceSymbolFilters } from \"./fetch-binance-symbol-filters\";\nimport { watchBinanceDepth } from \"./watch-binance-depth\";\n\n/**\n * Parameters for {@link createBinanceOrderbookSource}.\n */\nexport interface BinanceOrderbookSourceParameters {\n  /**\n   * Which Binance market to read. Defaults to `\"usd-m-futures\"` — its symbols\n   * are perpetual contracts, matching what a SYMMIO market actually is.\n   */\n  market?: BinanceOrderbookMarket;\n  /** Override the REST host (a regional mirror, or your own caching proxy). */\n  restUrl?: string;\n  /**\n   * Override the WebSocket endpoint.\n   *\n   * Only do this if you know the route serves depth. Binance routes futures\n   * streams by class, and a depth subscription on the wrong route is\n   * acknowledged and then silently never delivers — see {@link BINANCE_DEPTH_WS_URL}.\n   */\n  wsUrl?: string;\n  /**\n   * Diff-stream update speed in ms. Must be one the market serves — futures\n   * `100 | 250 | 500`, spot `100 | 1000`. Defaults to the market's own default.\n   */\n  updateSpeed?: number;\n  /**\n   * Map a SYMMIO market name onto a Binance symbol, or return `undefined` when\n   * the market has no Binance listing.\n   *\n   * Defaults to an upper-case identity mapping, which holds for current SYMMIO\n   * deployments where market names are already Binance USD-M symbols. Override\n   * it rather than relying on that coincidence if your deployment's names can\n   * diverge — an unmapped name otherwise resolves to a symbol that does not\n   * exist and the book simply stays empty.\n   */\n  resolveSymbol?: (marketName: string) => string | undefined;\n  /**\n   * WebSocket implementation for {@link OrderbookSource.watchOrderbook}.\n   * Defaults to `globalThis.WebSocket`; pass the `ws` package in Node\n   * environments without one.\n   */\n  webSocketConstructor?: WebSocketConstructor;\n}\n\nfunction defaultResolveSymbol(marketName: string): string {\n  return marketName.toUpperCase();\n}\n\nfunction resolveWebSocketConstructor(injected?: WebSocketConstructor): WebSocketConstructor {\n  const ctor = injected ?? (globalThis as { WebSocket?: WebSocketConstructor }).WebSocket;\n  if (!ctor) {\n    throw new SymmError(\n      \"config\",\n      \"NO_WEBSOCKET_IMPLEMENTATION\",\n      \"No WebSocket implementation available. Pass `webSocketConstructor` to createBinanceOrderbookSource (e.g. the `ws` package in Node).\",\n    );\n  }\n  return ctor;\n}\n\n/**\n * Create an {@link OrderbookSource} backed by Binance depth.\n *\n * Snapshots come from the REST `/depth` endpoint and live updates from the\n * diff-depth WebSocket stream, combined into a continuously synchronized book\n * by {@link watchBinanceDepth}. Both are reachable directly from a browser —\n * Binance serves permissive CORS headers on market data, so no proxy or API key\n * is involved.\n *\n * Two caveats worth surfacing to users of a ladder built on this:\n * - The book is `priceBasis: \"reference-exchange\"`. It is Binance's resting\n *   liquidity, not the depth a SYMMIO trade executes against.\n * - `api.binance.com` and `fapi.binance.com` are blocked in some jurisdictions.\n *   Supply `restUrl`/`wsUrl` to route through your own proxy where that matters.\n *\n * @param parameters - Market selection, endpoint overrides, and symbol mapping.\n * @returns A source usable by `getOrderbookQueryOptions`, `useOrderbook`, or\n *   `useLiveOrderbook`.\n * @throws {SymmError} when `updateSpeed` is not one the chosen market serves.\n *\n * @example\n * ```ts\n * const source = createBinanceOrderbookSource();\n * const book = await source.getOrderbook({ marketName: \"BTCUSDT\", limit: 20 });\n * const unwatch = source.watchOrderbook!({\n *   marketName: \"BTCUSDT\",\n *   levels: 15,\n *   onOrderbook: (next) => render(next),\n * });\n * ```\n */\nexport function createBinanceOrderbookSource(parameters: BinanceOrderbookSourceParameters = {}): OrderbookSource {\n  const market = parameters.market ?? \"usd-m-futures\";\n  const restUrl = parameters.restUrl ?? BINANCE_DEPTH_REST_URL[market];\n  const wsUrl = parameters.wsUrl ?? BINANCE_DEPTH_WS_URL[market];\n  const resolveSymbol = parameters.resolveSymbol ?? defaultResolveSymbol;\n  const supportedLimits = BINANCE_DEPTH_LIMITS[market];\n  const defaultLimit = BINANCE_DEPTH_DEFAULT_LIMIT[market];\n  const updateSpeed = parameters.updateSpeed ?? BINANCE_DEPTH_DEFAULT_UPDATE_SPEED[market];\n\n  if (!BINANCE_DEPTH_UPDATE_SPEEDS[market].includes(updateSpeed)) {\n    throw new SymmError(\n      \"validation\",\n      \"UNSUPPORTED_DEPTH_UPDATE_SPEED\",\n      `Binance ${market} has no ${updateSpeed}ms depth stream. Supported: ${BINANCE_DEPTH_UPDATE_SPEEDS[market].join(\", \")}ms.`,\n    );\n  }\n\n  /**\n   * `exchangeInfo` lists every contract on the venue and only changes on a\n   * listing or delisting, so it is fetched once per source and shared by every\n   * `getSymbol` call. The promise itself is cached so concurrent callers during\n   * the first load share one request; a rejection clears it so a transient\n   * failure does not poison the source for its lifetime.\n   */\n  let symbolFilters: Promise<Map<string, BinanceSymbolFilters>> | null = null;\n\n  function getSymbolFilters(): Promise<Map<string, BinanceSymbolFilters>> {\n    if (!symbolFilters) {\n      symbolFilters = fetchBinanceSymbolFilters(restUrl, market).catch((err: unknown) => {\n        symbolFilters = null;\n        throw err;\n      });\n    }\n    return symbolFilters;\n  }\n\n  function requireSourceSymbol(marketName: string): string {\n    const symbol = resolveSymbol(marketName);\n    if (!symbol) {\n      throw new SymmError(\n        \"validation\",\n        \"UNMAPPED_ORDERBOOK_MARKET\",\n        `No Binance symbol is mapped for market \"${marketName}\".`,\n      );\n    }\n    return symbol;\n  }\n\n  function requireLimit(requested: number | undefined): number {\n    const limit = requested ?? defaultLimit;\n    if (!supportedLimits.includes(limit)) {\n      throw new SymmError(\n        \"validation\",\n        \"UNSUPPORTED_DEPTH_LIMIT\",\n        `Binance ${market} rejects a depth limit of ${limit}. Supported: ${supportedLimits.join(\", \")}.`,\n      );\n    }\n    return limit;\n  }\n\n  return {\n    id: `binance:${market}`,\n    priceBasis: \"reference-exchange\",\n    supportedLimits,\n    defaultLimit,\n\n    async getSymbol(marketName: string): Promise<OrderbookSymbol | undefined> {\n      const sourceSymbol = resolveSymbol(marketName);\n      if (!sourceSymbol) return undefined;\n\n      const filters = (await getSymbolFilters()).get(sourceSymbol.toUpperCase());\n      if (!filters) return undefined;\n\n      return {\n        marketName,\n        sourceSymbol: filters.symbol,\n        baseAsset: filters.baseAsset,\n        quoteAsset: filters.quoteAsset,\n        pricePrecision: filters.pricePrecision,\n        sizePrecision: filters.sizePrecision,\n        tickSize: filters.tickSize,\n      };\n    },\n\n    /**\n     * `async` so that a validation failure arrives as a rejected promise rather\n     * than a synchronous throw. A method typed `Promise<Orderbook>` that throws\n     * before returning is hostile to callers: `.catch()` never sees it, and a\n     * TanStack `queryFn` would blow up outside the query's own error handling.\n     */\n    async getOrderbook(getOrderbookParameters: GetOrderbookParameters): Promise<Orderbook> {\n      const { marketName, limit, signal } = getOrderbookParameters;\n\n      return fetchBinanceDepth({\n        restUrl,\n        market,\n        symbol: requireSourceSymbol(marketName),\n        marketName,\n        limit: requireLimit(limit),\n        signal,\n      });\n    },\n\n    watchOrderbook(watchOrderbookParameters: WatchOrderbookParameters): Unwatch {\n      const { marketName, limit, levels, onOrderbook, onResync, onStatusChange, onError } = watchOrderbookParameters;\n\n      return watchBinanceDepth({\n        restUrl,\n        wsUrl,\n        market,\n        symbol: requireSourceSymbol(marketName),\n        marketName,\n        limit: requireLimit(limit),\n        levels: levels && levels > 0 ? levels : BINANCE_DEPTH_DEFAULT_LEVELS,\n        updateSpeed,\n        webSocketConstructor: resolveWebSocketConstructor(parameters.webSocketConstructor),\n        onOrderbook,\n        onResync,\n        onStatusChange,\n        onError,\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;AAmEA,SAAS,EAAqB,GAA4B;CACxD,OAAO,EAAW,YAAY;AAChC;AAEA,SAAS,EAA4B,GAAuD;CAC1F,IAAM,IAAO,KAAa,WAAoD;CAC9E,IAAI,CAAC,GACH,MAAM,IAAI,EACR,UACA,+BACA,qIACF;CAEF,OAAO;AACT;AAiCA,SAAgB,EAA6B,IAA+C,CAAC,GAAoB;CAC/G,IAAM,IAAS,EAAW,UAAU,iBAC9B,IAAU,EAAW,WAAW,EAAuB,IACvD,IAAQ,EAAW,SAAS,EAAqB,IACjD,IAAgB,EAAW,iBAAiB,GAC5C,IAAkB,EAAqB,IACvC,IAAe,EAA4B,IAC3C,IAAc,EAAW,eAAe,EAAmC;CAEjF,IAAI,CAAC,EAA4B,GAAQ,SAAS,CAAW,GAC3D,MAAM,IAAI,EACR,cACA,kCACA,WAAW,EAAO,UAAU,EAAY,8BAA8B,EAA4B,GAAQ,KAAK,IAAI,EAAE,IACvH;CAUF,IAAI,IAAmE;CAEvE,SAAS,IAA+D;EAOtE,OANA,AACE,MAAgB,EAA0B,GAAS,CAAM,EAAE,OAAO,MAAiB;GAEjF,MADA,IAAgB,MACV;EACR,CAAC,GAEI;CACT;CAEA,SAAS,EAAoB,GAA4B;EACvD,IAAM,IAAS,EAAc,CAAU;EACvC,IAAI,CAAC,GACH,MAAM,IAAI,EACR,cACA,6BACA,2CAA2C,EAAW,GACxD;EAEF,OAAO;CACT;CAEA,SAAS,EAAa,GAAuC;EAC3D,IAAM,IAAQ,KAAa;EAC3B,IAAI,CAAC,EAAgB,SAAS,CAAK,GACjC,MAAM,IAAI,EACR,cACA,2BACA,WAAW,EAAO,4BAA4B,EAAM,eAAe,EAAgB,KAAK,IAAI,EAAE,EAChG;EAEF,OAAO;CACT;CAEA,OAAO;EACL,IAAI,WAAW;EACf,YAAY;EACZ;EACA;EAEA,MAAM,UAAU,GAA0D;GACxE,IAAM,IAAe,EAAc,CAAU;GAC7C,IAAI,CAAC,GAAc;GAEnB,IAAM,KAAW,MAAM,EAAiB,GAAG,IAAI,EAAa,YAAY,CAAC;GACpE,OAEL,OAAO;IACL;IACA,cAAc,EAAQ;IACtB,WAAW,EAAQ;IACnB,YAAY,EAAQ;IACpB,gBAAgB,EAAQ;IACxB,eAAe,EAAQ;IACvB,UAAU,EAAQ;GACpB;EACF;EAQA,MAAM,aAAa,GAAoE;GACrF,IAAM,EAAE,eAAY,UAAO,cAAW;GAEtC,OAAO,EAAkB;IACvB;IACA;IACA,QAAQ,EAAoB,CAAU;IACtC;IACA,OAAO,EAAa,CAAK;IACzB;GACF,CAAC;EACH;EAEA,eAAe,GAA6D;GAC1E,IAAM,EAAE,eAAY,UAAO,WAAQ,gBAAa,aAAU,mBAAgB,eAAY;GAEtF,OAAO,EAAkB;IACvB;IACA;IACA;IACA,QAAQ,EAAoB,CAAU;IACtC;IACA,OAAO,EAAa,CAAK;IACzB,QAAQ,KAAU,IAAS,IAAI,IAAA;IAC/B;IACA,sBAAsB,EAA4B,EAAW,oBAAoB;IACjF;IACA;IACA;IACA;GACF,CAAC;EACH;CACF;AACF"}

package/dist/orderbook/sources/binance/fetch-binance-depth.d.ts

@@ -0,0 +1,45 @@
+import { Orderbook } from '../../types.js';
+import { BinanceOrderbookMarket } from './constants.js';
+/**
+ * Parameters for {@link fetchBinanceDepth}.
+ */
+export interface FetchBinanceDepthParameters {
+    /** REST host, without a trailing slash. */
+    restUrl: string;
+    /** Which Binance market to read. */
+    market: BinanceOrderbookMarket;
+    /** Binance symbol, upper-case (e.g. `"BTCUSDT"`). */
+    symbol: string;
+    /** Market name as SYMMIO names it, carried onto the returned book. */
+    marketName: string;
+    /** Levels per side. Must already be validated against the market's allowed depths. */
+    limit: number;
+    /** Aborts the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Fetch a depth snapshot and normalize it into an {@link Orderbook}.
+ *
+ * Binance returns bids descending and asks ascending, which is the SDK's own
+ * ordering, so no re-sorting is needed. Zero-size levels never appear in a
+ * snapshot (only in the diff stream, where a zero means removal) but are
+ * filtered defensively so a snapshot can never seed a phantom level.
+ *
+ * @param parameters - Endpoint, symbol, and depth.
+ * @returns The snapshot, synchronized to `lastUpdateId`.
+ * @throws {SymmApiError} when the request fails with an HTTP response.
+ * @throws {SymmError} when the response is not a depth snapshot.
+ *
+ * @example
+ * ```ts
+ * const book = await fetchBinanceDepth({
+ *   restUrl: "https://fapi.binance.com",
+ *   market: "usd-m-futures",
+ *   symbol: "BTCUSDT",
+ *   marketName: "BTCUSDT",
+ *   limit: 100,
+ * });
+ * ```
+ */
+export declare function fetchBinanceDepth(parameters: FetchBinanceDepthParameters): Promise<Orderbook>;
+//# sourceMappingURL=fetch-binance-depth.d.ts.map

package/dist/orderbook/sources/binance/fetch-binance-depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-depth.d.ts","sourceRoot":"","sources":["../../../../src/orderbook/sources/binance/fetch-binance-depth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAsB,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG9E;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,2BAA2B,GAAG,OAAO,CAAC,SAAS,CAAC,CA0CnG"}

package/dist/orderbook/sources/binance/fetch-binance-depth.js

@@ -0,0 +1,34 @@
+import { SymmApiError as e, SymmError as t } from "../../../shared/errors/symm-error.js";
+import { BINANCE_DEPTH_PATH as n } from "./constants.js";
+import { parseBinanceDepthLevels as r } from "./parse-depth.js";
+import i, { isAxiosError as a } from "axios";
+//#region src/orderbook/sources/binance/fetch-binance-depth.ts
+async function o(o) {
+	let { restUrl: s, market: c, symbol: l, marketName: u, limit: d, signal: f } = o, p = `${s}${n[c]}`;
+	try {
+		let e = (await i.get(p, {
+			params: {
+				symbol: l,
+				limit: d
+			},
+			signal: f
+		})).data;
+		if (!e || typeof e.lastUpdateId != "number" || !Array.isArray(e.bids)) throw new t("api", "FETCH_BINANCE_DEPTH_FAILED", `Binance depth response was not a snapshot for ${l}.`);
+		return {
+			marketName: u,
+			bids: r(e.bids).filter((e) => e.size > 0),
+			asks: r(e.asks).filter((e) => e.size > 0),
+			lastUpdateId: e.lastUpdateId,
+			timestamp: e.T ?? e.E ?? 0
+		};
+	} catch (n) {
+		throw n instanceof t ? n : a(n) ? e.fromAxios(n, {
+			code: "FETCH_BINANCE_DEPTH_FAILED",
+			baseURL: s
+		}) : new t("api", "FETCH_BINANCE_DEPTH_FAILED", `Failed to fetch Binance depth for ${l}: ${n instanceof Error ? n.message : String(n)}`, { cause: n instanceof Error ? n : void 0 });
+	}
+}
+//#endregion
+export { o as fetchBinanceDepth };
+
+//# sourceMappingURL=fetch-binance-depth.js.map

package/dist/orderbook/sources/binance/fetch-binance-depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-depth.js","names":[],"sources":["../../../../src/orderbook/sources/binance/fetch-binance-depth.ts"],"sourcesContent":["import axios, { isAxiosError } from \"axios\";\nimport { SymmApiError, SymmError } from \"../../../shared/errors/symm-error\";\nimport type { Orderbook } from \"../../types\";\nimport { BINANCE_DEPTH_PATH, type BinanceOrderbookMarket } from \"./constants\";\nimport { parseBinanceDepthLevels, type RawBinanceDepthSnapshot } from \"./parse-depth\";\n\n/**\n * Parameters for {@link fetchBinanceDepth}.\n */\nexport interface FetchBinanceDepthParameters {\n  /** REST host, without a trailing slash. */\n  restUrl: string;\n  /** Which Binance market to read. */\n  market: BinanceOrderbookMarket;\n  /** Binance symbol, upper-case (e.g. `\"BTCUSDT\"`). */\n  symbol: string;\n  /** Market name as SYMMIO names it, carried onto the returned book. */\n  marketName: string;\n  /** Levels per side. Must already be validated against the market's allowed depths. */\n  limit: number;\n  /** Aborts the request. */\n  signal?: AbortSignal;\n}\n\n/**\n * Fetch a depth snapshot and normalize it into an {@link Orderbook}.\n *\n * Binance returns bids descending and asks ascending, which is the SDK's own\n * ordering, so no re-sorting is needed. Zero-size levels never appear in a\n * snapshot (only in the diff stream, where a zero means removal) but are\n * filtered defensively so a snapshot can never seed a phantom level.\n *\n * @param parameters - Endpoint, symbol, and depth.\n * @returns The snapshot, synchronized to `lastUpdateId`.\n * @throws {SymmApiError} when the request fails with an HTTP response.\n * @throws {SymmError} when the response is not a depth snapshot.\n *\n * @example\n * ```ts\n * const book = await fetchBinanceDepth({\n *   restUrl: \"https://fapi.binance.com\",\n *   market: \"usd-m-futures\",\n *   symbol: \"BTCUSDT\",\n *   marketName: \"BTCUSDT\",\n *   limit: 100,\n * });\n * ```\n */\nexport async function fetchBinanceDepth(parameters: FetchBinanceDepthParameters): Promise<Orderbook> {\n  const { restUrl, market, symbol, marketName, limit, signal } = parameters;\n  const url = `${restUrl}${BINANCE_DEPTH_PATH[market]}`;\n\n  try {\n    const response = await axios.get<RawBinanceDepthSnapshot>(url, {\n      params: { symbol, limit },\n      signal,\n    });\n\n    const snapshot = response.data;\n\n    if (!snapshot || typeof snapshot.lastUpdateId !== \"number\" || !Array.isArray(snapshot.bids)) {\n      throw new SymmError(\n        \"api\",\n        \"FETCH_BINANCE_DEPTH_FAILED\",\n        `Binance depth response was not a snapshot for ${symbol}.`,\n      );\n    }\n\n    return {\n      marketName,\n      bids: parseBinanceDepthLevels(snapshot.bids).filter((level) => level.size > 0),\n      asks: parseBinanceDepthLevels(snapshot.asks).filter((level) => level.size > 0),\n      lastUpdateId: snapshot.lastUpdateId,\n      /** Spot omits both timestamps; `0` means \"the venue did not say\". */\n      timestamp: snapshot.T ?? snapshot.E ?? 0,\n    };\n  } catch (err) {\n    if (err instanceof SymmError) throw err;\n\n    if (isAxiosError(err)) {\n      throw SymmApiError.fromAxios(err, { code: \"FETCH_BINANCE_DEPTH_FAILED\", baseURL: restUrl });\n    }\n\n    throw new SymmError(\n      \"api\",\n      \"FETCH_BINANCE_DEPTH_FAILED\",\n      `Failed to fetch Binance depth for ${symbol}: ${err instanceof Error ? err.message : String(err)}`,\n      { cause: err instanceof Error ? err : undefined },\n    );\n  }\n}\n"],"mappings":";;;;;AAgDA,eAAsB,EAAkB,GAA6D;CACnG,IAAM,EAAE,YAAS,WAAQ,WAAQ,eAAY,UAAO,cAAW,GACzD,IAAM,GAAG,IAAU,EAAmB;CAE5C,IAAI;EAMF,IAAM,KAAW,MALM,EAAM,IAA6B,GAAK;GAC7D,QAAQ;IAAE;IAAQ;GAAM;GACxB;EACF,CAAC,GAEyB;EAE1B,IAAI,CAAC,KAAY,OAAO,EAAS,gBAAiB,YAAY,CAAC,MAAM,QAAQ,EAAS,IAAI,GACxF,MAAM,IAAI,EACR,OACA,8BACA,iDAAiD,EAAO,EAC1D;EAGF,OAAO;GACL;GACA,MAAM,EAAwB,EAAS,IAAI,EAAE,QAAQ,MAAU,EAAM,OAAO,CAAC;GAC7E,MAAM,EAAwB,EAAS,IAAI,EAAE,QAAQ,MAAU,EAAM,OAAO,CAAC;GAC7E,cAAc,EAAS;GAEvB,WAAW,EAAS,KAAK,EAAS,KAAK;EACzC;CACF,SAAS,GAAK;EAOZ,MANI,aAAe,IAAiB,IAEhC,EAAa,CAAG,IACZ,EAAa,UAAU,GAAK;GAAE,MAAM;GAA8B,SAAS;EAAQ,CAAC,IAGtF,IAAI,EACR,OACA,8BACA,qCAAqC,EAAO,IAAI,aAAe,QAAQ,EAAI,UAAU,OAAO,CAAG,KAC/F,EAAE,OAAO,aAAe,QAAQ,IAAM,KAAA,EAAU,CAClD;CACF;AACF"}

package/dist/orderbook/sources/binance/fetch-binance-symbol-filters.d.ts

@@ -0,0 +1,39 @@
+import { BinanceOrderbookMarket } from './constants.js';
+/**
+ * Trading increments and precisions for one Binance symbol.
+ *
+ * `tickSize` and `stepSize` are what the venue actually enforces; the two
+ * precisions are derived from them so a UI's decimal count can never disagree
+ * with the grid the venue quotes on.
+ */
+export interface BinanceSymbolFilters {
+    /** Binance symbol, upper-case. */
+    symbol: string;
+    /** Base asset (e.g. `"BTC"`). */
+    baseAsset: string;
+    /** Quote asset (e.g. `"USDT"`). */
+    quoteAsset: string;
+    /** Smallest price increment the venue allows. */
+    tickSize: number;
+    /** Smallest quantity increment the venue allows. */
+    stepSize: number;
+    /** Decimal places implied by {@link BinanceSymbolFilters.tickSize}. */
+    pricePrecision: number;
+    /** Decimal places implied by {@link BinanceSymbolFilters.stepSize}. */
+    sizePrecision: number;
+}
+/**
+ * Fetch Binance `exchangeInfo` and index each symbol's increments by symbol.
+ *
+ * Called once per source instance and cached — the response lists every
+ * contract on the venue and only changes on a listing or delisting.
+ *
+ * @param restUrl - REST host, without a trailing slash.
+ * @param market - Which Binance market to describe.
+ * @param signal - Aborts the request.
+ * @returns Increments and precisions keyed by upper-case Binance symbol.
+ * @throws {SymmApiError} when the request fails with an HTTP response.
+ * @throws {SymmError} when the response has no `symbols` array.
+ */
+export declare function fetchBinanceSymbolFilters(restUrl: string, market: BinanceOrderbookMarket, signal?: AbortSignal): Promise<Map<string, BinanceSymbolFilters>>;
+//# sourceMappingURL=fetch-binance-symbol-filters.d.ts.map

package/dist/orderbook/sources/binance/fetch-binance-symbol-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-symbol-filters.d.ts","sourceRoot":"","sources":["../../../../src/orderbook/sources/binance/fetch-binance-symbol-filters.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAgBhG;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;CACvB;AAgCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,sBAAsB,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CA8B5C"}