@imbingox/acex 0.1.0-beta.0 → 0.1.0

package/README.md

@@ -1,65 +1,359 @@
 # acex
 
-Bun-only trading SDK. Current official verification target: `binance`.
+`acex` 是一个面向 Bun 的交易 SDK。
 
-## Current Direction
+当前 public `createClient()` 的可用范围是：
 
-- 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.
+- 只支持 `binance`
+- 只支持单账户
+- 默认走 `sandbox: true`
+- 当前官方验证环境是 Binance USD-M demo/testnet
 
-## Verification Direction
+当前 Binance 路径分为两层：
 
-The current official verification path is Binance USD-M testnet. The current validation target scope consists of:
+- market 行情层已经走 native adapter，支持 `spot`、`USDⓈ-M perpetual`、`COIN-M perpetual`、`COIN-M delivery`
+- `subscribeFundingRate()` 只对 perpetual 市场可用
+- account / order 仍沿用当前 Binance USD-M private 路径
 
-- market WebSocket connectivity
-- private WebSocket connectivity
-- baseline bootstrap for runtime readiness
-- market `placeOrder`
-- reduce-only market `placeOrder`
+包名：
 
-Run the verification script via:
+```bash
+@imbingox/acex
+```
+
+## 安装
 
 ```bash
-bun run scripts/verify-binance-usdm-testnet.ts
+bun add @imbingox/acex
+```
+
+## 你会怎么用它
+
+典型流程只有 5 步：
+
+1. `createClient()` 创建客户端
+2. `registerAccount()` 注册账户
+3. `start()` 启动运行时
+4. `subscribe...()` 建立你关心的数据订阅
+5. 用 `get...()` 读取当前最新快照，或用下单 API 发命令
+
+## 最小示例
+
+下面这段就是当前推荐的接入方式：
+
+```ts
+import { createClient } from "@imbingox/acex";
+
+async function main() {
+  const client = createClient({
+    sandbox: true,
+  });
+
+  await client.registerAccount({
+    accountId: "main-binance",
+    exchange: "binance",
+    credentials: {
+      apiKey: process.env.BINANCE_API_KEY!,
+      secret: process.env.BINANCE_API_SECRET!,
+    },
+  });
+
+  await client.start();
+
+  await client.market.subscribeL1Book({
+    exchange: "binance",
+    symbol: "BTC/USDT",
+  });
+
+  await client.market.subscribeL1Book({
+    exchange: "binance",
+    symbol: "BTC/USDT:USDT",
+  });
+
+  await client.market.subscribeFundingRate({
+    exchange: "binance",
+    symbol: "BTC/USDT:USDT",
+  });
+
+  await client.account.subscribeAccount({
+    accountId: "main-binance",
+  });
+
+  await client.order.subscribeOrders({
+    accountId: "main-binance",
+  });
+
+  const book = client.market.getL1Book({
+    exchange: "binance",
+    symbol: "BTC/USDT:USDT",
+  });
+
+  const account = client.account.getAccountSnapshot("main-binance");
+  const orderStatus = client.order.getOrderStatus("main-binance");
+
+  console.log({
+    status: client.getStatus(),
+    health: client.getHealth(),
+    book,
+    account,
+    orderStatus,
+  });
+
+  await client.stop();
+}
+
+void main();
+```
+
+## 运行顺序说明
+
+### 1. 创建客户端
+
+```ts
+const client = createClient({
+  sandbox: true,
+});
+```
+
+当前只支持一个选项：
+
+- `sandbox`
+
+说明：
+
+- `sandbox` 默认就是 `true`
+- 对当前实现来说，`sandbox: true` 对应 Binance USD-M demo/testnet 路径
+
+### 2. 注册账户
+
+```ts
+await client.registerAccount({
+  accountId: "main-binance",
+  exchange: "binance",
+  credentials: {
+    apiKey: process.env.BINANCE_API_KEY!,
+    secret: process.env.BINANCE_API_SECRET!,
+  },
+});
+```
+
+当前约束：
+
+- `accountId` 不能为空
+- `exchange` 只能是 `binance`
+- `apiKey` 和 `secret` 不能为空
+- 一个 `client` 现在只能注册一个账户
+
+### 3. 启动运行时
+
+```ts
+await client.start();
+```
+
+`start()` 之后，SDK 才会真正建立底层 runtime。
+
+如果你在 `start()` 之前调用：
+
+- `subscribeL1Book()`
+- `subscribeAccount()`
+- `subscribeOrders()`
+- 下单相关 API
+
+会直接抛错。
+
+### 4. 订阅你要的数据
+
+行情：
+
+```ts
+await client.market.subscribeL1Book({
+  exchange: "binance",
+  symbol: "BTC/USDT",
+});
+
+await client.market.subscribeL1Book({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+});
+
+await client.market.subscribeFundingRate({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+});
 ```
 
