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

package/README.md

@@ -1,65 +1,598 @@
-# acex
+# @imbingox/acex
 
-Bun-only trading SDK. Current official verification target: `binance`.
+`acex` 是一个面向交易场景的状态型 SDK。调用方只需要持有一个 `AcexClient`，就可以通过统一的 `market`、`account`、`order` manager 读取最新快照、订阅增量事件、观察健康状态，而不需要自己维护本地缓存、ready barrier 或 websocket 生命周期。
 
-## 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.
+```bash
+bun add @imbingox/acex
+```
 
-## Verification Direction
+## 完整用法
 
-The current official verification path is Binance USD-M testnet. The current validation target scope consists of:
+### 1. 创建 client
 
-- market WebSocket connectivity
-- private WebSocket connectivity
-- baseline bootstrap for runtime readiness
-- market `placeOrder`
-- reduce-only market `placeOrder`
+```ts
+import { createClient } from "@imbingox/acex";
+// SDK re-exports BigNumber，调用方无需单独安装 bignumber.js
+import { BigNumber } from "@imbingox/acex";
 
-Run the verification script via:
+const client = createClient();
+```
 
-```bash
-bun run scripts/verify-binance-usdm-testnet.ts
+`createClient` 接受一个可选的配置对象，当前真正生效的是 `market.*` 运行时参数：
+
+```ts
+const client = createClient({
+  market: {
+    l1InitialMessageTimeoutMs: 15_000, // L1 Book 首条消息超时（默认 15s）
+    l1StaleAfterMs: 15_000,            // 多久没收到消息标记 stale（默认 15s）
+    l1ReconnectDelayMs: 1_000,         // 断线重连初始延迟
+    l1ReconnectMaxDelayMs: 10_000,     // 断线重连最大延迟（指数退避上限）
+  },
+});
+```
+
+> `sandbox`、`logger`、`logLevel` 已预留但当前未生效。
+
+### 2. 生命周期
+
+```ts
+// 启动 client（必须在所有 subscribe 之前）
+await client.start();
+
+// ... 使用 client ...
+
+// 停止 client（释放所有 websocket、订阅关系）
+await client.stop();
+
+// 也可以指定优雅退出选项
+await client.stop({ graceful: true, timeoutMs: 5000 });
+```
+
+Client 的状态机：`idle` → `starting` → `running` → `stopping` → `stopped`。
+
+可以通过 `client.getStatus()` 随时查看当前状态。
+
+### 3. Market Catalog（市场列表）
+
+加载市场列表后可以发现可用交易对、读取精度参数：
+
+```ts
+// 拉取并缓存所有交易所的 market catalog
+await client.market.loadMarkets();
+
+// 列出所有 market
+const markets = client.market.listMarkets();
+// → MarketDefinition[]
+
+// 只列出指定交易所的 market
+const binanceMarkets = client.market.listMarkets("binance");
+
+// 按交易所 + 统一 symbol 查询单个 market
+const btcPerp = client.market.getMarket("binance", "BTC/USDT:USDT");
+// → MarketDefinition | undefined
+
+// 查询一个 symbol 在所有交易所的 market（多交易所场景）
+const allBtcPerp = client.market.findMarkets("BTC/USDT:USDT");
+// → MarketDefinition[]
+```
+
+返回的 `MarketDefinition` 包含以下字段：
+
+```ts
+{
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",    // 统一 symbol
+  id: "BTCUSDT",              // 交易所原始 symbol
+  type: "swap",               // "spot" | "swap" | "future"
+  base: "BTC",
+  quote: "USDT",
+  settle: "USDT",             // 结算币种（swap/future 才有）
+  active: true,               // 是否可交易
+  contract: true,             // 是否合约
+  linear: true,               // U 本位
+  inverse: false,             // 币本位
+  contractSize: BigNumber(1),
+  pricePrecision: 1,
+  amountPrecision: 3,
+  priceStep: BigNumber(0.10),          // 最小价格变动
+  amountStep: BigNumber(0.001),        // 最小数量变动
+  minNotional: BigNumber(5),           // 最小名义价值
+  raw: { ... },               // 交易所原始数据
+}
+```
+
+> 所有价格、数量、金额字段均为 `BigNumber` 类型（来自 [bignumber.js](https://github.com/MikeMcl/bignumber.js)），可直接进行算术运算。
+
+**统一 symbol 约定：**
+
+| symbol 格式 | 含义 | 示例 |
+|---|---|---|
+| `BASE/QUOTE` | spot 现货 | `BTC/USDT` |
+| `BASE/QUOTE:SETTLE` | USDⓈ-M 永续 | `BTC/USDT:USDT` |
+| `BASE/USD:BASE` | COIN-M 永续 | `BTC/USD:BTC` |
+| `BASE/USD:BASE-YYYYMMDD` | COIN-M 交割 | `BTC/USD:BTC-20250627` |
+
+### 4. L1 Book（最优买卖价）
+
+这是当前最核心的实时数据能力。
+
+#### 订阅
+
+```ts
+// subscribeL1Book 是 ready barrier：
+// await 返回后，getL1Book 已经可以拿到首个可用快照
+await client.market.subscribeL1Book({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+});
+```
+
+`subscribeL1Book` 会自动确保 market catalog 已加载，所以不必手动先调 `loadMarkets()`。
+
+#### 读取快照
+
+```ts
+const book = client.market.getL1Book({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+});
+
+if (book) {
+  console.log(book.bidPrice, book.bidSize); // 最优买（BigNumber）
+  console.log(book.askPrice, book.askSize); // 最优卖（BigNumber）
+  // 直接算术运算
+  const spread = book.askPrice.minus(book.bidPrice);
+  console.log(`spread: ${spread.toFixed()}`);
+}
+```
+
+`L1Book` 完整结构：
+
+```ts
+{
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+  bidPrice: BigNumber("104321.50"),
+  bidSize: BigNumber("1.234"),
+  askPrice: BigNumber("104321.60"),
+  askSize: BigNumber("0.567"),
+  exchangeTs: 1710000000000,  // 交易所时间戳（可能为空）
+  receivedAt: 1710000000001,  // SDK 收到时间
+  updatedAt: 1710000000001,   // SDK 更新时间
+  version: 42,                // 递增序号
+}
+```
+
+> 所有价格和数量都是 `BigNumber` 类型，避免浮点精度问题，可直接进行算术运算。
+
+#### 消费增量事件
+
+```ts
+// events.* 只消费事件，不会隐式触发订阅
+// 必须先 subscribeL1Book 才会有数据流
+for await (const event of client.market.events.l1BookUpdates({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+})) {
+  console.log(event.snapshot.bidPrice, event.snapshot.askPrice);
+}
 ```
 
-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
+const iterator = client.market.events
+  .l1BookUpdates({ exchange: "binance", symbol: "BTC/USDT:USDT" })
+  [Symbol.asyncIterator]();
 
-- `BINANCE_USDM_API_KEY`
-- `BINANCE_USDM_API_SECRET`
-- `BINANCE_USDM_SYMBOL`
-- `BINANCE_USDM_ORDER_SIZE`
-- `BINANCE_USDM_ORDER_PRICE`
+const { value, done } = await iterator.next();
+if (!done) {
+  console.log(value.snapshot);
+}
+
+// 不再消费时，释放迭代器
+await iterator.return?.();
+```
+
+不传 filter 可以接收所有 symbol 的更新：
+
+```ts
+for await (const event of client.market.events.l1BookUpdates()) {
+  console.log(event.exchange, event.symbol, event.snapshot.bidPrice);
+}
+```
+
+#### 事件当触发器（推荐模式）
+
+`event.snapshot` 是事件发生那一刻的快照，但由于事件异步消费，处理时内部状态可能已被更新。如果你需要同时读取多个 symbol 的最新价格（如套利、对冲），推荐把事件当触发器，用 `getL1Book()` 读最新值：
+
+```ts
+const pairs = [
+  { exchange: "binance", symbol: "BTC/USDT:USDT" },
+  { exchange: "binance", symbol: "BTC/USD:BTC" },
+];
+
+for (const pair of pairs) {
+  await client.market.subscribeL1Book(pair);
+}
+
+// 不带 filter — 任何 symbol 变动都触发
+for await (const event of client.market.events.l1BookUpdates()) {
+  const books = pairs.map((pair) => ({
+    ...pair,
+    book: client.market.getL1Book(pair),
+  }));
+
+  if (books.some((b) => !b.book)) continue;
+
+  // 所有 symbol 的最新价格，执行你的策略逻辑
+  doSomething(books);
+}
+```
+
+#### 查看订阅状态
+
+```ts
+const status = client.market.getMarketStatus({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+});
+
+if (status) {
+  status.activity;      // "active" | "inactive"
+  status.ready;         // 首次 ready 是否完成
+  status.freshness;     // "fresh" | "stale" | "reconciling"
+  status.lastReceivedAt; // 最后收到数据的时间
+  status.reason;        // 变 stale 的原因: "ws_disconnected" | "heartbeat_timeout"
+}
+```
 
