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

package/README.md

@@ -1,23 +1,598 @@
 # @imbingox/acex
 
-To install dependencies:
+`acex` 是一个面向交易场景的状态型 SDK。调用方只需要持有一个 `AcexClient`，就可以通过统一的 `market`、`account`、`order` manager 读取最新快照、订阅增量事件、观察健康状态，而不需要自己维护本地缓存、ready barrier 或 websocket 生命周期。
+
+## 安装
 
 ```bash
-bun install
+bun add @imbingox/acex
 ```
 
-To run checks:
+## 完整用法
 
-```bash
-bun run lint
-bun run type-check
-bun run test
+### 1. 创建 client
+
+```ts
+import { createClient } from "@imbingox/acex";
+// SDK re-exports BigNumber，调用方无需单独安装 bignumber.js
+import { BigNumber } from "@imbingox/acex";
+
+const client = createClient();
+```
+
+`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);
+}
+```
+
+也可以手动控制迭代器：
+
+```ts
+const iterator = client.market.events
+  .l1BookUpdates({ exchange: "binance", symbol: "BTC/USDT:USDT" })
+  [Symbol.asyncIterator]();
+
+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"
+}
 ```
 
-To run the current entry:
+#### 退订
+
+```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()
+```
+
+## 核心语义
+
+| 概念 | 说明 |
+|---|---|
+| `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**（`okx`、`bybit`、`gate` 仅类型定义）
+- 真实落地的数据链路只有 Binance **L1 Book**
+- `fundingRate` 接口已暴露，但当前是占位快照
+- `account` / `order` 当前是占位实现，不是完整真实私有流
+- `CreateClientOptions` 中 `sandbox`、`logger`、`logLevel` 仍是预留位
+
+## 仓库内开发
 
 ```bash
-bun run index.ts
+bun install
+bun run lint
+bun run type-check
+bun test
 ```
 
-This project was created using `bun init` in bun v1.3.9. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+更完整的公开接口设计说明见 [docs/sdk-public-api.md](./docs/sdk-public-api.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "module": "index.ts",
   "type": "module",
@@ -21,5 +21,9 @@
     "@biomejs/biome": "^2.4.10",
     "@types/bun": "latest",
     "typescript": "^6.0.2"
+  },
+  "dependencies": {
+    "@mindfoldhq/trellis": "^0.4.0",
+    "bignumber.js": "^11.0.0"
   }
 }

package/src/adapters/binance/market-catalog.ts

@@ -1,3 +1,4 @@
+import BigNumber from "bignumber.js";
 import type { MarketDefinition, MarketType } from "../../types/index.ts";
 
 type FetchLike = typeof fetch;
