@imbingox/acex 0.1.0 → 0.3.0-beta.0

package/src/adapters/binance/book-ticker.ts

@@ -0,0 +1,123 @@
+import { createManagedWebSocket } from "../../internal/managed-websocket.ts";
+import type { BinanceMarketDefinition } from "./market-catalog.ts";
+
+export interface BinanceL1BookUpdate {
+  bidPrice: string;
+  bidSize: string;
+  askPrice: string;
+  askSize: string;
+  exchangeTs?: number;
+  receivedAt: number;
+}
+
+export interface BinanceBookTickerSubscription {
+  readonly ready: Promise<void>;
+  close(): void;
+}
+
+export interface BinanceBookTickerCallbacks {
+  onBookTicker(update: BinanceL1BookUpdate): void;
+  onFreshnessChange(
+    freshness: "fresh" | "stale",
+    reason?: "heartbeat_timeout",
+  ): void;
+  onDisconnected(): void;
+  onError?(error: Error): void;
+}
+
+export interface BinanceBookTickerOptions {
+  initialMessageTimeoutMs: number;
+  staleAfterMs: number;
+  reconnectDelayMs: number;
+  reconnectMaxDelayMs: number;
+  now?: () => number;
+}
+
+interface BinanceBookTickerMessage {
+  b?: string;
+  B?: string;
+  a?: string;
+  A?: string;
+  T?: number;
+}
+
+const BINANCE_SPOT_WS_BASE_URL = "wss://stream.binance.com:9443/ws";
+const BINANCE_USDM_WS_BASE_URL = "wss://fstream.binance.com/ws";
+const BINANCE_COINM_WS_BASE_URL = "wss://dstream.binance.com/ws";
+
+function getWsBaseUrl(market: BinanceMarketDefinition): string {
+  switch (market.family) {
+    case "spot":
+      return BINANCE_SPOT_WS_BASE_URL;
+    case "usdm":
+      return BINANCE_USDM_WS_BASE_URL;
+    case "coinm":
+      return BINANCE_COINM_WS_BASE_URL;
+  }
+}
+
+function buildBookTickerUrl(market: BinanceMarketDefinition): string {
+  return `${getWsBaseUrl(market)}/${market.id.toLowerCase()}@bookTicker`;
+}
+
+function parseBookTickerMessage(
+  data: string,
+): BinanceBookTickerMessage | undefined {
+  const parsed = JSON.parse(data) as BinanceBookTickerMessage;
+  if (!parsed.b || !parsed.B || !parsed.a || !parsed.A) {
+    return undefined;
+  }
+
+  return parsed;
+}
+
+export function subscribeBinanceBookTicker(
+  market: BinanceMarketDefinition,
+  callbacks: BinanceBookTickerCallbacks,
+  options: BinanceBookTickerOptions,
+): BinanceBookTickerSubscription {
+  const session = createManagedWebSocket<BinanceBookTickerMessage>({
+    url: buildBookTickerUrl(market),
+    initialMessageTimeoutMs: options.initialMessageTimeoutMs,
+    now: options.now,
+    messageWatchdog: {
+      staleAfterMs: options.staleAfterMs,
+      onStale() {
+        callbacks.onFreshnessChange("stale", "heartbeat_timeout");
+      },
+    },
+    reconnect: {
+      initialDelayMs: options.reconnectDelayMs,
+      maxDelayMs: options.reconnectMaxDelayMs,
+    },
+    parseMessage: parseBookTickerMessage,
+    onMessage(message, receivedAt) {
+      if (!message.b || !message.B || !message.a || !message.A) {
+        return;
+      }
+
+      callbacks.onBookTicker({
+        bidPrice: message.b,
+        bidSize: message.B,
+        askPrice: message.a,
+        askSize: message.A,
+        exchangeTs: message.T,
+        receivedAt,
+      });
+      callbacks.onFreshnessChange("fresh");
+    },
+    onUnexpectedClose() {
+      callbacks.onDisconnected();
+    },
+    onError() {
+      callbacks.onError?.(new Error(`WebSocket error for ${market.symbol}`));
+    },
+  });
+
+  return {
+    ready: session.ready,
+    close() {
+      session.close();
+    },
+  };
+}

package/src/adapters/binance/mark-price.ts

