@symmio/trading-core 1.1.0 → 3.0.0

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

@@ -0,0 +1,46 @@
+/**
+ * Which Binance market a candle source reads from.
+ *
+ * `usd-m-futures` is the default and the correct choice for charting a SYMMIO
+ * perp: its symbols are perpetual contracts, so the series matches what the
+ * instrument actually is. `spot` is offered for markets that have no futures
+ * listing.
+ */
+export type BinanceMarket = "usd-m-futures" | "spot";
+/** Default REST hosts per market. */
+export declare const BINANCE_REST_URL: Record<BinanceMarket, string>;
+/**
+ * Default combined-stream WebSocket endpoints per market.
+ *
+ * The `/stream` (combined) form is used rather than `/ws` (raw) so every frame
+ * arrives wrapped as `{ stream, data }` and further streams can be multiplexed
+ * onto one connection later without changing the parse path.
+ *
+ * The futures `/market/` prefix is deliberate and verified against the live
+ * endpoint: on `fstream.binance.com` the documented `/stream` and `/ws` forms
+ * accept the SUBSCRIBE frame, acknowledge it with `{"result":null}`, and then
+ * never push a single kline — a feed that reports `open` and silently never
+ * ticks. Only the `/market/` paths deliver frames. Spot needs no such prefix.
+ */
+export declare const BINANCE_WS_URL: Record<BinanceMarket, string>;
+/** Klines REST path per market. */
+export declare const BINANCE_KLINES_PATH: Record<BinanceMarket, string>;
+/** Exchange-info REST path per market, used to resolve price precision. */
+export declare const BINANCE_EXCHANGE_INFO_PATH: Record<BinanceMarket, string>;
+/**
+ * Maximum bars a single klines request may ask for.
+ *
+ * Exceeding this is a hard error (`-1130 Data sent for parameter 'limit' is not
+ * valid`), not a silent clamp, so requests are capped against it before being
+ * sent. Futures allows 1500; spot allows 1000.
+ */
+export declare const BINANCE_MAX_LIMIT: Record<BinanceMarket, number>;
+/**
+ * Upper bound on paging iterations inside a single `getCandles` call.
+ *
+ * A safety net only: paging normally stops because the venue returned a short
+ * batch or the caller's `limit` was met. This guarantees the loop terminates
+ * even if the venue keeps returning full batches that never advance the cursor.
+ */
+export declare const BINANCE_MAX_PAGES = 50;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/candles/sources/binance/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,MAAM,CAAC;AAErD,qCAAqC;AACrC,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAG1D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAGxD,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAG7D,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAGpE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAG3D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC"}

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

@@ -0,0 +1,21 @@
+//#region src/candles/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/market/stream",
+	spot: "wss://stream.binance.com:9443/stream"
+}, n = {
+	"usd-m-futures": "/fapi/v1/klines",
+	spot: "/api/v3/klines"
+}, r = {
+	"usd-m-futures": "/fapi/v1/exchangeInfo",
+	spot: "/api/v3/exchangeInfo"
+}, i = {
+	"usd-m-futures": 1500,
+	spot: 1e3
+};
+//#endregion
+export { r as BINANCE_EXCHANGE_INFO_PATH, n as BINANCE_KLINES_PATH, i as BINANCE_MAX_LIMIT, e as BINANCE_REST_URL, t as BINANCE_WS_URL };
+
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../../../src/candles/sources/binance/constants.ts"],"sourcesContent":["/**\n * Which Binance market a candle source reads from.\n *\n * `usd-m-futures` is the default and the correct choice for charting a SYMMIO\n * perp: its symbols are perpetual contracts, so the series matches what the\n * instrument actually is. `spot` is offered for markets that have no futures\n * listing.\n */\nexport type BinanceMarket = \"usd-m-futures\" | \"spot\";\n\n/** Default REST hosts per market. */\nexport const BINANCE_REST_URL: Record<BinanceMarket, 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 `/stream` (combined) form is used rather than `/ws` (raw) so every frame\n * arrives wrapped as `{ stream, data }` and further streams can be multiplexed\n * onto one connection later without changing the parse path.\n *\n * The futures `/market/` prefix is deliberate and verified against the live\n * endpoint: on `fstream.binance.com` the documented `/stream` and `/ws` forms\n * accept the SUBSCRIBE frame, acknowledge it with `{\"result\":null}`, and then\n * never push a single kline — a feed that reports `open` and silently never\n * ticks. Only the `/market/` paths deliver frames. Spot needs no such prefix.\n */\nexport const BINANCE_WS_URL: Record<BinanceMarket, string> = {\n  \"usd-m-futures\": \"wss://fstream.binance.com/market/stream\",\n  spot: \"wss://stream.binance.com:9443/stream\",\n};\n\n/** Klines REST path per market. */\nexport const BINANCE_KLINES_PATH: Record<BinanceMarket, string> = {\n  \"usd-m-futures\": \"/fapi/v1/klines\",\n  spot: \"/api/v3/klines\",\n};\n\n/** Exchange-info REST path per market, used to resolve price precision. */\nexport const BINANCE_EXCHANGE_INFO_PATH: Record<BinanceMarket, string> = {\n  \"usd-m-futures\": \"/fapi/v1/exchangeInfo\",\n  spot: \"/api/v3/exchangeInfo\",\n};\n\n/**\n * Maximum bars a single klines request may ask for.\n *\n * Exceeding this is a hard error (`-1130 Data sent for parameter 'limit' is not\n * valid`), not a silent clamp, so requests are capped against it before being\n * sent. Futures allows 1500; spot allows 1000.\n */\nexport const BINANCE_MAX_LIMIT: Record<BinanceMarket, number> = {\n  \"usd-m-futures\": 1500,\n  spot: 1000,\n};\n\n/**\n * Upper bound on paging iterations inside a single `getCandles` call.\n *\n * A safety net only: paging normally stops because the venue returned a short\n * batch or the caller's `limit` was met. This guarantees the loop terminates\n * even if the venue keeps returning full batches that never advance the cursor.\n */\nexport const BINANCE_MAX_PAGES = 50;\n"],"mappings":";AAWA,IAAa,IAAkD;CAC7D,iBAAiB;CACjB,MAAM;AACR,GAea,IAAgD;CAC3D,iBAAiB;CACjB,MAAM;AACR,GAGa,IAAqD;CAChE,iBAAiB;CACjB,MAAM;AACR,GAGa,IAA4D;CACvE,iBAAiB;CACjB,MAAM;AACR,GASa,IAAmD;CAC9D,iBAAiB;CACjB,MAAM;AACR"}

package/dist/candles/sources/binance/create-binance-candle-source.d.ts

