@imbingox/acex 0.1.0-beta.0 → 0.1.0-beta.2

package/src/adapters/binance/adapter.ts

@@ -0,0 +1,53 @@
+import type { MarketDefinition } from "../../types/index.ts";
+import type {
+  L1BookStreamCallbacks,
+  L1BookStreamOptions,
+  MarketAdapter,
+  StreamHandle,
+} from "../types.ts";
+import { subscribeBinanceBookTicker } from "./book-ticker.ts";
+import {
+  type BinanceMarketDefinition,
+  loadBinanceMarkets,
+} from "./market-catalog.ts";
+
+export class BinanceMarketAdapter implements MarketAdapter {
+  readonly exchange = "binance" as const;
+
+  private readonly definitions = new Map<string, BinanceMarketDefinition>();
+
+  async loadMarkets(): Promise<MarketDefinition[]> {
+    const markets = await loadBinanceMarkets();
+    this.definitions.clear();
+
+    for (const market of markets) {
+      this.definitions.set(market.symbol, market);
+    }
+
+    return markets;
+  }
+
+  createL1BookStream(
+    market: MarketDefinition,
+    callbacks: L1BookStreamCallbacks,
+    options: L1BookStreamOptions,
+  ): StreamHandle {
+    const binanceMarket = this.definitions.get(market.symbol);
+    if (!binanceMarket) {
+      throw new Error(`Unknown Binance market: ${market.symbol}`);
+    }
+
+    return subscribeBinanceBookTicker(
+      binanceMarket,
+      {
+        onBookTicker(update) {
+          callbacks.onUpdate(update);
+        },
+        onFreshnessChange: callbacks.onFreshnessChange,
+        onDisconnected: callbacks.onDisconnected,
+        onError: callbacks.onError,
+      },
+      options,
+    );
+  }
+}

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/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"),
+    ),
+  ]);
+}

package/src/adapters/types.ts

@@ -0,0 +1,43 @@
+import type { Exchange, MarketDefinition } from "../types/index.ts";
+
+export interface StreamHandle {
+  readonly ready: Promise<void>;
+  close(): void;
+}
+
+export interface RawL1BookUpdate {
+  bidPrice: string;
+  bidSize: string;
+  askPrice: string;
+  askSize: string;
+  exchangeTs?: number;
+  receivedAt: number;
+}
+
+export interface L1BookStreamCallbacks {
+  onUpdate(update: RawL1BookUpdate): void;
+  onFreshnessChange(
+    freshness: "fresh" | "stale",
+    reason?: "heartbeat_timeout",
+  ): void;
+  onDisconnected(): void;
+  onError(error: Error): void;
+}
+
+export interface L1BookStreamOptions {
+  initialMessageTimeoutMs: number;
+  staleAfterMs: number;
+  reconnectDelayMs: number;
+  reconnectMaxDelayMs: number;
+  now?: () => number;
+}
+
+export interface MarketAdapter {
+  readonly exchange: Exchange;
+  loadMarkets(): Promise<MarketDefinition[]>;
+  createL1BookStream(
+    market: MarketDefinition,
+    callbacks: L1BookStreamCallbacks,
+    options: L1BookStreamOptions,
+  ): StreamHandle;
+}

package/src/client/context.ts

@@ -0,0 +1,60 @@
+import type {
+  AccountCredentials,
+  AcexInternalError,
+  Exchange,
+  HealthEvent,
+} from "../types/index.ts";
+
+export interface RegisteredAccountRecord {
+  accountId: string;
+  exchange: Exchange;
+  credentials?: AccountCredentials;
+  options?: Record<string, unknown>;
+}
+
+export interface ClientContext {
+  now(): number;
+  assertStarted(): void;
+  getRegisteredAccount(accountId: string): RegisteredAccountRecord;
+  ensurePrivateCredentials(accountId: string): void;
+  publishRuntimeError(
+    source: AcexInternalError["source"],
+    error: Error,
+    metadata?: Omit<AcexInternalError, "error" | "source" | "ts">,
+  ): void;
+  publishHealthEvent(event: HealthEvent): void;
+}
+
+export interface ManagerLifecycle {
+  onClientStarted(): void;
+  onClientStopping(now: number): void;
+}
+
+export interface AccountAwareManager {
+  onAccountRemoved(accountId: string, now: number): void;
+  onCredentialsUpdated(accountId: string, exchange: Exchange): void;
+}
+
+export interface HealthReporter<T> {
+  getStatuses(): T[];
+}
+
+export function hasPrivateCredentials(
+  credentials?: AccountCredentials,
+): boolean {
+  return Boolean(credentials?.apiKey && credentials.secret);
+}
+
+export function mergeCredentials(
+  current: AccountCredentials | undefined,
+  next: AccountCredentials,
+): AccountCredentials {
+  return {
+    ...current,
+    ...next,
+    extra: {
+      ...(current?.extra ?? {}),
+      ...(next.extra ?? {}),
+    },
+  };
+}

package/src/client/create-client.ts

@@ -0,0 +1,6 @@
+import type { AcexClient, CreateClientOptions } from "../types/index.ts";
+import { AcexClientImpl } from "./runtime.ts";
+
+export function createClient(options?: CreateClientOptions): AcexClient {
+  return new AcexClientImpl(options);
+}