@@ -0,0 +1,126 @@
+import { createManagedWebSocket } from "../../internal/managed-websocket.ts";
+import type { BinanceMarketDefinition } from "./market-catalog.ts";
+
+export interface BinanceFundingRateUpdate {
+  fundingRate: string;
+  nextFundingTime?: number;
+  markPrice?: string;
+  indexPrice?: string;
+  exchangeTs?: number;
+  receivedAt: number;
+}
+
+export interface BinanceMarkPriceSubscription {
+  readonly ready: Promise<void>;
+  close(): void;
+}
+
+export interface BinanceMarkPriceCallbacks {
+  onFundingRate(update: BinanceFundingRateUpdate): void;
+  onFreshnessChange(
+    freshness: "fresh" | "stale",
+    reason?: "heartbeat_timeout",
+  ): void;
+  onDisconnected(): void;
+  onError?(error: Error): void;
+}
+
+export interface BinanceMarkPriceOptions {
+  initialMessageTimeoutMs: number;
+  staleAfterMs: number;
+  reconnectDelayMs: number;
+  reconnectMaxDelayMs: number;
+  now?: () => number;
+}
+
+interface BinanceMarkPriceMessage {
+  e?: string;
+  E?: number;
+  s?: string;
+  p?: string;
+  i?: string;
+  r?: string;
+  T?: number;
+}
+
+const BINANCE_USDM_MARKET_WS_BASE_URL = "wss://fstream.binance.com/market/ws";
+const BINANCE_COINM_WS_BASE_URL = "wss://dstream.binance.com/ws";
+
+function getWsBaseUrl(market: BinanceMarketDefinition): string {
+  switch (market.family) {
+    case "usdm":
+      return BINANCE_USDM_MARKET_WS_BASE_URL;
+    case "coinm":
+      return BINANCE_COINM_WS_BASE_URL;
+    case "spot":
+      throw new Error(
+        `Funding rate is not supported for spot market: ${market.symbol}`,
+      );
+  }
+}
+
+function buildMarkPriceUrl(market: BinanceMarketDefinition): string {
+  return `${getWsBaseUrl(market)}/${market.id.toLowerCase()}@markPrice`;
+}
+
+function parseMarkPriceMessage(
+  data: string,
+): BinanceMarkPriceMessage | undefined {
+  const parsed = JSON.parse(data) as BinanceMarkPriceMessage;
+  if (!parsed.r) {
+    return undefined;
+  }
+
+  return parsed;
+}
+
+export function subscribeBinanceMarkPrice(
+  market: BinanceMarketDefinition,
+  callbacks: BinanceMarkPriceCallbacks,
+  options: BinanceMarkPriceOptions,
+): BinanceMarkPriceSubscription {
+  const session = createManagedWebSocket<BinanceMarkPriceMessage>({
+    url: buildMarkPriceUrl(market),
+    initialMessageTimeoutMs: options.initialMessageTimeoutMs,
+    now: options.now,
+    messageWatchdog: {
+      staleAfterMs: options.staleAfterMs,
+      onStale() {
+        callbacks.onFreshnessChange("stale", "heartbeat_timeout");
+      },
+    },
+    reconnect: {
+      initialDelayMs: options.reconnectDelayMs,
+      maxDelayMs: options.reconnectMaxDelayMs,
+    },
+    parseMessage: parseMarkPriceMessage,
+    onMessage(message, receivedAt) {
+      if (!message.r) {
+        return;
+      }
+
+      callbacks.onFundingRate({
+        fundingRate: message.r,
+        nextFundingTime: message.T,
+        markPrice: message.p,
+        indexPrice: message.i,
+        exchangeTs: message.E,
+        receivedAt,
+      });
+      callbacks.onFreshnessChange("fresh");
+    },
+    onUnexpectedClose() {
+      callbacks.onDisconnected();
+    },
+    onError() {
+      callbacks.onError?.(new Error(`WebSocket error for ${market.symbol}`));
+    },
+  });
+
+  return {
+    ready: session.ready,
+    close() {
+      session.close();
+    },
+  };
+}

package/src/adapters/binance/market-catalog.ts