@@ -0,0 +1,65 @@
+import { WebSocketConstructor } from '../../../shared/types/websocket.js';
+import { CandleSource } from '../../types.js';
+import { BinanceMarket } from './constants.js';
+/**
+ * Parameters for {@link createBinanceCandleSource}.
+ */
+export interface BinanceCandleSourceParameters {
+    /**
+     * Which Binance market to read. Defaults to `"usd-m-futures"` — its symbols
+     * are perpetual contracts, matching what a SYMMIO market actually is.
+     */
+    market?: BinanceMarket;
+    /** Override the REST host (a regional mirror, or your own caching proxy). */
+    restUrl?: string;
+    /** Override the WebSocket endpoint. */
+    wsUrl?: string;
+    /**
+     * 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 chart simply stays empty.
+     */
+    resolveSymbol?: (marketName: string) => string | undefined;
+    /**
+     * WebSocket implementation for {@link CandleSource.watchCandles}. Defaults to
+     * `globalThis.WebSocket`; pass the `ws` package in Node environments without one.
+     */
+    webSocketConstructor?: WebSocketConstructor;
+}
+/**
+ * Create a {@link CandleSource} backed by Binance klines.
+ *
+ * History comes from the REST `/klines` endpoint, paged backwards from the end
+ * of the requested range, and live bars from the kline WebSocket stream. 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 chart built on this:
+ * - The series is `priceBasis: "reference-exchange"`. It is Binance's perp
+ *   price, not the SYMMIO solver's mark price that a trade actually settles at.
+ * - `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 `getCandlesQueryOptions`, `useCandles`, or
+ *   `toTradingViewDatafeed`.
+ *
+ * @example
+ * ```ts
+ * const source = createBinanceCandleSource();
+ * const { candles } = await source.getCandles({
+ *   marketName: "BTCUSDT",
+ *   resolution: "1m",
+ *   from: Date.now() - 60 * 60 * 1000,
+ *   to: Date.now(),
+ *   limit: 60,
+ * });
+ * ```
+ */
+export declare function createBinanceCandleSource(parameters?: BinanceCandleSourceParameters): CandleSource;
+//# sourceMappingURL=create-binance-candle-source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-binance-candle-source.d.ts","sourceRoot":"","sources":["../../../../src/candles/sources/binance/create-binance-candle-source.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE5E,OAAO,KAAK,EAGV,YAAY,EAKb,MAAM,aAAa,CAAC;AACrB,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC3D;;;OAGG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,GAAE,6BAAkC,GAAG,YAAY,CAqJtG"}

package/dist/candles/sources/binance/create-binance-candle-source.js

@@ -0,0 +1,92 @@
+import { SymmError as e } from "../../../shared/errors/symm-error.js";
+import { BINANCE_MAX_LIMIT as t, BINANCE_REST_URL as n, BINANCE_WS_URL as r } from "./constants.js";
+import { fetchBinanceKlines as i } from "./fetch-binance-klines.js";
+import { fetchBinanceExchangeInfo as a } from "./fetch-binance-exchange-info.js";
+import { getBinanceSupportedResolutions as o, toBinanceInterval as s } from "./map-resolution.js";
+import { watchBinanceKlines as c } from "./watch-binance-klines.js";
+//#region src/candles/sources/binance/create-binance-candle-source.ts
+function l(e) {
+	return e.toUpperCase();
+}
+function u(t) {
+	let n = t ?? globalThis.WebSocket;
+	if (!n) throw new e("config", "NO_WEBSOCKET_IMPLEMENTATION", "No WebSocket implementation available. Pass `webSocketConstructor` to createBinanceCandleSource (e.g. the `ws` package in Node).");
+	return n;
+}
+function d(d = {}) {
+	let f = d.market ?? "usd-m-futures", p = d.restUrl ?? n[f], m = d.wsUrl ?? r[f], h = d.resolveSymbol ?? l, g = t[f], _ = null;
+	function v() {
+		return _ ||= a(p, f).catch((e) => {
+			throw _ = null, e;
+		}), _;
+	}
+	function y(t) {
+		let n = s(f, t);
+		if (!n) throw new e("validation", "UNSUPPORTED_CANDLE_RESOLUTION", `Binance ${f} has no klines interval for resolution "${t}".`);
+		return n;
+	}
+	function b(t) {
+		let n = h(t);
+		if (!n) throw new e("validation", "UNMAPPED_CANDLE_MARKET", `No Binance symbol is mapped for market "${t}".`);
+		return n;
+	}
+	return {
+		id: `binance:${f}`,
+		priceBasis: "reference-exchange",
+		supportedResolutions: o(f),
+		maxCandlesPerRequest: g,
+		async getSymbol(e) {
+			let t = h(e);
+			if (!t) return;
+			let n = (await v()).get(t.toUpperCase());
+			if (!n) return;
+			let r = n.baseAsset && n.quoteAsset ? `${n.baseAsset} / ${n.quoteAsset}` : n.symbol;
+			return {
+				marketName: e,
+				sourceSymbol: n.symbol,
+				description: r,
+				pricePrecision: n.pricePrecision,
+				volumePrecision: 2
+			};
+		},
+		async getCandles(e) {
+			let { marketName: t, resolution: n, from: r, to: a, limit: o, signal: s } = e, c = y(n), l = b(t), u = o && o > 0 ? o : Infinity, d = [], m = a - 1;
+			for (let e = 0; e < 50 && !(m < r); e++) {
+				let e = u - d.length, t = Math.max(1, Math.min(g, e)), n = await i({
+					restUrl: p,
+					market: f,
+					symbol: l,
+					interval: c,
+					endTime: m,
+					limit: t,
+					signal: s
+				}), o = n[0];
+				if (!o || (d.unshift(...n.filter((e) => e.time >= r && e.time < a)), o.time <= r || n.length < t) || d.length >= u) break;
+				let h = o.time - 1;
+				if (h >= m) break;
+				m = h;
+			}
+			return {
+				candles: d,
+				noMoreData: d.length === 0
+			};
+		},
+		watchCandles(e) {
+			let { marketName: t, resolution: n, onCandle: r, onReset: i, onStatusChange: a, onError: o } = e;
+			return c({
+				wsUrl: m,
+				symbol: b(t),
+				interval: y(n),
+				webSocketConstructor: u(d.webSocketConstructor),
+				onCandle: r,
+				onReset: i,
+				onStatusChange: a,
+				onError: o
+			});
+		}
+	};
+}
+//#endregion
+export { d as createBinanceCandleSource };
+
+//# sourceMappingURL=create-binance-candle-source.js.map

