npm package: @imbingox/acex
Description: `acex` 是一个面向 Bun 的交易 SDK。
Latest version: 0.1.0

# acex

`acex` 是一个面向 Bun 的交易 SDK。

当前 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
```

## 安装

```bash
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",
});
```

账户基线：

```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",
});
```

读取单个订单：

```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 主要用于内部验收

## 当前已验证的路径

截至 `2026-03-31`，Binance USD-M demo/testnet 已验证：

- `subscribeL1Book`
- `fetchAccountBaseline`
- `fetchOpenOrdersBaseline`
- market `placeOrder`
- reduce-only market `placeOrder`
- public WS
- private WS
- REST baseline

这意味着：

- README 里的最小接入流程是当前实现重点保障的使用方式
- `amendOrder` 和 `cancelAllOrders` 已有 API，但不属于首轮官方实盘验收重点

## 本地开发

安装依赖：

```bash
bun install
```

常用命令：

```bash
bun run typecheck
bun test
bun run lint
```

## 仓库里的验证脚本

如果你想直接验证 Binance demo/testnet 路径，可以跑：

```bash
bun run scripts/verify-binance-usdm-testnet.ts
```

这个脚本更偏“仓库验收”，不是普通业务接入时必须使用的入口。