@@ -0,0 +1,258 @@
+import BigNumber from "bignumber.js";
+import type { MarketDefinition, MarketType } from "../../types/index.ts";
+
+type FetchLike = typeof fetch;
+
+export type BinanceMarketFamily = "spot" | "usdm" | "coinm";
+
+export interface BinanceMarketDefinition extends MarketDefinition {
+  family: BinanceMarketFamily;
+}
+
+interface BinanceSymbolFilter {
+  filterType?: string;
+  tickSize?: string;
+  stepSize?: string;
+  minQty?: string;
+  minNotional?: string;
+  notional?: string;
+}
+
+interface BinanceSpotSymbolInfo {
+  symbol: string;
+  status: string;
+  baseAsset: string;
+  quoteAsset: string;
+  filters?: BinanceSymbolFilter[];
+}
+
+interface BinanceSpotExchangeInfo {
+  symbols?: BinanceSpotSymbolInfo[];
+}
+
+interface BinanceDerivativesSymbolInfo {
+  symbol: string;
+  status: string;
+  contractType?: string;
+  deliveryDate?: number;
+  baseAsset: string;
+  quoteAsset: string;
+  marginAsset?: string;
+  pricePrecision?: number;
+  quantityPrecision?: number;
+  contractSize?: number | string;
+  filters?: BinanceSymbolFilter[];
+}
+
+interface BinanceDerivativesExchangeInfo {
+  symbols?: BinanceDerivativesSymbolInfo[];
+}
+
+const BINANCE_SPOT_EXCHANGE_INFO_URL =
+  "https://api.binance.com/api/v3/exchangeInfo";
+const BINANCE_USDM_EXCHANGE_INFO_URL =
+  "https://fapi.binance.com/fapi/v1/exchangeInfo";
+const BINANCE_COINM_EXCHANGE_INFO_URL =
+  "https://dapi.binance.com/dapi/v1/exchangeInfo";
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function getFilter(
+  filters: BinanceSymbolFilter[] | undefined,
+  filterType: string,
+): BinanceSymbolFilter | undefined {
+  return filters?.find((filter) => filter.filterType === filterType);
+}
+
+function normalizeStep(step: string | undefined, fallback = "1"): string {
+  return step && step.length > 0 ? step : fallback;
+}
+
+function precisionFromStep(step: string): number {
+  const normalized = step.replace(/0+$/, "");
+  const dotIndex = normalized.indexOf(".");
+  if (dotIndex === -1) {
+    return 0;
+  }
+
+  return normalized.length - dotIndex - 1;
+}
+
+function formatExpiry(expiry: number): string {
+  const date = new Date(expiry);
+  const year = date.getUTCFullYear();
+  const month = `${date.getUTCMonth() + 1}`.padStart(2, "0");
+  const day = `${date.getUTCDate()}`.padStart(2, "0");
+  return `${year}${month}${day}`;
+}
+
+function inferContractType(
+  contractType: string | undefined,
+  deliveryDate: number | undefined,
+): MarketType {
+  if (contractType === "PERPETUAL") {
+    return "swap";
+  }
+
+  if (deliveryDate && Number.isFinite(deliveryDate) && deliveryDate > 0) {
+    return "future";
+  }
+
+  return "swap";
+}
+
+function buildFuturesSymbol(
+  base: string,
+  quote: string,
+  settle: string,
+  type: MarketType,
+  expiry: number | undefined,
+): string {
+  const prefix = `${base}/${quote}:${settle}`;
+  if (type !== "future" || !expiry) {
+    return prefix;
+  }
+
+  return `${prefix}-${formatExpiry(expiry)}`;
+}
+
+function normalizeSpotSymbol(
+  symbol: BinanceSpotSymbolInfo,
+): BinanceMarketDefinition {
+  const priceFilter = getFilter(symbol.filters, "PRICE_FILTER");
+  const lotSizeFilter = getFilter(symbol.filters, "LOT_SIZE");
+  const notionalFilter =
+    getFilter(symbol.filters, "NOTIONAL") ??
+    getFilter(symbol.filters, "MIN_NOTIONAL");
+  const priceStep = normalizeStep(priceFilter?.tickSize);
+  const amountStep = normalizeStep(lotSizeFilter?.stepSize);
+  const notionalValue = notionalFilter?.minNotional ?? notionalFilter?.notional;
+
+  return {
+    exchange: "binance",
+    family: "spot",
+    symbol: `${symbol.baseAsset}/${symbol.quoteAsset}`,
+    id: symbol.symbol,
+    type: "spot",
+    base: symbol.baseAsset,
+    quote: symbol.quoteAsset,
+    active: symbol.status === "TRADING",
+    contract: false,
+    pricePrecision: precisionFromStep(priceStep),
+    amountPrecision: precisionFromStep(amountStep),
+    priceStep: new BigNumber(priceStep),
+    amountStep: new BigNumber(amountStep),
+    minAmount: lotSizeFilter?.minQty
+      ? new BigNumber(lotSizeFilter.minQty)
+      : undefined,
+    minNotional: notionalValue ? new BigNumber(notionalValue) : undefined,
+    raw: toRecord(symbol),
+  };
+}
+
+function normalizeDerivativesSymbol(
+  symbol: BinanceDerivativesSymbolInfo,
+  family: BinanceMarketFamily,
+): BinanceMarketDefinition {
+  const priceFilter = getFilter(symbol.filters, "PRICE_FILTER");
+  const lotSizeFilter = getFilter(symbol.filters, "LOT_SIZE");
+  const notionalFilter =
+    getFilter(symbol.filters, "NOTIONAL") ??
+    getFilter(symbol.filters, "MIN_NOTIONAL");
+  const priceStep = normalizeStep(priceFilter?.tickSize);
+  const amountStep = normalizeStep(lotSizeFilter?.stepSize);
+  const type = inferContractType(symbol.contractType, symbol.deliveryDate);
+  const settle =
+    symbol.marginAsset ??
+    (family === "usdm" ? symbol.quoteAsset : symbol.baseAsset);
+  const contractSize =
+    symbol.contractSize !== undefined
+      ? `${symbol.contractSize}`
+      : family === "usdm"
+        ? "1"
+        : undefined;
+  const notionalValue = notionalFilter?.minNotional ?? notionalFilter?.notional;
+
+  return {
+    exchange: "binance",
+    family,
+    symbol: buildFuturesSymbol(
+      symbol.baseAsset,
+      symbol.quoteAsset,
+      settle,
+      type,
+      type === "future" ? symbol.deliveryDate : undefined,
+    ),
+    id: symbol.symbol,
+    type,
+    base: symbol.baseAsset,
+    quote: symbol.quoteAsset,
+    settle,
+    active: symbol.status === "TRADING",
+    contract: true,
+    linear: family === "usdm",
+    inverse: family === "coinm",
+    contractSize: contractSize ? new BigNumber(contractSize) : undefined,
+    pricePrecision: precisionFromStep(priceStep),
+    amountPrecision: precisionFromStep(amountStep),
+    priceStep: new BigNumber(priceStep),
+    amountStep: new BigNumber(amountStep),
+    minAmount: lotSizeFilter?.minQty
+      ? new BigNumber(lotSizeFilter.minQty)
+      : undefined,
+    minNotional: notionalValue ? new BigNumber(notionalValue) : undefined,
+    expiry: type === "future" ? symbol.deliveryDate : undefined,
+    raw: toRecord(symbol),
+  };
+}
+
+async function fetchJson<T>(fetchFn: FetchLike, url: string): Promise<T> {
+  const response = await fetchFn(url);
+  if (!response.ok) {
+    throw new Error(
+      `Binance request failed: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return (await response.json()) as T;
+}
+
+function sortMarkets(
+  markets: BinanceMarketDefinition[],
+): BinanceMarketDefinition[] {
+  return [...markets].sort((left, right) =>
+    left.symbol.localeCompare(right.symbol),
+  );
+}
+
+export async function loadBinanceMarkets(
+  fetchFn: FetchLike = fetch,
+): Promise<BinanceMarketDefinition[]> {
+  const [spot, usdm, coinm] = await Promise.all([
+    fetchJson<BinanceSpotExchangeInfo>(fetchFn, BINANCE_SPOT_EXCHANGE_INFO_URL),
+    fetchJson<BinanceDerivativesExchangeInfo>(
+      fetchFn,
+      BINANCE_USDM_EXCHANGE_INFO_URL,
+    ),
+    fetchJson<BinanceDerivativesExchangeInfo>(
+      fetchFn,
+      BINANCE_COINM_EXCHANGE_INFO_URL,
+    ),
+  ]);
+
+  return sortMarkets([
+    ...(spot.symbols ?? []).map(normalizeSpotSymbol),
+    ...(usdm.symbols ?? []).map((symbol) =>
+      normalizeDerivativesSymbol(symbol, "usdm"),
+    ),
+    ...(coinm.symbols ?? []).map((symbol) =>
+      normalizeDerivativesSymbol(symbol, "coinm"),
+    ),
+  ]);
+}