-`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
+```ts
+await client.market.unsubscribeL1Book({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+});
+```
+
+退订后最后一份快照仍可读，但 `activity` 会变成 `"inactive"`。调用方不应把旧快照当成实时值。
+
+### 5. Account（账户余额和仓位）
+
+> 当前 account 是占位实现，contract 已稳定但不是完整真实私有流。
+
+```ts
+// ① 注册账户（start 之前或之后均可）
+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.account.subscribeAccount({ accountId: "main-binance" });
+
+// ③ 读取快照
+const snapshot = client.account.getAccountSnapshot("main-binance");
+// → AccountSnapshot | undefined
+
+const balances = client.account.getBalances("main-binance");
+// → BalanceSnapshot[]
+
+const usdtBalance = client.account.getBalance("main-binance", "USDT");
+// → BalanceSnapshot | undefined
+// { asset: "USDT", free: BigNumber("1000.00"), used: BigNumber("200.00"), total: BigNumber("1200.00"), ... }
+
+const positions = client.account.getPositions("main-binance");
+// → PositionSnapshot[]
+
+const btcPosition = client.account.getPosition({
+  accountId: "main-binance",
+  symbol: "BTC/USDT:USDT",
+  side: "long",  // 可选，不传则返回第一个匹配
+});
+// → PositionSnapshot | undefined
+// { symbol, side, size, entryPrice, markPrice, unrealizedPnl, leverage, ... }
+
+const risk = client.account.getRiskSnapshot("main-binance");
+// → RiskSnapshot | undefined
+// { equity, marginRatio, initialMargin, maintenanceMargin, ... }
+
+// ④ 消费增量事件
+for await (const event of client.account.events.updates({
+  accountId: "main-binance",
+})) {
+  switch (event.type) {
+    case "balance.updated":
+      console.log(event.asset, event.snapshot.free);
+      break;
+    case "position.updated":
+      console.log(event.symbol, event.snapshot.size);
+      break;
+    case "risk.updated":
+      console.log(event.snapshot.marginRatio);
+      break;
+    case "account.snapshot_replaced":
+      console.log("全量快照替换");
+      break;
+  }
+}
+
+// ⑤ 退订 & 移除账户
+await client.account.unsubscribeAccount({ accountId: "main-binance" });
+await client.removeAccount("main-binance");
+```
+
+### 6. Order（订单）
+
+> 当前 order 是占位实现，contract 已稳定但不是完整真实私有流。
+
+```ts
+// 订阅订单流（需要先 registerAccount）
+await client.order.subscribeOrders({ accountId: "main-binance" });
+
+// 读取所有挂单
+const openOrders = client.order.getOpenOrders("main-binance");
+// → OrderSnapshot[]
+
+// 按 symbol 过滤挂单
+const btcOrders = client.order.getOpenOrders("main-binance", "BTC/USDT:USDT");
+
+// 按 orderId 或 clientOrderId 查询单笔
+const order = client.order.getOrder({
+  accountId: "main-binance",
+  orderId: "12345",
+});
+// → OrderSnapshot | undefined
+// { symbol, side, type, status, price, amount, filled, remaining, ... }
+
+// 消费订单事件
+for await (const event of client.order.events.updates({
+  accountId: "main-binance",
+})) {
+  switch (event.type) {
+    case "order.updated":
+      console.log("订单更新", event.snapshot.status);
+      break;
+    case "order.filled":
+      console.log("完全成交", event.snapshot.avgFillPrice);
+      break;
+    case "order.canceled":
+      console.log("已撤单");
+      break;
+    case "order.rejected":
+      console.log("被拒绝");
+      break;
+  }
+}
+
+// 退订
+await client.order.unsubscribeOrders({ accountId: "main-binance" });
+```
+
+### 7. 健康监控
+
+#### 全局健康快照
+
+```ts
+const health = client.getHealth();
+// → ClientHealthSnapshot
+// {
+//   clientStatus: "running",
+//   markets: MarketDataStatus[],   // 所有 market 订阅的状态
+//   accounts: AccountDataStatus[], // 所有 account 订阅的状态
+//   orders: OrderDataStatus[],     // 所有 order 订阅的状态
+//   updatedAt: 1710000000000,
+// }
+```
+
+#### 消费健康事件流
+
+```ts
+for await (const event of client.events.health()) {
+  switch (event.type) {
+    case "client.status_changed":
+      console.log("client 状态变化:", event.status);
+      break;
+    case "market.status_changed":
+      console.log("market 状态变化:", event.exchange, event.symbol);
+      break;
+    case "account.status_changed":
+      console.log("account 状态变化:", event.accountId);
+      break;
+    case "order.status_changed":
+      console.log("order 状态变化:", event.accountId);
+      break;
+  }
+}
+```
+
+可以按 scope 过滤：
+
+```ts
+// 只关心 market 相关的健康变化
+for await (const event of client.events.health({ scope: "market" })) {
+  // ...
+}
+
+// 只关心特定交易所
+for await (const event of client.events.health({ exchange: "binance" })) {
+  // ...
+}
+```
+
+#### 消费内部错误流
+
+```ts
+for await (const err of client.events.errors()) {
+  console.error(`[${err.source}] ${err.error.message}`, {
+    exchange: err.exchange,
+    symbol: err.symbol,
+    accountId: err.accountId,
+  });
+}
+```
+
+适合桥接到日志系统或告警系统。
+
+### 8. 错误处理
+
+SDK 的可预期错误统一通过 `AcexError` 抛出，包含结构化的 `code`：
+
+```ts
+import { AcexError } from "@imbingox/acex";
+
+try {
+  await client.market.subscribeL1Book({
+    exchange: "binance",
+    symbol: "INVALID/PAIR",
+  });
+} catch (error) {
+  if (error instanceof AcexError) {
+    switch (error.code) {
+      case "CLIENT_NOT_STARTED":
+        // client 还没 start()
+        break;
+      case "MARKET_NOT_FOUND":
+        // symbol 不存在
+        break;
+      case "MARKET_INACTIVE":
+        // 市场存在但不可交易
+        break;
+      case "MARKET_STREAM_TIMEOUT":
+        // L1 Book 首条消息超时
+        break;
+      case "EXCHANGE_NOT_SUPPORTED":
+        // 交易所未支持
+        break;
+      case "MARKET_CATALOG_LOAD_FAILED":
+        // market catalog 拉取失败
+        break;
+      case "ACCOUNT_ALREADY_EXISTS":
+        // 重复注册同一个 accountId
+        break;
+      case "ACCOUNT_NOT_FOUND":
+        // accountId 不存在
+        break;
+      case "CREDENTIALS_MISSING":
+        // 私有订阅缺少凭证
+        break;
+    }
+  }
+}
+```
+
+## 完整示例
+
+```ts
+import { AcexError, createClient } from "@imbingox/acex";
+
+async function main() {
+  const client = createClient({
+    market: {
+      l1InitialMessageTimeoutMs: 15_000,
+      l1StaleAfterMs: 15_000,
+    },
+  });
+
+  await client.start();
+
+  // 加载市场列表
+  await client.market.loadMarkets();
+  const symbols = client.market.listMarkets().map((m) => m.symbol);
+  console.log(`共 ${symbols.length} 个交易对`);
+
+  // 订阅 BTC 永续 L1 Book
+  const exchange = "binance";
+  const symbol = "BTC/USDT:USDT";
+
+  await client.market.subscribeL1Book({ exchange, symbol });
+
+  // 读取首个快照
+  const book = client.market.getL1Book({ exchange, symbol });
+  console.log(`BTC bid=${book?.bidPrice.toFixed()} ask=${book?.askPrice.toFixed()}`);
+
+  // 持续消费 5 条更新后退出
+  let count = 0;
+  for await (const event of client.market.events.l1BookUpdates({
+    exchange,
+    symbol,
+  })) {
+    console.log(
+      `#${++count} bid=${event.snapshot.bidPrice.toFixed()} ask=${event.snapshot.askPrice.toFixed()}`,
+    );
+    if (count >= 5) break;
+  }
+
+  await client.market.unsubscribeL1Book({ exchange, symbol });
+  await client.stop();
+}
+
+main().catch((error) => {
+  if (error instanceof AcexError) {
+    console.error(error.code, error.message);
+  } else {
+    console.error(error);
+  }
+});
+```
+
+## 调用顺序总结
+
+```
+createClient()
+  ↓
+registerAccount()          ← 如需私有能力（可选）
+  ↓
+client.start()
+  ↓
+loadMarkets()              ← 如需市场列表（可选）
+  ↓
+subscribe*()               ← 开始维护数据
+  ↓
+get*() / events.*()        ← 读快照 / 消费增量
+  ↓
+unsubscribe*()             ← 释放订阅
+  ↓
+removeAccount()            ← 释放账户（可选）
+  ↓
+client.stop()
+```
 
-- 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
+| 概念 | 说明 |
+|---|---|
+| `get*()` | 读 SDK 本地快照，不阻塞、不发网络请求 |
+| `events.*()` | 返回 `AsyncIterable`，持续消费增量变化 |
+| `event.snapshot` vs `get*()` | `event.snapshot` 是事件发生时的快照；`get*()` 是调用时的最新值。跨 symbol 比较建议用 `get*()` |
+| `subscribe*()` | ready barrier — `await` 返回时对应的 `get*()` 已可用 |
+| `events.*()` 与 `subscribe*()` | 独立。`events` 不会隐式触发订阅，必须显式 `subscribe` |
+| 退订后的缓存 | 最后一份快照仍可读，但 `activity` 变为 `"inactive"` |
 
-- 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
+- 运行时真正支持的市场数据交易所只有 **Binance**（`okx`、`bybit`、`gate` 仅类型定义）
+- 真实落地的数据链路只有 Binance **L1 Book**
+- `fundingRate` 接口已暴露，但当前是占位快照
+- `account` / `order` 当前是占位实现，不是完整真实私有流
+- `CreateClientOptions` 中 `sandbox`、`logger`、`logLevel` 仍是预留位
 
-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 install
+bun run lint
+bun run type-check
+bun test
 ```
 
-The Aster assets are retained for experimentation and validation reference but are not the current official release gate.
+更完整的公开接口设计说明见 [docs/sdk-public-api.md](./docs/sdk-public-api.md)。

package/index.ts

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

package/package.json

@@ -1,34 +1,29 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.1.0-beta.0",
-  "private": false,
+  "version": "0.1.0-beta.2",
+  "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"
+  },
+  "dependencies": {
+    "@mindfoldhq/trellis": "^0.4.0",
+    "bignumber.js": "^11.0.0"
   }
 }