@@ -131,6 +132,7 @@ function normalizeSpotSymbol(
     getFilter(symbol.filters, "MIN_NOTIONAL");
   const priceStep = normalizeStep(priceFilter?.tickSize);
   const amountStep = normalizeStep(lotSizeFilter?.stepSize);
+  const notionalValue = notionalFilter?.minNotional ?? notionalFilter?.notional;
 
   return {
     exchange: "binance",
@@ -144,10 +146,12 @@ function normalizeSpotSymbol(
     contract: false,
     pricePrecision: precisionFromStep(priceStep),
     amountPrecision: precisionFromStep(amountStep),
-    priceStep,
-    amountStep,
-    minAmount: lotSizeFilter?.minQty,
-    minNotional: notionalFilter?.minNotional ?? notionalFilter?.notional,
+    priceStep: new BigNumber(priceStep),
+    amountStep: new BigNumber(amountStep),
+    minAmount: lotSizeFilter?.minQty
+      ? new BigNumber(lotSizeFilter.minQty)
+      : undefined,
+    minNotional: notionalValue ? new BigNumber(notionalValue) : undefined,
     raw: toRecord(symbol),
   };
 }
@@ -173,6 +177,7 @@ function normalizeDerivativesSymbol(
       : family === "usdm"
         ? "1"
         : undefined;
+  const notionalValue = notionalFilter?.minNotional ?? notionalFilter?.notional;
 
   return {
     exchange: "binance",
@@ -193,13 +198,15 @@ function normalizeDerivativesSymbol(
     contract: true,
     linear: family === "usdm",
     inverse: family === "coinm",
-    contractSize,
+    contractSize: contractSize ? new BigNumber(contractSize) : undefined,
     pricePrecision: precisionFromStep(priceStep),
     amountPrecision: precisionFromStep(amountStep),
-    priceStep,
-    amountStep,
-    minAmount: lotSizeFilter?.minQty,
-    minNotional: notionalFilter?.minNotional ?? notionalFilter?.notional,
+    priceStep: new BigNumber(priceStep),
+    amountStep: new BigNumber(amountStep),
+    minAmount: lotSizeFilter?.minQty
+      ? new BigNumber(lotSizeFilter.minQty)
+      : undefined,
+    minNotional: notionalValue ? new BigNumber(notionalValue) : undefined,
     expiry: type === "future" ? symbol.deliveryDate : undefined,
     raw: toRecord(symbol),
   };

package/src/index.ts

@@ -1,3 +1,4 @@
+export { BigNumber } from "bignumber.js";
 export { createClient } from "./client/create-client.ts";
 export type { AcexErrorCode } from "./errors.ts";
 export { AcexError } from "./errors.ts";

package/src/managers/market-manager.ts

@@ -1,3 +1,4 @@
+import BigNumber from "bignumber.js";
 import type {
   L1BookStreamCallbacks,
   L1BookStreamOptions,
@@ -208,13 +209,23 @@ export class MarketManagerImpl
     this.updateActivity(record);
   }
 
-  getMarket(symbol: string): MarketDefinition | undefined {
-    const market = this.definitions.get(symbol);
+  getMarket(exchange: Exchange, symbol: string): MarketDefinition | undefined {
+    const market = this.definitions.get(marketKey({ exchange, symbol }));
     return market ? cloneMarketDefinition(market) : undefined;
   }
 
-  listMarkets(): MarketDefinition[] {
+  findMarkets(symbol: string): MarketDefinition[] {
     return [...this.definitions.values()]
+      .filter((market) => market.symbol === symbol)
+      .map((market) => cloneMarketDefinition(market));
+  }
+
+  listMarkets(exchange?: Exchange): MarketDefinition[] {
+    const values = [...this.definitions.values()];
+    const filtered = exchange
+      ? values.filter((market) => market.exchange === exchange)
+      : values;
+    return filtered
       .sort((left, right) => left.symbol.localeCompare(right.symbol))
       .map((market) => cloneMarketDefinition(market));
   }
@@ -319,7 +330,7 @@ export class MarketManagerImpl
       this.definitions.clear();
 
       for (const market of markets) {
-        this.definitions.set(market.symbol, market);
+        this.definitions.set(marketKey(market), market);
       }
     } catch (error) {
       const wrapped = new AcexError(
@@ -344,7 +355,7 @@ export class MarketManagerImpl
     this.assertSupportedExchange(input.exchange);
     await this.loadMarketCatalog();
 
-    const market = this.definitions.get(input.symbol);
+    const market = this.definitions.get(marketKey(input));
     if (!market) {
       throw this.createError(
         "MARKET_NOT_FOUND",
@@ -517,10 +528,10 @@ export class MarketManagerImpl
     return {
       exchange,
       symbol,
-      bidPrice: input.bidPrice,
-      bidSize: input.bidSize,
-      askPrice: input.askPrice,
-      askSize: input.askSize,
+      bidPrice: new BigNumber(input.bidPrice),
+      bidSize: new BigNumber(input.bidSize),
+      askPrice: new BigNumber(input.askPrice),
+      askSize: new BigNumber(input.askSize),
       exchangeTs: input.exchangeTs,
       receivedAt: input.receivedAt,
       updatedAt: input.receivedAt,
@@ -538,7 +549,7 @@ export class MarketManagerImpl
     return {
       exchange,
       symbol,
-      fundingRate: previous?.fundingRate ?? "0",
+      fundingRate: previous?.fundingRate ?? new BigNumber(0),
       nextFundingTime: previous?.nextFundingTime,
       markPrice: previous?.markPrice,
       indexPrice: previous?.indexPrice,

package/src/types/account.ts

@@ -1,3 +1,4 @@
+import type BigNumber from "bignumber.js";
 import type {
   Exchange,
   PrivateRuntimeStatus,
@@ -55,9 +56,9 @@ export interface BalanceSnapshot {
   accountId: string;
   exchange: Exchange;
   asset: string;
-  free: string;
-  used: string;
-  total: string;
+  free: BigNumber;
+  used: BigNumber;
+  total: BigNumber;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -69,12 +70,12 @@ export interface PositionSnapshot {
   exchange: Exchange;
   symbol: string;
   side: PositionSide;
-  size: string;
-  entryPrice?: string;
-  markPrice?: string;
-  unrealizedPnl?: string;
-  leverage?: string;
-  liquidationPrice?: string;
+  size: BigNumber;
+  entryPrice?: BigNumber;
+  markPrice?: BigNumber;
+  unrealizedPnl?: BigNumber;
+  leverage?: BigNumber;
+  liquidationPrice?: BigNumber;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -84,10 +85,10 @@ export interface PositionSnapshot {
 export interface RiskSnapshot {
   accountId: string;
   exchange: Exchange;
-  equity?: string;
-  marginRatio?: string;
-  initialMargin?: string;
-  maintenanceMargin?: string;
+  equity?: BigNumber;
+  marginRatio?: BigNumber;
+  initialMargin?: BigNumber;
+  maintenanceMargin?: BigNumber;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;

package/src/types/market.ts

@@ -1,3 +1,4 @@
+import type BigNumber from "bignumber.js";
 import type {
   Exchange,
   MarketFreshness,
@@ -18,13 +19,13 @@ export interface MarketDefinition {
   contract: boolean;
   linear?: boolean;
   inverse?: boolean;
-  contractSize?: string;
+  contractSize?: BigNumber;
   pricePrecision: number;
   amountPrecision: number;
-  priceStep: string;
-  amountStep: string;
-  minAmount?: string;
-  minNotional?: string;
+  priceStep: BigNumber;
+  amountStep: BigNumber;
+  minAmount?: BigNumber;
+  minNotional?: BigNumber;
   expiry?: number;
   raw: Record<string, unknown>;
 }
@@ -58,10 +59,10 @@ export interface MarketEventFilter {
 export interface L1Book {
   exchange: Exchange;
   symbol: string;
-  bidPrice: string;
-  bidSize: string;
-  askPrice: string;
-  askSize: string;
+  bidPrice: BigNumber;
+  bidSize: BigNumber;
+  askPrice: BigNumber;
+  askSize: BigNumber;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -71,10 +72,10 @@ export interface L1Book {
 export interface FundingRateSnapshot {
   exchange: Exchange;
   symbol: string;
-  fundingRate: string;
+  fundingRate: BigNumber;
   nextFundingTime?: number;
-  markPrice?: string;
-  indexPrice?: string;
+  markPrice?: BigNumber;
+  indexPrice?: BigNumber;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -128,8 +129,9 @@ export interface MarketManager {
   subscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;
   unsubscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;
 
-  getMarket(symbol: string): MarketDefinition | undefined;
-  listMarkets(): MarketDefinition[];
+  getMarket(exchange: Exchange, symbol: string): MarketDefinition | undefined;
+  findMarkets(symbol: string): MarketDefinition[];
+  listMarkets(exchange?: Exchange): MarketDefinition[];
   getL1Book(key: MarketKeyInput): L1Book | undefined;
   getFundingRate(key: MarketKeyInput): FundingRateSnapshot | undefined;
   getMarketStatus(key: MarketKeyInput): MarketDataStatus | undefined;

package/src/types/order.ts

@@ -1,3 +1,4 @@
+import type BigNumber from "bignumber.js";
 import type { PositionSide } from "./account.ts";
 import type {
   Exchange,
@@ -69,14 +70,14 @@ export interface OrderSnapshot {
   side: OrderSide;
   type: string;
   status: OrderStatus;
-  price?: string;
-  triggerPrice?: string;
-  amount: string;
-  filled: string;
-  remaining?: string;
+  price?: BigNumber;
+  triggerPrice?: BigNumber;
+  amount: BigNumber;
+  filled: BigNumber;
+  remaining?: BigNumber;
   reduceOnly?: boolean;
   positionSide?: PositionSide;
-  avgFillPrice?: string;
+  avgFillPrice?: BigNumber;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;