package/dist/candles/sources/binance/create-binance-candle-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-binance-candle-source.js","names":[],"sources":["../../../../src/candles/sources/binance/create-binance-candle-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  Candle,\n  CandleResolution,\n  CandleSource,\n  CandleSymbol,\n  GetCandlesParameters,\n  GetCandlesReturnType,\n  WatchCandlesParameters,\n} from \"../../types\";\nimport {\n  BINANCE_MAX_LIMIT,\n  BINANCE_MAX_PAGES,\n  BINANCE_REST_URL,\n  BINANCE_WS_URL,\n  type BinanceMarket,\n} from \"./constants\";\nimport { fetchBinanceExchangeInfo, type BinanceSymbolInfo } from \"./fetch-binance-exchange-info\";\nimport { fetchBinanceKlines } from \"./fetch-binance-klines\";\nimport { getBinanceSupportedResolutions, toBinanceInterval } from \"./map-resolution\";\nimport { watchBinanceKlines } from \"./watch-binance-klines\";\n\n/**\n * Parameters for {@link createBinanceCandleSource}.\n */\nexport interface BinanceCandleSourceParameters {\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?: BinanceMarket;\n  /** Override the REST host (a regional mirror, or your own caching proxy). */\n  restUrl?: string;\n  /** Override the WebSocket endpoint. */\n  wsUrl?: string;\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 chart simply stays empty.\n   */\n  resolveSymbol?: (marketName: string) => string | undefined;\n  /**\n   * WebSocket implementation for {@link CandleSource.watchCandles}. Defaults to\n   * `globalThis.WebSocket`; pass the `ws` package in Node 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 createBinanceCandleSource (e.g. the `ws` package in Node).\",\n    );\n  }\n  return ctor;\n}\n\n/**\n * Create a {@link CandleSource} backed by Binance klines.\n *\n * History comes from the REST `/klines` endpoint, paged backwards from the end\n * of the requested range, and live bars from the kline WebSocket stream. Both\n * are reachable directly from a browser — Binance serves permissive CORS\n * headers on market data, so no proxy or API key is involved.\n *\n * Two caveats worth surfacing to users of a chart built on this:\n * - The series is `priceBasis: \"reference-exchange\"`. It is Binance's perp\n *   price, not the SYMMIO solver's mark price that a trade actually settles at.\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 `getCandlesQueryOptions`, `useCandles`, or\n *   `toTradingViewDatafeed`.\n *\n * @example\n * ```ts\n * const source = createBinanceCandleSource();\n * const { candles } = await source.getCandles({\n *   marketName: \"BTCUSDT\",\n *   resolution: \"1m\",\n *   from: Date.now() - 60 * 60 * 1000,\n *   to: Date.now(),\n *   limit: 60,\n * });\n * ```\n */\nexport function createBinanceCandleSource(parameters: BinanceCandleSourceParameters = {}): CandleSource {\n  const market = parameters.market ?? \"usd-m-futures\";\n  const restUrl = parameters.restUrl ?? BINANCE_REST_URL[market];\n  const wsUrl = parameters.wsUrl ?? BINANCE_WS_URL[market];\n  const resolveSymbol = parameters.resolveSymbol ?? defaultResolveSymbol;\n  const maxLimit = BINANCE_MAX_LIMIT[market];\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 exchangeInfo: Promise<Map<string, BinanceSymbolInfo>> | null = null;\n\n  function getExchangeInfo(): Promise<Map<string, BinanceSymbolInfo>> {\n    if (!exchangeInfo) {\n      exchangeInfo = fetchBinanceExchangeInfo(restUrl, market).catch((err: unknown) => {\n        exchangeInfo = null;\n        throw err;\n      });\n    }\n    return exchangeInfo;\n  }\n\n  function requireInterval(resolution: CandleResolution): string {\n    const interval = toBinanceInterval(market, resolution);\n    if (!interval) {\n      throw new SymmError(\n        \"validation\",\n        \"UNSUPPORTED_CANDLE_RESOLUTION\",\n        `Binance ${market} has no klines interval for resolution \"${resolution}\".`,\n      );\n    }\n    return interval;\n  }\n\n  function requireSourceSymbol(marketName: string): string {\n    const symbol = resolveSymbol(marketName);\n    if (!symbol) {\n      throw new SymmError(\n        \"validation\",\n        \"UNMAPPED_CANDLE_MARKET\",\n        `No Binance symbol is mapped for market \"${marketName}\".`,\n      );\n    }\n    return symbol;\n  }\n\n  return {\n    id: `binance:${market}`,\n    priceBasis: \"reference-exchange\",\n    supportedResolutions: getBinanceSupportedResolutions(market),\n    maxCandlesPerRequest: maxLimit,\n\n    async getSymbol(marketName: string): Promise<CandleSymbol | undefined> {\n      const sourceSymbol = resolveSymbol(marketName);\n      if (!sourceSymbol) return undefined;\n\n      const info = (await getExchangeInfo()).get(sourceSymbol.toUpperCase());\n      if (!info) return undefined;\n\n      const description = info.baseAsset && info.quoteAsset ? `${info.baseAsset} / ${info.quoteAsset}` : info.symbol;\n\n      return {\n        marketName,\n        sourceSymbol: info.symbol,\n        description,\n        pricePrecision: info.pricePrecision,\n        /** Binance reports base-asset volume; two decimals reads well for every listed contract. */\n        volumePrecision: 2,\n      };\n    },\n\n    async getCandles(getCandlesParameters: GetCandlesParameters): Promise<GetCandlesReturnType> {\n      const { marketName, resolution, from, to, limit, signal } = getCandlesParameters;\n      const interval = requireInterval(resolution);\n      const symbol = requireSourceSymbol(marketName);\n      const wanted = limit && limit > 0 ? limit : Number.POSITIVE_INFINITY;\n\n      const candles: Candle[] = [];\n\n      /**\n       * Paged backwards from `to`, not forwards from `from`. Binance caps a\n       * range request from its *start*: sending `startTime`, `endTime` and\n       * `limit` together returns the OLDEST `limit` bars in the window, which\n       * for a chart is the wrong end entirely. Sending `endTime` alone returns\n       * the newest bars ending there, which is what a chart scrolling back\n       * actually needs; the `from` bound is then applied client-side.\n       */\n      let cursorEnd = to - 1;\n\n      for (let page = 0; page < BINANCE_MAX_PAGES; page++) {\n        if (cursorEnd < from) break;\n\n        const remaining = wanted - candles.length;\n        const requestLimit = Math.max(1, Math.min(maxLimit, remaining));\n\n        const batch = await fetchBinanceKlines({\n          restUrl,\n          market,\n          symbol,\n          interval,\n          endTime: cursorEnd,\n          limit: requestLimit,\n          signal,\n        });\n        const oldest = batch[0];\n        if (!oldest) break;\n\n        candles.unshift(...batch.filter((candle) => candle.time >= from && candle.time < to));\n\n        /** Reached the requested start, or the venue has nothing older. */\n        if (oldest.time <= from || batch.length < requestLimit) break;\n        if (candles.length >= wanted) break;\n\n        const nextCursor = oldest.time - 1;\n        /** No-progress guard: without it a venue quirk could spin the loop. */\n        if (nextCursor >= cursorEnd) break;\n        cursorEnd = nextCursor;\n      }\n\n      return {\n        candles,\n        /**\n         * An empty result is the venue saying it has nothing in this window —\n         * for a 24/7 market that means the range predates the listing, so a\n         * chart paging backwards should stop rather than keep asking.\n         */\n        noMoreData: candles.length === 0,\n      };\n    },\n\n    watchCandles(watchCandlesParameters: WatchCandlesParameters): Unwatch {\n      const { marketName, resolution, onCandle, onReset, onStatusChange, onError } = watchCandlesParameters;\n\n      return watchBinanceKlines({\n        wsUrl,\n        symbol: requireSourceSymbol(marketName),\n        interval: requireInterval(resolution),\n        webSocketConstructor: resolveWebSocketConstructor(parameters.webSocketConstructor),\n        onCandle,\n        onReset,\n        onStatusChange,\n        onError,\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;AAuDA,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,kIACF;CAEF,OAAO;AACT;AAgCA,SAAgB,EAA0B,IAA4C,CAAC,GAAiB;CACtG,IAAM,IAAS,EAAW,UAAU,iBAC9B,IAAU,EAAW,WAAW,EAAiB,IACjD,IAAQ,EAAW,SAAS,EAAe,IAC3C,IAAgB,EAAW,iBAAiB,GAC5C,IAAW,EAAkB,IAS/B,IAA+D;CAEnE,SAAS,IAA2D;EAOlE,OANA,AACE,MAAe,EAAyB,GAAS,CAAM,EAAE,OAAO,MAAiB;GAE/E,MADA,IAAe,MACT;EACR,CAAC,GAEI;CACT;CAEA,SAAS,EAAgB,GAAsC;EAC7D,IAAM,IAAW,EAAkB,GAAQ,CAAU;EACrD,IAAI,CAAC,GACH,MAAM,IAAI,EACR,cACA,iCACA,WAAW,EAAO,0CAA0C,EAAW,GACzE;EAEF,OAAO;CACT;CAEA,SAAS,EAAoB,GAA4B;EACvD,IAAM,IAAS,EAAc,CAAU;EACvC,IAAI,CAAC,GACH,MAAM,IAAI,EACR,cACA,0BACA,2CAA2C,EAAW,GACxD;EAEF,OAAO;CACT;CAEA,OAAO;EACL,IAAI,WAAW;EACf,YAAY;EACZ,sBAAsB,EAA+B,CAAM;EAC3D,sBAAsB;EAEtB,MAAM,UAAU,GAAuD;GACrE,IAAM,IAAe,EAAc,CAAU;GAC7C,IAAI,CAAC,GAAc;GAEnB,IAAM,KAAQ,MAAM,EAAgB,GAAG,IAAI,EAAa,YAAY,CAAC;GACrE,IAAI,CAAC,GAAM;GAEX,IAAM,IAAc,EAAK,aAAa,EAAK,aAAa,GAAG,EAAK,UAAU,KAAK,EAAK,eAAe,EAAK;GAExG,OAAO;IACL;IACA,cAAc,EAAK;IACnB;IACA,gBAAgB,EAAK;IAErB,iBAAiB;GACnB;EACF;EAEA,MAAM,WAAW,GAA2E;GAC1F,IAAM,EAAE,eAAY,eAAY,SAAM,OAAI,UAAO,cAAW,GACtD,IAAW,EAAgB,CAAU,GACrC,IAAS,EAAoB,CAAU,GACvC,IAAS,KAAS,IAAQ,IAAI,IAAQ,UAEtC,IAAoB,CAAC,GAUvB,IAAY,IAAK;GAErB,KAAK,IAAI,IAAO,GAAG,IAAA,MACb,MAAY,IAD2B,KAAQ;IAGnD,IAAM,IAAY,IAAS,EAAQ,QAC7B,IAAe,KAAK,IAAI,GAAG,KAAK,IAAI,GAAU,CAAS,CAAC,GAExD,IAAQ,MAAM,EAAmB;KACrC;KACA;KACA;KACA;KACA,SAAS;KACT,OAAO;KACP;IACF,CAAC,GACK,IAAS,EAAM;IAOrB,IANI,CAAC,MAEL,EAAQ,QAAQ,GAAG,EAAM,QAAQ,MAAW,EAAO,QAAQ,KAAQ,EAAO,OAAO,CAAE,CAAC,GAGhF,EAAO,QAAQ,KAAQ,EAAM,SAAS,MACtC,EAAQ,UAAU,GAAQ;IAE9B,IAAM,IAAa,EAAO,OAAO;IAEjC,IAAI,KAAc,GAAW;IAC7B,IAAY;GACd;GAEA,OAAO;IACL;IAMA,YAAY,EAAQ,WAAW;GACjC;EACF;EAEA,aAAa,GAAyD;GACpE,IAAM,EAAE,eAAY,eAAY,aAAU,YAAS,mBAAgB,eAAY;GAE/E,OAAO,EAAmB;IACxB;IACA,QAAQ,EAAoB,CAAU;IACtC,UAAU,EAAgB,CAAU;IACpC,sBAAsB,EAA4B,EAAW,oBAAoB;IACjF;IACA;IACA;IACA;GACF,CAAC;EACH;CACF;AACF"}

