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

package/README.md

@@ -1,65 +1,23 @@
-# acex
+# @imbingox/acex
 
-Bun-only trading SDK. Current official verification target: `binance`.
-
-## Current Direction
-
-- Official release verification now focuses on the Binance USD-M testnet path.
-- `aster` remains in the repo as an exploration sample (via CCXT / CCXT Pro) but is not part of the current official support commitment.
-- The Aster branch was kept to preserve the generic runtime and adapter validation work without blocking the Binance verification focus.
-
-## Verification Direction
-
-The current official verification path is Binance USD-M testnet. The current validation target scope consists of:
-
-- market WebSocket connectivity
-- private WebSocket connectivity
-- baseline bootstrap for runtime readiness
-- market `placeOrder`
-- reduce-only market `placeOrder`
-
-Run the verification script via:
+To install dependencies:
 
 ```bash
-bun run scripts/verify-binance-usdm-testnet.ts
+bun install
 ```
 
-The current script exercises bootstrap, subscription setup, and a real demo market open / reduce-only market close round-trip.
-
-The script expects the following environment variables for Binance USD-M testnet:
-
-- `BINANCE_USDM_API_KEY`
-- `BINANCE_USDM_API_SECRET`
-- `BINANCE_USDM_SYMBOL`
-- `BINANCE_USDM_ORDER_SIZE`
-- `BINANCE_USDM_ORDER_PRICE`
+To run checks:
 
-`BINANCE_USDM_ORDER_PRICE` is currently kept as a reference configuration field for notional planning and result logging; the verification orders themselves are submitted as market orders.
-
-## Verified Scope
-
-- Verified exchange: `binance`
-- Verified product: `USD-M`
-- Verified environment: `demo trading / testnet-style`
-- Verified date: `2026-03-31`
-- Verified runtime paths: `subscribeL1Book`, `fetchAccountBaseline`, `fetchOpenOrdersBaseline`, market `placeOrder`, reduce-only market `placeOrder`
-- Verified transports with direct evidence: `public WS (bookTicker)`, `private WS (runtime-level order confirmation + balance confirmation)`, `REST baseline`
-- Supplementary low-level evidence: direct `ccxt.pro.binanceusdm.watchOrders()` and `watchBalance()` both returned during the real demo open/close verification flow on `2026-03-31`
-- Deferred coverage: `amendOrder`, `cancelAllOrders`
-
-## Current Caveats
-
-- Binance `watchTicker()` is not suitable for L1 mapping on USD-M because it returns a 24h ticker payload without `bid` / `ask`; the adapter now uses `watchBidsAsks()` / `bookTicker`.
-- `fetchOpenOrders()` without `symbol` requires `warnOnFetchOpenOrdersWithoutSymbol = false` on the CCXT Binance USD-M exchange instance.
-- Under Bun + CCXT Pro, websocket handles can remain alive after verification. The CLI script now exits explicitly after emitting the result so the verification command terminates deterministically.
-- A simple `place/cancel` flow was insufficient to trigger `watchBalance()` on Binance demo during the 2026-03-31 investigation; the verification script now uses a real market open followed by a reduce-only market close so balance private-WS confirmation is part of the success gate.
-
-## Aster Exploration Notes
+```bash
+bun run lint
+bun run type-check
+bun run test
+```
 
-The repository still contains the earlier Aster verification script skeleton that can be used for exploratory checks:
+To run the current entry:
 
 ```bash
-bun run scripts/verify-aster-live.ts
+bun run index.ts
 ```
 
-The Aster assets are retained for experimentation and validation reference but are not the current official release gate.
+This project was created using `bun init` in bun v1.3.9. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.ts";

package/package.json

@@ -1,34 +1,25 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.1.0-beta.0",
-  "private": false,
+  "version": "0.1.0-beta.1",
+  "description": "Multi-exchange trading SDK for market data, account, and order management",
+  "module": "index.ts",
   "type": "module",
-  "packageManager": "bun@1.2.8",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": ["dist"],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+    ".": "./index.ts"
   },
+  "files": [
+    "index.ts",
+    "src/"
+  ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
-    "test": "bun test",
-    "lint": "biome check package.json tsconfig.json src tests",
-    "format": "biome format --write ."
-  },
-  "dependencies": {
-    "ccxt": "^4.5.45"
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "type-check": "tsc --noEmit",
+    "test": "bun test"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "typescript": "^5.8.2",
-    "bun-types": "^1.3.11"
+    "@biomejs/biome": "^2.4.10",
+    "@types/bun": "latest",
+    "typescript": "^6.0.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,251 @@
+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);
+
+  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,
+    amountStep,
+    minAmount: lotSizeFilter?.minQty,
+    minNotional: notionalFilter?.minNotional ?? notionalFilter?.notional,
+    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;
+
+  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,
+    pricePrecision: precisionFromStep(priceStep),
+    amountPrecision: precisionFromStep(amountStep),
+    priceStep,
+    amountStep,
+    minAmount: lotSizeFilter?.minQty,
+    minNotional: notionalFilter?.minNotional ?? notionalFilter?.notional,
+    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);
+}