@imbingox/acex 0.1.0 → 0.3.0-beta.0

package/README.md

@@ -1,25 +1,8 @@
-# acex
+# @imbingox/acex
 
-`acex` 是一个面向 Bun 的交易 SDK。
+`acex` 是一个面向交易场景的 **状态型** 多交易所 SDK。调用方持有一个 `AcexClient`，通过统一的 `market` / `account` / `order` manager 读取最新快照、消费增量事件、执行下单撤单命令；SDK 内部负责本地缓存、ready barrier、websocket 生命周期和自动重连，调用方不需要自己处理。
 
-当前 public `createClient()` 的可用范围是：
-
-- 只支持 `binance`
-- 只支持单账户
-- 默认走 `sandbox: true`
-- 当前官方验证环境是 Binance USD-M demo/testnet
-
-当前 Binance 路径分为两层：
-
-- market 行情层已经走 native adapter，支持 `spot`、`USDⓈ-M perpetual`、`COIN-M perpetual`、`COIN-M delivery`
-- `subscribeFundingRate()` 只对 perpetual 市场可用
-- account / order 仍沿用当前 Binance USD-M private 路径
-
-包名：
-
-```bash
-@imbingox/acex
-```
+当前 MVP 只落地 Binance（Spot + USDⓈ-M + COIN-M 行情，PAPI UM 私有链路）。
 
 ## 安装
 
@@ -27,333 +10,161 @@
 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
+const client = createClient();
 await client.start();
-```
-
-`start()` 之后，SDK 才会真正建立底层 runtime。
 
-如果你在 `start()` 之前调用：
-
-- `subscribeL1Book()`
-- `subscribeAccount()`
-- `subscribeOrders()`
-- 下单相关 API
-
-会直接抛错。
-
-### 4. 订阅你要的数据
-
-行情：
-
-```ts
 await client.market.subscribeL1Book({
   exchange: "binance",
-  symbol: "BTC/USDT",
+  symbol: "BTC/USDT:USDT",
 });
 