package/dist/candles/sources/binance/fetch-binance-exchange-info.d.ts

@@ -0,0 +1,40 @@
+import { BinanceMarket } from './constants.js';
+/**
+ * Per-symbol metadata resolved from Binance `exchangeInfo`.
+ */
+export interface BinanceSymbolInfo {
+    /** Binance symbol, upper-case. */
+    symbol: string;
+    /** Base asset (e.g. `"BTC"`), when the venue reports one. */
+    baseAsset?: string;
+    /** Quote asset (e.g. `"USDT"`), when the venue reports one. */
+    quoteAsset?: string;
+    /** Decimal places prices should be rendered at. */
+    pricePrecision: number;
+}
+/**
+ * Derive decimal places from a Binance `tickSize` string.
+ *
+ * `tickSize` is a decimal literal with trailing zeros (`"0.10"`, `"1.00"`), so
+ * the count of characters after the dot overstates the real precision; trailing
+ * zeros are stripped first.
+ *
+ * @param tickSize - The `PRICE_FILTER` tick size (e.g. `"0.010"`).
+ * @returns Significant decimal places (`"0.010"` → `2`).
+ */
+export declare function tickSizeToPrecision(tickSize: string): number;
+/**
+ * Fetch Binance `exchangeInfo` and index it by symbol.
+ *
+ * Called once per source instance and cached — the response is large (every
+ * listed contract) and its contents only change when Binance lists or delists.
+ *
+ * @param restUrl - REST host, without a trailing slash.
+ * @param market - Which Binance market to describe.
+ * @param signal - Aborts the request.
+ * @returns Symbol metadata 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 fetchBinanceExchangeInfo(restUrl: string, market: BinanceMarket, signal?: AbortSignal): Promise<Map<string, BinanceSymbolInfo>>;
+//# sourceMappingURL=fetch-binance-exchange-info.d.ts.map

package/dist/candles/sources/binance/fetch-binance-exchange-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-exchange-info.d.ts","sourceRoot":"","sources":["../../../../src/candles/sources/binance/fetch-binance-exchange-info.ts"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAc7E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK5D;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,EACrB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CA8BzC"}

package/dist/candles/sources/binance/fetch-binance-exchange-info.js

@@ -0,0 +1,34 @@
+import { SymmApiError as e, SymmError as t } from "../../../shared/errors/symm-error.js";
+import { BINANCE_EXCHANGE_INFO_PATH as n } from "./constants.js";
+import r, { isAxiosError as i } from "axios";
+//#region src/candles/sources/binance/fetch-binance-exchange-info.ts
+function a(e) {
+	let t = e.indexOf(".");
+	return t === -1 ? 0 : e.slice(t + 1).replace(/0+$/, "").length;
+}
+function o(e) {
+	let t = e.filters?.find((e) => e.filterType === "PRICE_FILTER"), n = t?.tickSize ? a(t.tickSize) : void 0;
+	return {
+		symbol: e.symbol,
+		baseAsset: e.baseAsset,
+		quoteAsset: e.quoteAsset,
+		pricePrecision: n ?? e.pricePrecision ?? 2
+	};
+}
+async function s(a, s, c) {
+	let l = `${a}${n[s]}`;
+	try {
+		let e = (await r.get(l, { signal: c })).data?.symbols;
+		if (!Array.isArray(e)) throw new t("api", "FETCH_BINANCE_EXCHANGE_INFO_FAILED", "Binance exchangeInfo response had no `symbols` array.");
+		return new Map(e.map((e) => [e.symbol.toUpperCase(), o(e)]));
+	} catch (n) {
+		throw n instanceof t ? n : i(n) ? e.fromAxios(n, {
+			code: "FETCH_BINANCE_EXCHANGE_INFO_FAILED",
+			baseURL: a
+		}) : new t("api", "FETCH_BINANCE_EXCHANGE_INFO_FAILED", `Failed to fetch Binance exchangeInfo: ${n instanceof Error ? n.message : String(n)}`, { cause: n instanceof Error ? n : void 0 });
+	}
+}
+//#endregion
+export { s as fetchBinanceExchangeInfo };
+
+//# sourceMappingURL=fetch-binance-exchange-info.js.map

package/dist/candles/sources/binance/fetch-binance-exchange-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-exchange-info.js","names":[],"sources":["../../../../src/candles/sources/binance/fetch-binance-exchange-info.ts"],"sourcesContent":["import axios, { isAxiosError } from \"axios\";\nimport { SymmApiError, SymmError } from \"../../../shared/errors/symm-error\";\nimport { BINANCE_EXCHANGE_INFO_PATH, type BinanceMarket } from \"./constants\";\n\n/**\n * The subset of a Binance `exchangeInfo` symbol entry the SDK reads.\n */\ninterface RawBinanceExchangeInfoSymbol {\n  symbol: string;\n  baseAsset?: string;\n  quoteAsset?: string;\n  /** Present on USD-M futures; absent on spot, where precision comes from the price filter. */\n  pricePrecision?: number;\n  filters?: { filterType?: string; tickSize?: string }[];\n}\n\n/**\n * Per-symbol metadata resolved from Binance `exchangeInfo`.\n */\nexport interface BinanceSymbolInfo {\n  /** Binance symbol, upper-case. */\n  symbol: string;\n  /** Base asset (e.g. `\"BTC\"`), when the venue reports one. */\n  baseAsset?: string;\n  /** Quote asset (e.g. `\"USDT\"`), when the venue reports one. */\n  quoteAsset?: string;\n  /** Decimal places prices should be rendered at. */\n  pricePrecision: number;\n}\n\n/**\n * Derive decimal places from a Binance `tickSize` string.\n *\n * `tickSize` is a decimal literal with trailing zeros (`\"0.10\"`, `\"1.00\"`), so\n * the count of characters after the dot overstates the real precision; trailing\n * zeros are stripped first.\n *\n * @param tickSize - The `PRICE_FILTER` tick size (e.g. `\"0.010\"`).\n * @returns Significant decimal places (`\"0.010\"` → `2`).\n */\nexport function tickSizeToPrecision(tickSize: string): number {\n  const dotIndex = tickSize.indexOf(\".\");\n  if (dotIndex === -1) return 0;\n  const fraction = tickSize.slice(dotIndex + 1).replace(/0+$/, \"\");\n  return fraction.length;\n}\n\nfunction toSymbolInfo(entry: RawBinanceExchangeInfoSymbol): BinanceSymbolInfo {\n  const priceFilter = entry.filters?.find((filter) => filter.filterType === \"PRICE_FILTER\");\n  const fromTickSize = priceFilter?.tickSize ? tickSizeToPrecision(priceFilter.tickSize) : undefined;\n\n  return {\n    symbol: entry.symbol,\n    baseAsset: entry.baseAsset,\n    quoteAsset: entry.quoteAsset,\n    /**\n     * The tick size is the authoritative increment a price can move by, so it\n     * is preferred; `pricePrecision` is the futures-only fallback and `2` the\n     * last resort for a venue that reports neither.\n     */\n    pricePrecision: fromTickSize ?? entry.pricePrecision ?? 2,\n  };\n}\n\n/**\n * Fetch Binance `exchangeInfo` and index it by symbol.\n *\n * Called once per source instance and cached — the response is large (every\n * listed contract) and its contents only change when Binance lists or delists.\n *\n * @param restUrl - REST host, without a trailing slash.\n * @param market - Which Binance market to describe.\n * @param signal - Aborts the request.\n * @returns Symbol metadata keyed by upper-case Binance symbol.\n * @throws {SymmApiError} when the request fails with an HTTP response.\n * @throws {SymmError} when the response has no `symbols` array.\n */\nexport async function fetchBinanceExchangeInfo(\n  restUrl: string,\n  market: BinanceMarket,\n  signal?: AbortSignal,\n): Promise<Map<string, BinanceSymbolInfo>> {\n  const url = `${restUrl}${BINANCE_EXCHANGE_INFO_PATH[market]}`;\n\n  try {\n    const response = await axios.get<{ symbols?: RawBinanceExchangeInfoSymbol[] }>(url, { signal });\n    const symbols = response.data?.symbols;\n\n    if (!Array.isArray(symbols)) {\n      throw new SymmError(\n        \"api\",\n        \"FETCH_BINANCE_EXCHANGE_INFO_FAILED\",\n        \"Binance exchangeInfo response had no `symbols` array.\",\n      );\n    }\n\n    return new Map(symbols.map((entry) => [entry.symbol.toUpperCase(), toSymbolInfo(entry)]));\n  } catch (err) {\n    if (err instanceof SymmError) throw err;\n\n    if (isAxiosError(err)) {\n      throw SymmApiError.fromAxios(err, { code: \"FETCH_BINANCE_EXCHANGE_INFO_FAILED\", baseURL: restUrl });\n    }\n\n    throw new SymmError(\n      \"api\",\n      \"FETCH_BINANCE_EXCHANGE_INFO_FAILED\",\n      `Failed to fetch Binance exchangeInfo: ${err instanceof Error ? err.message : String(err)}`,\n      { cause: err instanceof Error ? err : undefined },\n    );\n  }\n}\n"],"mappings":";;;;AAwCA,SAAgB,EAAoB,GAA0B;CAC5D,IAAM,IAAW,EAAS,QAAQ,GAAG;CAGrC,OAFI,MAAa,KAAW,IACX,EAAS,MAAM,IAAW,CAAC,EAAE,QAAQ,OAAO,EACtD,EAAS;AAClB;AAEA,SAAS,EAAa,GAAwD;CAC5E,IAAM,IAAc,EAAM,SAAS,MAAM,MAAW,EAAO,eAAe,cAAc,GAClF,IAAe,GAAa,WAAW,EAAoB,EAAY,QAAQ,IAAI,KAAA;CAEzF,OAAO;EACL,QAAQ,EAAM;EACd,WAAW,EAAM;EACjB,YAAY,EAAM;EAMlB,gBAAgB,KAAgB,EAAM,kBAAkB;CAC1D;AACF;AAeA,eAAsB,EACpB,GACA,GACA,GACyC;CACzC,IAAM,IAAM,GAAG,IAAU,EAA2B;CAEpD,IAAI;EAEF,IAAM,KAAU,MADO,EAAM,IAAkD,GAAK,EAAE,UAAO,CAAC,GACrE,MAAM;EAE/B,IAAI,CAAC,MAAM,QAAQ,CAAO,GACxB,MAAM,IAAI,EACR,OACA,sCACA,uDACF;EAGF,OAAO,IAAI,IAAI,EAAQ,KAAK,MAAU,CAAC,EAAM,OAAO,YAAY,GAAG,EAAa,CAAK,CAAC,CAAC,CAAC;CAC1F,SAAS,GAAK;EAOZ,MANI,aAAe,IAAiB,IAEhC,EAAa,CAAG,IACZ,EAAa,UAAU,GAAK;GAAE,MAAM;GAAsC,SAAS;EAAQ,CAAC,IAG9F,IAAI,EACR,OACA,sCACA,yCAAyC,aAAe,QAAQ,EAAI,UAAU,OAAO,CAAG,KACxF,EAAE,OAAO,aAAe,QAAQ,IAAM,KAAA,EAAU,CAClD;CACF;AACF"}