-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:
+```ts
+await client.account.subscribeAccount({
+  accountId: "main-binance",
+});
+```
+
+订单基线：
+
+```ts
+await client.order.subscribeOrders({
+  accountId: "main-binance",
+});
+```
+
+建议：
+
+- 要读余额/仓位前，先做 `subscribeAccount()`
+- 要读 open orders / order status 前，先做 `subscribeOrders()`
+
+### 5. 读取最新快照
+
+行情快照：
+
+```ts
+const book = client.market.getL1Book({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+});
+```
+
+账户快照：
+
+```ts
+const account = client.account.getAccountSnapshot("main-binance");
+const balances = client.account.getBalances("main-binance");
+const positions = client.account.getPositions("main-binance");
+const risk = client.account.getRiskSnapshot("main-binance");
+```
+
+订单投影：
+
+```ts
+const openOrders = client.order.getOpenOrders("main-binance");
+const orderStatus = client.order.getOrderStatus("main-binance");
+```
+
+## 下单相关 API
+
+当前 public API 已暴露这些命令：
+
+```ts
+await client.order.placeOrder({
+  accountId: "main-binance",
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+  side: "buy",
+  amount: "0.001",
+  clientOrderId: "demo-open-1",
+  type: "market",
+});
+```
+
+```ts
+await client.order.cancelOrder({
+  accountId: "main-binance",
+  exchange: "binance",
+  clientOrderId: "demo-open-1",
+});
+```
+
+```ts
+await client.order.amendOrder({
+  accountId: "main-binance",
+  exchange: "binance",
+  clientOrderId: "demo-open-1",
+  newPrice: "65000",
+});
+```
+
+```ts
+await client.order.cancelAllOrders({
+  accountId: "main-binance",
+  exchange: "binance",
+});
+```
 
-- `BINANCE_USDM_API_KEY`
-- `BINANCE_USDM_API_SECRET`
-- `BINANCE_USDM_SYMBOL`
-- `BINANCE_USDM_ORDER_SIZE`
-- `BINANCE_USDM_ORDER_PRICE`
+读取单个订单：
 
-`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.
+```ts
+const order = client.order.getOrder({
+  accountId: "main-binance",
+  exchange: "binance",
+  clientOrderId: "demo-open-1",
+});
+```
+
+## 健康状态和错误流
+
+客户端状态：
+
+```ts
+const status = client.getStatus();
+const health = client.getHealth();
+```
+
+监听 health：
+
+```ts
+for await (const event of client.watchHealth()) {
+  console.log("health", event);
+}
+```
+
+监听内部错误：
+
+```ts
+for await (const event of client.watchErrors()) {
+  console.error("internal error", event);
+}
+```
+
+## 当前最值得记住的限制
+
+- 这是 `Bun-only` SDK
+- 当前 public 入口只接通了 `binance`
+- 当前 public 入口只支持单账户
+- 默认就是 `sandbox: true`
+- symbol 使用 CCXT unified symbol，例如 `BTC/USDT:USDT`
+- `createClient()` 适合直接接入；仓库里的 verification script 主要用于内部验收
 
-## 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`
+截至 `2026-03-31`，Binance USD-M demo/testnet 已验证：
 