-await client.market.subscribeL1Book({
+const book = client.market.getL1Book({
   exchange: "binance",
   symbol: "BTC/USDT:USDT",
 });
+const books = client.market.getL1Books("BTC/USDT:USDT");
+console.log(`bid=${book?.bidPrice.toFixed()} ask=${book?.askPrice.toFixed()}`);
+console.log(`venues=${books.length}`);
+console.log(`book freshness=${book?.status.freshness}`);
 
 await client.market.subscribeFundingRate({
   exchange: "binance",
   symbol: "BTC/USDT:USDT",
 });
-```
-
-账户基线：
-
-```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({
+const funding = client.market.getFundingRate({
   exchange: "binance",
   symbol: "BTC/USDT:USDT",
 });
-```
+const fundingRates = client.market.getFundingRates("BTC/USDT:USDT");
+console.log(`funding=${funding?.fundingRate.toFixed()}`);
+console.log(`funding venues=${fundingRates.length}`);
 
-账户快照：
+for await (const event of client.market.events.l1BookUpdates({
+  exchange: "binance",
+  symbol: "BTC/USDT:USDT",
+})) {
+  console.log(event.snapshot.bidPrice.toFixed());
+  break;
+}
 
-```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");
+await client.stop();
 ```
 
-订单投影：
+### 账户与订单
 
 ```ts
-const openOrders = client.order.getOpenOrders("main-binance");
-const orderStatus = client.order.getOrderStatus("main-binance");
-```
+const client = createClient();
+await client.start();
 
-## 下单相关 API
+await client.registerAccount({
+  accountId: "main-binance",
+  exchange: "binance",
+  credentials: {
+    apiKey: process.env.BINANCE_PAPI_API_KEY,
+    secret: process.env.BINANCE_PAPI_SECRET,
+  },
+});
 
-当前 public API 已暴露这些命令：
+await client.account.subscribeAccount({ accountId: "main-binance" });
+await client.order.subscribeOrders({ accountId: "main-binance" });
 
-```ts
-await client.order.placeOrder({
+const created = await client.order.createOrder({
   accountId: "main-binance",
-  exchange: "binance",
   symbol: "BTC/USDT:USDT",
   side: "buy",
+  type: "limit",
+  price: "71830.6",
   amount: "0.001",
-  clientOrderId: "demo-open-1",
-  type: "market",
 });
-```
 
-```ts
 await client.order.cancelOrder({
   accountId: "main-binance",
-  exchange: "binance",
-  clientOrderId: "demo-open-1",
+  symbol: "BTC/USDT:USDT",
+  orderId: created.orderId,
 });
-```
 
-```ts
-await client.order.amendOrder({
-  accountId: "main-binance",
-  exchange: "binance",
-  clientOrderId: "demo-open-1",
-  newPrice: "65000",
-});
+await client.stop();
 ```
 
-```ts
-await client.order.cancelAllOrders({
-  accountId: "main-binance",
-  exchange: "binance",
-});
-```
-
-读取单个订单：
-
-```ts
-const order = client.order.getOrder({
-  accountId: "main-binance",
-  exchange: "binance",
-  clientOrderId: "demo-open-1",
-});
-```
+价格、数量等输出字段统一是 `BigNumber`；`createOrder()` 的 `price` / `amount` 输入仍接受 decimal string。详见手册 [§3 核心概念](./docs/api.md#3-核心概念)。
 
-## 健康状态和错误流
+## 核心能力
 
-客户端状态：
+| 能力 | 概述 | 详细文档 |
+|---|---|---|
+| **Market** | Market catalog、L1 Book / Funding Rate 订阅、增量事件、订阅状态与自动重连 | [docs/api.md §5](./docs/api.md#5-marketmanager) |
+| **Account** | 账户快照、余额、持仓、风险投影与事件流 | [docs/api.md §6](./docs/api.md#6-accountmanager) |
+| **Order** | open orders 投影、订单事件流，`createOrder` / `cancelOrder` / `cancelAllOrders` 第一版命令 | [docs/api.md §7](./docs/api.md#7-ordermanager) |
+| **健康与错误** | `getHealth()`、`events.health()`、`events.errors()` | [docs/api.md §8](./docs/api.md#8-健康与错误事件) |
 
-```ts
-const status = client.getStatus();
-const health = client.getHealth();
-```
+完整手册（接口签名、数据类型、错误码）：[docs/api.md](./docs/api.md)。
 
-监听 health：
+## 当前限制
 
-```ts
-for await (const event of client.watchHealth()) {
-  console.log("health", event);
-}
-```
+- 运行时只支持 `binance`；`okx` / `bybit` / `gate` 仅类型定义
+- 私有链路仅 Binance PAPI UM（统一账户 / Portfolio Margin）
+- Funding Rate 仅支持 Binance 永续合约，来自 mark price websocket；不支持现货和交割合约
+- `createOrder()` 只支持 `limit` / `market`；条件单、改单、账户级全撤不支持
+- 双向持仓账户下单时必须显式传 `positionSide`
+- `CreateClientOptions` 中 `sandbox` / `logger` / `logLevel` 是预留位
 
-监听内部错误：
+## 仓库内开发
 
-```ts
-for await (const event of client.watchErrors()) {
-  console.error("internal error", event);
-}
+```bash
+bun install
+bun run lint
+bun run type-check
+bun run test
 ```
 
-## 当前最值得记住的限制
+### 真实环境 smoke / soak 脚本
 
-- 这是 `Bun-only` SDK
-- 当前 public 入口只接通了 `binance`
-- 当前 public 入口只支持单账户
-- 默认就是 `sandbox: true`
-- symbol 使用 CCXT unified symbol，例如 `BTC/USDT:USDT`
-- `createClient()` 适合直接接入；仓库里的 verification script 主要用于内部验收
+不进默认 `bun run test`，单独执行：
 
-## 当前已验证的路径
+```bash
+bun run test:live:market:smoke
+bun run test:live:market:soak
+bun run test:live:account:smoke
+bun run test:live:account:soak
+bun run test:live:order:smoke
+bun run test:live:order:soak
+```
 
-截至 `2026-03-31`，Binance USD-M demo/testnet 已验证：
+约定：
 
-- `subscribeL1Book`
-- `fetchAccountBaseline`
-- `fetchOpenOrdersBaseline`
-- market `placeOrder`
-- reduce-only market `placeOrder`
-- public WS
-- private WS
-- REST baseline
+- `smoke` 默认跑 10 秒，做连通性检查，不主动断线
+- `soak` 默认跑 60 秒，并做一次主动断线重连验证
 
-这意味着：
+覆盖内容：
 
-- README 里的最小接入流程是当前实现重点保障的使用方式
-- `amendOrder` 和 `cancelAllOrders` 已有 API，但不属于首轮官方实盘验收重点
+- `market`：`loadMarkets()`、`subscribeL1Book()`、`subscribeFundingRate()`、`getL1Book()` / `getL1Books()`、`getFundingRate()` / `getFundingRates()`、对应事件流和可选断线重连（`--disconnect-target funding` 可单独验证资金费率重连）
+- `account`：Binance PAPI UM 账户 bootstrap、余额/仓位/风险投影、private stream 更新和可选重连
+- `order`：open orders bootstrap、`subscribeOrders()`、订单事件投影和可选重连
 
-## 本地开发
+### 发布流程
 
-安装依赖：
+仓库使用 **Changesets + GitHub Actions + npm Trusted Publishing**：
 
-```bash
-bun install
-```
+1. 开发 PR 时，如果改动影响用户，执行 `bun run changeset`
+2. 按提示选择 `patch` / `minor` / `major`，写一段对外 release note
+3. PR merge 到 `main` 后，[release.yml](./.github/workflows/release.yml) 会：
+   - 安装依赖
+   - 跑 `bun run lint` / `bun run type-check` / `bun run test`
+   - 若有未消费的 changeset，创建或更新 release PR
+4. merge release PR 后，同一 workflow 自动发布到 npm
 
-常用命令：
+当前仓库处于 Changesets 的 `beta` prerelease 模式，自动发布默认走 npm `beta` dist-tag。
 
-```bash
-bun run typecheck
-bun test
-bun run lint
-```
-
-## 仓库里的验证脚本
-
-如果你想直接验证 Binance demo/testnet 路径，可以跑：
-
-```bash
-bun run scripts/verify-binance-usdm-testnet.ts
-```
+npm 侧配置 Trusted Publisher 要求：
 
-这个脚本更偏“仓库验收”，不是普通业务接入时必须使用的入口。
+- workflow 文件名是 `release.yml`
+- `package.json.repository.url` 直接写仓库地址，例如 `https://github.com/imbingox/acex`
+- npm 包 settings 绑定 GitHub Actions trusted publisher，不使用长期 `NPM_TOKEN`

package/index.ts

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

package/package.json

@@ -1,34 +1,51 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.1.0",
-  "private": false,
+  "version": "0.3.0-beta.0",
+  "description": "Multi-exchange trading SDK for market data, account, and order management",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imbingox/acex.git"
+  },
+  "module": "index.ts",
   "type": "module",
-  "packageManager": "bun@1.2.8",
+  "exports": {
+    ".": "./index.ts"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": ["dist"],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
+  "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"
+    "changeset": "changeset",
+    "changeset:pre:enter:beta": "changeset pre enter beta && if [ -f .changeset/pre.json ]; then biome check --write .changeset/pre.json; fi",
+    "changeset:pre:exit": "changeset pre exit && if [ -f .changeset/pre.json ]; then biome check --write .changeset/pre.json; fi",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "release": "changeset publish",
+    "type-check": "tsc --noEmit",
+    "test": "bun test --max-concurrency=1",
+    "test:live:account": "bun run scripts/live-account-smoke.ts",
+    "test:live:account:smoke": "bun run scripts/live-account-smoke.ts --duration 10",
+    "test:live:account:soak": "bun run scripts/live-account-smoke.ts --duration 60 --disconnect-after 5",
+    "test:live:market": "bun run scripts/live-market-smoke.ts",
+    "test:live:market:smoke": "bun run scripts/live-market-smoke.ts --duration 10",
+    "test:live:market:soak": "bun run scripts/live-market-smoke.ts --duration 60 --disconnect-after 5 --disconnect-target perp",
+    "test:live:order": "bun run scripts/live-order-smoke.ts",
+    "test:live:order:smoke": "bun run scripts/live-order-smoke.ts --duration 10",
+    "test:live:order:soak": "bun run scripts/live-order-smoke.ts --duration 60 --disconnect-after 5",
+    "version-packages": "changeset version && files=\"package.json\"; if [ -f .changeset/pre.json ]; then files=\"$files .changeset/pre.json\"; fi; if [ -f CHANGELOG.md ]; then files=\"$files CHANGELOG.md\"; fi; biome check --write $files"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "typescript": "^5.8.2",
-    "bun-types": "^1.3.11"
+    "@biomejs/biome": "^2.4.10",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "latest",
+    "typescript": "^6.0.2"
+  },
+  "dependencies": {
+    "@mindfoldhq/trellis": "^0.4.0",
+    "bignumber.js": "^11.0.0"
   }
 }

package/src/adapters/binance/adapter.ts

@@ -0,0 +1,80 @@
+import type { MarketDefinition } from "../../types/index.ts";
+import type {
+  FundingRateStreamCallbacks,
+  FundingRateStreamOptions,
+  L1BookStreamCallbacks,
+  L1BookStreamOptions,
+  MarketAdapter,
+  StreamHandle,
+} from "../types.ts";
+import { subscribeBinanceBookTicker } from "./book-ticker.ts";
+import { subscribeBinanceMarkPrice } from "./mark-price.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,
+    );
+  }
+
+  createFundingRateStream(
+    market: MarketDefinition,
+    callbacks: FundingRateStreamCallbacks,
+    options: FundingRateStreamOptions,
+  ): StreamHandle {
+    const binanceMarket = this.definitions.get(market.symbol);
+    if (!binanceMarket) {
+      throw new Error(`Unknown Binance market: ${market.symbol}`);
+    }
+
+    return subscribeBinanceMarkPrice(
+      binanceMarket,
+      {
+        onFundingRate(update) {
+          callbacks.onUpdate(update);
+        },
+        onFreshnessChange: callbacks.onFreshnessChange,
+        onDisconnected: callbacks.onDisconnected,
+        onError: callbacks.onError,
+      },
+      options,
+    );
+  }
+}