package/dist/candles/sources/binance/fetch-binance-klines.d.ts

@@ -0,0 +1,36 @@
+import { Candle } from '../../types.js';
+import { BinanceMarket } from './constants.js';
+/**
+ * Parameters for {@link fetchBinanceKlines}.
+ */
+export interface FetchBinanceKlinesParameters {
+    /** REST host, without a trailing slash. */
+    restUrl: string;
+    /** Which Binance market to read. */
+    market: BinanceMarket;
+    /** Binance symbol, upper-case (e.g. `"BTCUSDT"`). */
+    symbol: string;
+    /** Binance interval string (e.g. `"1m"`). */
+    interval: string;
+    /** Earliest bar open time to return, unix ms, inclusive. */
+    startTime?: number;
+    /** Latest bar open time to return, unix ms, inclusive on Binance's side. */
+    endTime?: number;
+    /** Bars to request. Must already be capped to the market's maximum. */
+    limit: number;
+    /** Aborts the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Issue one Binance klines request and normalize the response.
+ *
+ * A single request only — {@link createBinanceCandleSource} layers paging on
+ * top. Bars come back in ascending time order and that order is preserved.
+ *
+ * @param parameters - Endpoint, symbol, interval, and range.
+ * @returns The bars Binance returned, ascending by time.
+ * @throws {SymmApiError} when the request fails with an HTTP response.
+ * @throws {SymmError} when the response is not an array of klines.
+ */
+export declare function fetchBinanceKlines(parameters: FetchBinanceKlinesParameters): Promise<Candle[]>;
+//# sourceMappingURL=fetch-binance-klines.d.ts.map

package/dist/candles/sources/binance/fetch-binance-klines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-klines.d.ts","sourceRoot":"","sources":["../../../../src/candles/sources/binance/fetch-binance-klines.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGtE;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,4BAA4B,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiCpG"}

package/dist/candles/sources/binance/fetch-binance-klines.js

@@ -0,0 +1,31 @@
+import { SymmApiError as e, SymmError as t } from "../../../shared/errors/symm-error.js";
+import { BINANCE_KLINES_PATH as n } from "./constants.js";
+import { parseBinanceKline as r } from "./parse-kline.js";
+import i, { isAxiosError as a } from "axios";
+//#region src/candles/sources/binance/fetch-binance-klines.ts
+async function o(o) {
+	let { restUrl: s, market: c, symbol: l, interval: u, startTime: d, endTime: f, limit: p, signal: m } = o, h = `${s}${n[c]}`;
+	try {
+		let e = await i.get(h, {
+			params: {
+				symbol: l,
+				interval: u,
+				startTime: d,
+				endTime: f,
+				limit: p
+			},
+			signal: m
+		});
+		if (!Array.isArray(e.data)) throw new t("api", "FETCH_BINANCE_KLINES_FAILED", `Binance klines response was not an array for ${l} ${u}.`);
+		return e.data.map(r);
+	} catch (n) {
+		throw n instanceof t ? n : a(n) ? e.fromAxios(n, {
+			code: "FETCH_BINANCE_KLINES_FAILED",
+			baseURL: s
+		}) : new t("api", "FETCH_BINANCE_KLINES_FAILED", `Failed to fetch Binance klines for ${l} ${u}: ${n instanceof Error ? n.message : String(n)}`, { cause: n instanceof Error ? n : void 0 });
+	}
+}
+//#endregion
+export { o as fetchBinanceKlines };
+
+//# sourceMappingURL=fetch-binance-klines.js.map

package/dist/candles/sources/binance/fetch-binance-klines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-klines.js","names":[],"sources":["../../../../src/candles/sources/binance/fetch-binance-klines.ts"],"sourcesContent":["import axios, { isAxiosError } from \"axios\";\nimport { SymmApiError, SymmError } from \"../../../shared/errors/symm-error\";\nimport type { Candle } from \"../../types\";\nimport { BINANCE_KLINES_PATH, type BinanceMarket } from \"./constants\";\nimport { parseBinanceKline, type RawBinanceKline } from \"./parse-kline\";\n\n/**\n * Parameters for {@link fetchBinanceKlines}.\n */\nexport interface FetchBinanceKlinesParameters {\n  /** REST host, without a trailing slash. */\n  restUrl: string;\n  /** Which Binance market to read. */\n  market: BinanceMarket;\n  /** Binance symbol, upper-case (e.g. `\"BTCUSDT\"`). */\n  symbol: string;\n  /** Binance interval string (e.g. `\"1m\"`). */\n  interval: string;\n  /** Earliest bar open time to return, unix ms, inclusive. */\n  startTime?: number;\n  /** Latest bar open time to return, unix ms, inclusive on Binance's side. */\n  endTime?: number;\n  /** Bars to request. Must already be capped to the market's maximum. */\n  limit: number;\n  /** Aborts the request. */\n  signal?: AbortSignal;\n}\n\n/**\n * Issue one Binance klines request and normalize the response.\n *\n * A single request only — {@link createBinanceCandleSource} layers paging on\n * top. Bars come back in ascending time order and that order is preserved.\n *\n * @param parameters - Endpoint, symbol, interval, and range.\n * @returns The bars Binance returned, ascending by time.\n * @throws {SymmApiError} when the request fails with an HTTP response.\n * @throws {SymmError} when the response is not an array of klines.\n */\nexport async function fetchBinanceKlines(parameters: FetchBinanceKlinesParameters): Promise<Candle[]> {\n  const { restUrl, market, symbol, interval, startTime, endTime, limit, signal } = parameters;\n  const url = `${restUrl}${BINANCE_KLINES_PATH[market]}`;\n\n  try {\n    const response = await axios.get<RawBinanceKline[]>(url, {\n      params: { symbol, interval, startTime, endTime, limit },\n      signal,\n    });\n\n    if (!Array.isArray(response.data)) {\n      throw new SymmError(\n        \"api\",\n        \"FETCH_BINANCE_KLINES_FAILED\",\n        `Binance klines response was not an array for ${symbol} ${interval}.`,\n      );\n    }\n\n    return response.data.map(parseBinanceKline);\n  } catch (err) {\n    if (err instanceof SymmError) throw err;\n\n    if (isAxiosError(err)) {\n      throw SymmApiError.fromAxios(err, { code: \"FETCH_BINANCE_KLINES_FAILED\", baseURL: restUrl });\n    }\n\n    throw new SymmError(\n      \"api\",\n      \"FETCH_BINANCE_KLINES_FAILED\",\n      `Failed to fetch Binance klines for ${symbol} ${interval}: ${err instanceof Error ? err.message : String(err)}`,\n      { cause: err instanceof Error ? err : undefined },\n    );\n  }\n}\n"],"mappings":";;;;;AAuCA,eAAsB,EAAmB,GAA6D;CACpG,IAAM,EAAE,YAAS,WAAQ,WAAQ,aAAU,cAAW,YAAS,UAAO,cAAW,GAC3E,IAAM,GAAG,IAAU,EAAoB;CAE7C,IAAI;EACF,IAAM,IAAW,MAAM,EAAM,IAAuB,GAAK;GACvD,QAAQ;IAAE;IAAQ;IAAU;IAAW;IAAS;GAAM;GACtD;EACF,CAAC;EAED,IAAI,CAAC,MAAM,QAAQ,EAAS,IAAI,GAC9B,MAAM,IAAI,EACR,OACA,+BACA,gDAAgD,EAAO,GAAG,EAAS,EACrE;EAGF,OAAO,EAAS,KAAK,IAAI,CAAiB;CAC5C,SAAS,GAAK;EAOZ,MANI,aAAe,IAAiB,IAEhC,EAAa,CAAG,IACZ,EAAa,UAAU,GAAK;GAAE,MAAM;GAA+B,SAAS;EAAQ,CAAC,IAGvF,IAAI,EACR,OACA,+BACA,sCAAsC,EAAO,GAAG,EAAS,IAAI,aAAe,QAAQ,EAAI,UAAU,OAAO,CAAG,KAC5G,EAAE,OAAO,aAAe,QAAQ,IAAM,KAAA,EAAU,CAClD;CACF;AACF"}