-## Current Caveats
+- `subscribeL1Book`
+- `fetchAccountBaseline`
+- `fetchOpenOrdersBaseline`
+- market `placeOrder`
+- reduce-only market `placeOrder`
+- public WS
+- private WS
+- REST baseline
+
+这意味着：
+
+- README 里的最小接入流程是当前实现重点保障的使用方式
+- `amendOrder` 和 `cancelAllOrders` 已有 API，但不属于首轮官方实盘验收重点
 
-- 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 install
+```
 
-The repository still contains the earlier Aster verification script skeleton that can be used for exploratory checks:
+常用命令：
 
 ```bash
-bun run scripts/verify-aster-live.ts
+bun run typecheck
+bun test
+bun run lint
+```
+
+## 仓库里的验证脚本
+
+如果你想直接验证 Binance demo/testnet 路径，可以跑：
+
+```bash
+bun run scripts/verify-binance-usdm-testnet.ts
 ```
 
-The Aster assets are retained for experimentation and validation reference but are not the current official release gate.
+这个脚本更偏“仓库验收”，不是普通业务接入时必须使用的入口。

package/dist/adapters/binance/composite-adapter.d.ts

@@ -0,0 +1,116 @@
+import type { ExchangeAdapter, NormalizedAccountEvent, NormalizedMarketEvent, NormalizedOrderEvent } from "../types.js";
+interface BinanceMarketInfoRecord {
+    exchange: string;
+    symbol: string;
+    baseAsset: string;
+    quoteAsset: string;
+    marketType: string;
+    pricePrecision: number;
+    amountPrecision: number;
+    active: boolean;
+}
+interface BinanceCompositeMarketAdapter extends ExchangeAdapter {
+    fetchMarketInfo(): Promise<BinanceMarketInfoRecord[]>;
+}
+export declare class BinanceCompositeAdapter implements ExchangeAdapter {
+    private readonly input;
+    readonly exchange = "binance";
+    constructor(input: {
+        marketAdapter: BinanceCompositeMarketAdapter;
+        privateAdapter: ExchangeAdapter;
+    });
+    get capabilities(): {
+        publicWs: boolean;
+        l1BookStream: boolean;
+        fundingRateStream: boolean;
+        fetchMarketInfo: boolean;
+        privateWs: boolean;
+        accountStream: boolean;
+        orderStream: boolean;
+        fetchBalances: boolean;
+        fetchPositions: boolean;
+        fetchRisk: boolean;
+        fetchOpenOrders: boolean;
+        fetchMyTrades: boolean;
+        fetchOrderById: boolean;
+    };
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    subscribeL1Book(input: {
+        exchange: string;
+        symbol: string;
+    }): Promise<void>;
+    subscribeFundingRate(input: {
+        exchange: string;
+        symbol: string;
+    }): Promise<void>;
+    fetchMarketInfo(): Promise<BinanceMarketInfoRecord[]>;
+    watchMarketEvents(): AsyncIterable<NormalizedMarketEvent>;
+    setMarketEventSink(sink: ((event: NormalizedMarketEvent) => void) | undefined): void;
+    watchInternalErrors(): AsyncGenerator<Error, void, any>;
+    subscribeOrders(input: {
+        accountId: string;
+    }): Promise<void>;
+    fetchOpenOrdersBaseline(accountId: string): Promise<({
+        accountId: string;
+        exchange: string;
+        symbol: string;
+        side: "buy" | "sell";
+        type: string;
+        status: string;
+        amount: string;
+        filled: string;
+        price?: string;
+        seq: number;
+        receivedAt: number;
+        updatedAt: number;
+        orderId?: string;
+        clientOrderId?: string;
+    } | {
+        accountId: string;
+        exchange: string;
+        symbol: string;
+        side: "buy" | "sell";
+        type: string;
+        status: string;
+        amount: string;
+        filled: string;
+        price?: string;
+        seq: number;
+        receivedAt: number;
+        updatedAt: number;
+        orderId?: string;
+        clientOrderId?: string;
+    })[]>;
+    watchOrderEvents(): AsyncIterable<NormalizedOrderEvent>;
+    setOrderEventSink(sink: ((event: NormalizedOrderEvent) => void) | undefined): void;
+    fetchAccountBaseline(accountId: string): Promise<import("../types.js").AdapterAccountBaseline>;
+    watchAccountEvents(): AsyncIterable<NormalizedAccountEvent>;
+    setAccountEventSink(sink: ((event: NormalizedAccountEvent) => void) | undefined): void;
+    placeOrder(input: Parameters<ExchangeAdapter["placeOrder"]>[0]): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        receivedAt: number;
+    }>;
+    amendOrder(input: Parameters<ExchangeAdapter["amendOrder"]>[0]): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        receivedAt: number;
+    }>;
+    cancelOrder(input: Parameters<ExchangeAdapter["cancelOrder"]>[0]): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        receivedAt: number;
+    }>;
+    cancelAllOrders(input: Parameters<ExchangeAdapter["cancelAllOrders"]>[0]): Promise<{
+        accountId: string;
+        exchange: string;
+        canceledCount: number;
+    }>;
+    getHealth(): {
+        exchange: string;
+        status: string;
+        wsConnected: boolean;
+    };
+}
+export {};

package/dist/adapters/binance/composite-adapter.js

@@ -0,0 +1,121 @@
+import { createAsyncQueue } from "../../runtime/async-queue.js";
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+async function* mergeErrors(left, right) {
+    const queue = createAsyncQueue({ maxBufferSize: 20 });
+    let completedStreams = 0;
+    const forward = async (source) => {
+        try {
+            for await (const error of source) {
+                queue.push(error);
+            }
+        }
+        catch (error) {
+            queue.push(toError(error));
+        }
+        finally {
+            completedStreams += 1;
+            if (completedStreams === 2) {
+                queue.close();
+            }
+        }
+    };
+    void forward(left);
+    void forward(right);
+    yield* queue;
+}
+export class BinanceCompositeAdapter {
+    input;
+    exchange = "binance";
+    constructor(input) {
+        this.input = input;
+    }
+    get capabilities() {
+        return {
+            ...this.input.privateAdapter.capabilities,
+            publicWs: this.input.marketAdapter.capabilities.publicWs,
+            l1BookStream: this.input.marketAdapter.capabilities.l1BookStream,
+            fundingRateStream: this.input.marketAdapter.capabilities.fundingRateStream,
+            fetchMarketInfo: this.input.marketAdapter.capabilities.fetchMarketInfo,
+        };
+    }
+    async start() {
+        await this.input.marketAdapter.start();
+        try {
+            await this.input.privateAdapter.start();
+        }
+        catch (error) {
+            await this.input.marketAdapter.stop();
+            throw error;
+        }
+    }
+    async stop() {
+        await Promise.allSettled([this.input.marketAdapter.stop(), this.input.privateAdapter.stop()]);
+    }
+    async subscribeL1Book(input) {
+        return this.input.marketAdapter.subscribeL1Book(input);
+    }
+    async subscribeFundingRate(input) {
+        return this.input.marketAdapter.subscribeFundingRate(input);
+    }
+    async fetchMarketInfo() {
+        return this.input.marketAdapter.fetchMarketInfo();
+    }
+    watchMarketEvents() {
+        return this.input.marketAdapter.watchMarketEvents();
+    }
+    setMarketEventSink(sink) {
+        this.input.marketAdapter.setMarketEventSink?.(sink);
+    }
+    watchInternalErrors() {
+        return mergeErrors(this.input.marketAdapter.watchInternalErrors(), this.input.privateAdapter.watchInternalErrors());
+    }
+    async subscribeOrders(input) {
+        return this.input.privateAdapter.subscribeOrders(input);
+    }
+    async fetchOpenOrdersBaseline(accountId) {
+        return this.input.privateAdapter.fetchOpenOrdersBaseline(accountId);
+    }
+    watchOrderEvents() {
+        return this.input.privateAdapter.watchOrderEvents();
+    }
+    setOrderEventSink(sink) {
+        this.input.privateAdapter.setOrderEventSink?.(sink);
+    }
+    async fetchAccountBaseline(accountId) {
+        return this.input.privateAdapter.fetchAccountBaseline(accountId);
+    }
+    watchAccountEvents() {
+        return this.input.privateAdapter.watchAccountEvents();
+    }
+    setAccountEventSink(sink) {
+        this.input.privateAdapter.setAccountEventSink?.(sink);
+    }
+    async placeOrder(input) {
+        return this.input.privateAdapter.placeOrder(input);
+    }
+    async amendOrder(input) {
+        return this.input.privateAdapter.amendOrder(input);
+    }
+    async cancelOrder(input) {
+        return this.input.privateAdapter.cancelOrder(input);
+    }
+    async cancelAllOrders(input) {
+        return this.input.privateAdapter.cancelAllOrders(input);
+    }
+    getHealth() {
+        const market = this.input.marketAdapter.getHealth();
+        const privateHealth = this.input.privateAdapter.getHealth();
+        const status = market.status === "healthy" && privateHealth.status === "healthy"
+            ? "healthy"
+            : market.status === "idle" && privateHealth.status === "idle"
+                ? "idle"
+                : "degraded";
+        return {
+            exchange: this.exchange,
+            status,
+            wsConnected: market.wsConnected && privateHealth.wsConnected,
+        };
+    }
+}

package/dist/adapters/binance/market-types.d.ts

@@ -0,0 +1,63 @@
+export type BinanceMarketFamily = "spot" | "usdm" | "coinm";
+export interface BinanceSymbolFilter {
+    filterType: string;
+    tickSize?: string;
+    stepSize?: string;
+}
+export interface BinanceSpotExchangeInfo {
+    symbols: Array<{
+        symbol: string;
+        status: string;
+        baseAsset: string;
+        quoteAsset: string;
+        filters: BinanceSymbolFilter[];
+    }>;
+}
+export interface BinanceUsdmExchangeInfo {
+    symbols: Array<{
+        symbol: string;
+        pair: string;
+        status: string;
+        contractType: string;
+        baseAsset: string;
+        quoteAsset: string;
+        marginAsset: string;
+        pricePrecision: number;
+        quantityPrecision: number;
+        filters: BinanceSymbolFilter[];
+    }>;
+}
+export interface BinanceCoinmExchangeInfo {
+    symbols: Array<{
+        symbol: string;
+        pair: string;
+        contractType: string;
+        contractStatus: string;
+        baseAsset: string;
+        quoteAsset: string;
+        marginAsset: string;
+        deliveryDate?: number;
+        pricePrecision: number;
+        quantityPrecision: number;
+        filters: BinanceSymbolFilter[];
+    }>;
+}
+export interface BinanceMarketRecord {
+    exchange: "binance";
+    family: BinanceMarketFamily;
+    nativeSymbol: string;
+    unifiedSymbol: string;
+    baseAsset: string;
+    quoteAsset: string;
+    settleAsset?: string;
+    contractType?: string;
+    fundingEligible: boolean;
+    active: boolean;
+    pricePrecision: number;
+    amountPrecision: number;
+}
+export interface BinanceMarketIndex {
+    byUnifiedSymbol: Map<string, BinanceMarketRecord>;
+    byNativeSymbol: Map<string, BinanceMarketRecord>;
+    markets: BinanceMarketRecord[];
+}

package/dist/adapters/binance/market-types.js

@@ -0,0 +1 @@
+export {};