package/dist/candles/sources/binance/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './create-binance-candle-source.js';
+export * from './fetch-binance-exchange-info.js';
+export * from './fetch-binance-klines.js';
+export * from './map-resolution.js';
+export * from './parse-kline.js';
+export * from './watch-binance-klines.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/candles/sources/binance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/candles/sources/binance/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC"}

package/dist/candles/sources/binance/map-resolution.d.ts

@@ -0,0 +1,25 @@
+import { CandleResolution } from '../../types.js';
+import { BinanceMarket } from './constants.js';
+/**
+ * Translate an SDK resolution into a Binance `interval` string.
+ *
+ * @param market - Which Binance market the interval is for.
+ * @param resolution - The SDK resolution to translate.
+ * @returns The Binance interval, or `undefined` when that market has no
+ *   equivalent bucket.
+ *
+ * @example
+ * ```ts
+ * toBinanceInterval("usd-m-futures", "4h"); // "4h"
+ * toBinanceInterval("usd-m-futures", "1s"); // undefined — futures has no 1s klines
+ * ```
+ */
+export declare function toBinanceInterval(market: BinanceMarket, resolution: CandleResolution): string | undefined;
+/**
+ * List the resolutions a Binance market can serve, in ascending bar size.
+ *
+ * @param market - Which Binance market to describe.
+ * @returns The supported resolutions, suitable for `CandleSource.supportedResolutions`.
+ */
+export declare function getBinanceSupportedResolutions(market: BinanceMarket): readonly CandleResolution[];
+//# sourceMappingURL=map-resolution.d.ts.map

package/dist/candles/sources/binance/map-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-resolution.d.ts","sourceRoot":"","sources":["../../../../src/candles/sources/binance/map-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyCjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAEzG;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,gBAAgB,EAAE,CAEjG"}

package/dist/candles/sources/binance/map-resolution.js

@@ -0,0 +1,34 @@
+//#region src/candles/sources/binance/map-resolution.ts
+var e = {
+	"1m": "1m",
+	"3m": "3m",
+	"5m": "5m",
+	"15m": "15m",
+	"30m": "30m",
+	"1h": "1h",
+	"2h": "2h",
+	"4h": "4h",
+	"6h": "6h",
+	"8h": "8h",
+	"12h": "12h",
+	"1d": "1d",
+	"3d": "3d",
+	"1w": "1w",
+	"1M": "1M"
+}, t = {
+	"usd-m-futures": e,
+	spot: {
+		"1s": "1s",
+		...e
+	}
+};
+function n(e, n) {
+	return t[e][n];
+}
+function r(e) {
+	return Object.keys(t[e]);
+}
+//#endregion
+export { r as getBinanceSupportedResolutions, n as toBinanceInterval };
+
+//# sourceMappingURL=map-resolution.js.map

package/dist/candles/sources/binance/map-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-resolution.js","names":[],"sources":["../../../../src/candles/sources/binance/map-resolution.ts"],"sourcesContent":["import type { CandleResolution } from \"../../types\";\nimport type { BinanceMarket } from \"./constants\";\n\n/**\n * Resolutions both Binance markets serve, mapped to their `interval` strings.\n *\n * The codes happen to be identical to the SDK's own vocabulary for this range,\n * but the mapping is written out rather than assumed — the SDK's resolution set\n * is its own contract, and a venue that names things differently plugs in the\n * same way.\n */\nconst SHARED_INTERVALS: Partial<Record<CandleResolution, string>> = {\n  \"1m\": \"1m\",\n  \"3m\": \"3m\",\n  \"5m\": \"5m\",\n  \"15m\": \"15m\",\n  \"30m\": \"30m\",\n  \"1h\": \"1h\",\n  \"2h\": \"2h\",\n  \"4h\": \"4h\",\n  \"6h\": \"6h\",\n  \"8h\": \"8h\",\n  \"12h\": \"12h\",\n  \"1d\": \"1d\",\n  \"3d\": \"3d\",\n  \"1w\": \"1w\",\n  \"1M\": \"1M\",\n};\n\n/**\n * Per-market interval tables.\n *\n * Spot additionally serves `1s` klines. USD-M futures does not, and neither\n * market has any equivalent of the SDK's `10s` bucket — a source that needs\n * sub-minute bars for a perp has to build them by folding a tick stream, which\n * is a different source entirely.\n */\nconst INTERVALS: Record<BinanceMarket, Partial<Record<CandleResolution, string>>> = {\n  \"usd-m-futures\": SHARED_INTERVALS,\n  spot: { \"1s\": \"1s\", ...SHARED_INTERVALS },\n};\n\n/**\n * Translate an SDK resolution into a Binance `interval` string.\n *\n * @param market - Which Binance market the interval is for.\n * @param resolution - The SDK resolution to translate.\n * @returns The Binance interval, or `undefined` when that market has no\n *   equivalent bucket.\n *\n * @example\n * ```ts\n * toBinanceInterval(\"usd-m-futures\", \"4h\"); // \"4h\"\n * toBinanceInterval(\"usd-m-futures\", \"1s\"); // undefined — futures has no 1s klines\n * ```\n */\nexport function toBinanceInterval(market: BinanceMarket, resolution: CandleResolution): string | undefined {\n  return INTERVALS[market][resolution];\n}\n\n/**\n * List the resolutions a Binance market can serve, in ascending bar size.\n *\n * @param market - Which Binance market to describe.\n * @returns The supported resolutions, suitable for `CandleSource.supportedResolutions`.\n */\nexport function getBinanceSupportedResolutions(market: BinanceMarket): readonly CandleResolution[] {\n  return Object.keys(INTERVALS[market]) as CandleResolution[];\n}\n"],"mappings":";AAWA,IAAM,IAA8D;CAClE,MAAM;CACN,MAAM;CACN,MAAM;CACN,OAAO;CACP,OAAO;CACP,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,OAAO;CACP,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;AACR,GAUM,IAA8E;CAClF,iBAAiB;CACjB,MAAM;EAAE,MAAM;EAAM,GAAG;CAAiB;AAC1C;AAgBA,SAAgB,EAAkB,GAAuB,GAAkD;CACzG,OAAO,EAAU,GAAQ;AAC3B;AAQA,SAAgB,EAA+B,GAAoD;CACjG,OAAO,OAAO,KAAK,EAAU,EAAO;AACtC"}

package/dist/candles/sources/binance/parse-kline.d.ts

@@ -0,0 +1,61 @@
+import { Candle } from '../../types.js';
+/**
+ * A kline as Binance returns it: a positional tuple, not an object.
+ *
+ * Slots 6-11 (close time, quote volume, trade count, taker volumes, and an
+ * unused field) are present on the wire but carry nothing a chart needs, so
+ * they are typed loosely and ignored.
+ */
+export type RawBinanceKline = [
+    openTime: number,
+    open: string,
+    high: string,
+    low: string,
+    close: string,
+    volume: string,
+    ...rest: unknown[]
+];
+/**
+ * The `k` payload of a Binance kline WebSocket event.
+ */
+export interface RawBinanceKlineEvent {
+    /** Bar open time, unix ms. */
+    t: number;
+    /** Interval string this bar belongs to (e.g. `"1m"`). */
+    i: string;
+    /** Open price. */
+    o: string;
+    /** High price. */
+    h: string;
+    /** Low price. */
+    l: string;
+    /** Close price — the latest price while the bar is still forming. */
+    c: string;
+    /** Base-asset volume. */
+    v: string;
+    /** `true` once the bar has closed and the next event starts a new one. */
+    x: boolean;
+}
+/**
+ * Convert a Binance REST kline tuple into a {@link Candle}.
+ *
+ * @param kline - One entry from a `/klines` response.
+ * @returns The normalized bar.
+ * @throws {SymmError} when the tuple is malformed or carries non-numeric prices.
+ *
+ * @example
+ * ```ts
+ * parseBinanceKline([1700000000000, "42000.1", "42100", "41950", "42050", "12.5"]);
+ * // → { time: 1700000000000, open: 42000.1, high: 42100, low: 41950, close: 42050, volume: 12.5 }
+ * ```
+ */
+export declare function parseBinanceKline(kline: RawBinanceKline): Candle;
+/**
+ * Convert the `k` payload of a Binance kline WebSocket event into a {@link Candle}.
+ *
+ * @param event - The `k` object from a `kline` stream frame.
+ * @returns The normalized bar.
+ * @throws {SymmError} when the payload carries non-numeric prices.
+ */
+export declare function parseBinanceKlineEvent(event: RawBinanceKlineEvent): Candle;
+//# sourceMappingURL=parse-kline.d.ts.map

package/dist/candles/sources/binance/parse-kline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-kline.d.ts","sourceRoot":"","sources":["../../../../src/candles/sources/binance/parse-kline.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM;IAChB,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,MAAM;IACX,KAAK,EAAE,MAAM;IACb,MAAM,EAAE,MAAM;IACd,GAAG,IAAI,EAAE,OAAO,EAAE;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,CAAC,EAAE,MAAM,CAAC;IACV,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAC;IACV,kBAAkB;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,kBAAkB;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAC;IACV,qEAAqE;IACrE,CAAC,EAAE,MAAM,CAAC;IACV,yBAAyB;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,0EAA0E;IAC1E,CAAC,EAAE,OAAO,CAAC;CACZ;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAiBhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAS1E"}

package/dist/candles/sources/binance/parse-kline.js

@@ -0,0 +1,32 @@
+import { SymmError as e } from "../../../shared/errors/symm-error.js";
+//#region src/candles/sources/binance/parse-kline.ts
+function t(t, n) {
+	let r = Number(t);
+	if (!Number.isFinite(r)) throw new e("api", "INVALID_BINANCE_KLINE", `Binance kline has a non-numeric \`${n}\`: ${t}.`);
+	return r;
+}
+function n(n) {
+	if (!Array.isArray(n) || n.length < 6) throw new e("api", "INVALID_BINANCE_KLINE", `Binance kline is not a tuple of at least 6 fields: ${JSON.stringify(n)}.`);
+	return {
+		time: t(n[0], "openTime"),
+		open: t(n[1], "open"),
+		high: t(n[2], "high"),
+		low: t(n[3], "low"),
+		close: t(n[4], "close"),
+		volume: t(n[5], "volume")
+	};
+}
+function r(e) {
+	return {
+		time: t(e.t, "t"),
+		open: t(e.o, "o"),
+		high: t(e.h, "h"),
+		low: t(e.l, "l"),
+		close: t(e.c, "c"),
+		volume: t(e.v, "v")
+	};
+}
+//#endregion
+export { n as parseBinanceKline, r as parseBinanceKlineEvent };
+
+//# sourceMappingURL=parse-kline.js.map