@imbingox/acex 0.3.0 → 0.4.0-beta.1

package/README.md

@@ -30,7 +30,7 @@ const book = client.market.getL1Book({
   symbol: "BTC/USDT:USDT",
 });
 const books = client.market.getL1Books("BTC/USDT:USDT");
-console.log(`bid=${book?.bidPrice.toFixed()} ask=${book?.askPrice.toFixed()}`);
+console.log(`bid=${book?.bidPrice} ask=${book?.askPrice}`);
 console.log(`venues=${books.length}`);
 console.log(`book freshness=${book?.status.freshness}`);
 
@@ -44,14 +44,14 @@ const funding = client.market.getFundingRate({
   symbol: "BTC/USDT:USDT",
 });
 const fundingRates = client.market.getFundingRates("BTC/USDT:USDT");
-console.log(`funding=${funding?.fundingRate.toFixed()}`);
+console.log(`funding=${funding?.fundingRate}`);
 console.log(`funding venues=${fundingRates.length}`);
 
 for await (const event of client.market.events.l1BookUpdates({
   venue: "binance",
   symbol: "BTC/USDT:USDT",
 })) {
-  console.log(event.snapshot.bidPrice.toFixed());
+  console.log(event.snapshot.bidPrice);
   break;
 }
 
@@ -113,11 +113,11 @@ const juplendRisk = client.account.getRiskSnapshot("jup-loop-a");
 const juplendBalances = client.account.getBalances("jup-loop-a");
 
 for (const balance of juplendBalances) {
-  console.log(balance.asset, balance.lending?.netAsset.toFixed());
+  console.log(balance.asset, balance.lending?.netAsset);
 }
 console.log({
-  binanceRiskRatio: binanceRisk?.riskRatio?.toFixed(),
-  juplendRiskRatio: juplendRisk?.riskRatio?.toFixed(),
+  binanceRiskRatio: binanceRisk?.riskRatio,
+  juplendRiskRatio: juplendRisk?.riskRatio,
 });
 
 await client.stop();
@@ -141,7 +141,7 @@ console.log(juplend.order.reason); // "read_only"
 const capabilities = client.listVenueCapabilities();
 ```
 
-价格、数量等输出字段统一是 `BigNumber`；`createOrder()` 的 `price` / `amount` 输入仍接受 decimal string。详见手册 [§3 核心概念](./docs/api.md#3-核心概念)。
+价格、数量等公共输出字段统一是 canonical decimal string（无科学计数法、不补尾零）；输入侧保持宽进严出，`createOrder()` 的 `price` / `amount` 是 decimal string，`DecimalInput` 仍接受 string / number / `BigNumber`。如需运算，使用 SDK re-export 的 `BigNumber`：`new BigNumber(field)`。详见手册 [§3 核心概念](./docs/api.md#3-核心概念)。
 
 ## 核心能力
 

package/docs/api.md

@@ -51,13 +51,13 @@ const book = client.market.getL1Book({
   venue: "binance",
   symbol: "BTC/USDT:USDT",
 });
-console.log(`bid=${book?.bidPrice.toFixed()} ask=${book?.askPrice.toFixed()}`);
+console.log(`bid=${book?.bidPrice} ask=${book?.askPrice}`);
 
 for await (const event of client.market.events.l1BookUpdates({
   venue: "binance",
   symbol: "BTC/USDT:USDT",
 })) {
-  console.log(event.snapshot.bidPrice.toFixed());
+  console.log(event.snapshot.bidPrice);
   break;
 }
 
@@ -114,8 +114,8 @@ await client.account.subscribeAccount({ accountId: "jup-loop-a" });
 const binanceRisk = client.account.getRiskSnapshot("main-binance");
 const juplendRisk = client.account.getRiskSnapshot("jup-loop-a");
 
-console.log(binanceRisk?.riskRatio?.toFixed());
-console.log(juplendRisk?.riskRatio?.toFixed());
+console.log(binanceRisk?.riskRatio);
+console.log(juplendRisk?.riskRatio);
 ```
 
 需要账户或订单能力时，在 `start()` 前后任意时刻 `registerAccount()`：
@@ -182,19 +182,19 @@ await client.market.subscribeL1Book({ venue, symbol });
 
 退订后 `activity` 变为 `"inactive"`，但最后一份快照仍可读——不要把它当实时值。
 
-### 3.5 BigNumber 约定
+### 3.5 Decimal string 约定
 
-输出侧的价格、数量、金额统一是 `BigNumber`（来自 [bignumber.js](https://github.com/MikeMcl/bignumber.js)，SDK 已 re-export）：
+输出侧的价格、数量、金额统一是 canonical 十进制 string：无损、无科学计数法、不补尾零。SDK 仍 re-export `BigNumber`（来自 [bignumber.js](https://github.com/MikeMcl/bignumber.js)）作为可选工具；需要运算时由调用方显式解析：
 
 ```ts
 import { BigNumber } from "@imbingox/acex";
 
 const book = client.market.getL1Book({ venue, symbol });
-const spread = book!.askPrice.minus(book!.bidPrice); // BigNumber
+const spread = new BigNumber(book!.askPrice).minus(new BigNumber(book!.bidPrice));
 console.log(spread.toFixed());
 ```
 
-**输入侧不对称**：`createOrder()` 的 `price` / `amount` 仍接受 decimal string。这是为了让调用方直接从交易所精度（`MarketDefinition.priceStep` / `amountStep`）做字符串格式化，不必先转 BigNumber 再转字符串。
+不要用 `parseFloat()` 解析输出字段，否则会退回 JS 浮点精度。输入侧保持宽进严出：`createOrder()` 的 `price` / `amount` 是 decimal string，`normalizeOrderInput()` 的 `DecimalInput` 仍接受 string / number / `BigNumber`，但公共输出一律是 canonical decimal string。
 
 ## 4. Client 生命周期
 
@@ -378,7 +378,7 @@ const allBtcPerp = client.market.getMarkets("BTC/USDT:USDT");
 
 `getMarkets(symbol)` 严格按完整统一 symbol 匹配。
 
-`MarketDefinition` 见 [§9](#9-数据类型参考)。价格/数量相关字段（`priceStep`、`amountStep`、`contractSize`、`minAmount`、`minNotional`）都是 `BigNumber`。
+`MarketDefinition` 见 [§9](#9-数据类型参考)。价格/数量相关字段（`priceStep`、`amountStep`、`contractSize`、`minAmount`、`minNotional`）都是 canonical decimal string；需要运算时用 `new BigNumber(field)` 自行解析。
 
 归一化下单价格和数量：
 
@@ -459,7 +459,7 @@ const book = client.market.getL1Book({
 });
 
 if (book) {
-  const spread = book.askPrice.minus(book.bidPrice);
+  const spread = new BigNumber(book.askPrice).minus(new BigNumber(book.bidPrice));
   console.log(`spread=${spread.toFixed()}`);
 }
 ```
@@ -471,7 +471,7 @@ for await (const event of client.market.events.l1BookUpdates({
   venue: "binance",
   symbol: "BTC/USDT:USDT",
 })) {
-  console.log(event.snapshot.bidPrice.toFixed());
+  console.log(event.snapshot.bidPrice);
 }
 ```
 
@@ -529,9 +529,9 @@ const funding = client.market.getFundingRate({
 });
 
 if (funding) {
-  console.log(funding.fundingRate.toFixed());
-  console.log(funding.markPrice?.toFixed());
-  console.log(funding.indexPrice?.toFixed());
+  console.log(funding.fundingRate);
+  console.log(funding.markPrice);
+  console.log(funding.indexPrice);
   console.log(funding.nextFundingTime);
   console.log(funding.status.freshness);
 }
@@ -544,7 +544,7 @@ for await (const event of client.market.events.fundingRateUpdates({
   venue: "binance",
   symbol: "BTC/USDT:USDT",
 })) {
-  console.log(event.snapshot.fundingRate.toFixed());
+  console.log(event.snapshot.fundingRate);
 }
 ```
 
@@ -638,7 +638,7 @@ const btcPosition = client.account.getPosition({
 const risk = client.account.getRiskSnapshot("main-binance");
 ```
 
-所有数量字段（`free` / `used` / `total` / `size` / `entryPrice` / `netEquity` / `riskEquity` / ...）都是 `BigNumber`。
+所有数量字段（`free` / `used` / `total` / `size` / `entryPrice` / `netEquity` / `riskEquity` / ...）都是 canonical decimal string；需要运算时用 `new BigNumber(field)` 自行解析。
 
 `RiskSnapshot.netEquity` 表示不含风控折算的净资产价值；`riskEquity` 表示抵押系数或清算阈值折算后的风控净权益。Binance 使用 `actualEquity` / `accountEquity` 映射这两个字段；Juplend 使用 `totalCollateralUsd - totalDebtUsd` / `Σ(suppliedValue × liquidationThreshold) - totalDebtUsd`。
 
@@ -652,13 +652,13 @@ for await (const event of client.account.events.updates({
 })) {
   switch (event.type) {
     case "balance.updated":
-      console.log(event.asset, event.snapshot.free.toFixed());
+      console.log(event.asset, event.snapshot.free);
       break;
     case "position.updated":
-      console.log(event.symbol, event.snapshot.size.toFixed());
+      console.log(event.symbol, event.snapshot.size);
       break;
     case "risk.updated":
-      console.log(event.snapshot.riskRatio?.toFixed());
+      console.log(event.snapshot.riskRatio);
       break;
     case "account.snapshot_replaced":
       // 私有链路重连/重对账后的全量替换
@@ -801,10 +801,10 @@ for await (const event of client.order.events.updates({
 })) {
   switch (event.type) {
     case "order.updated":
-      console.log("更新", event.snapshot.status, event.snapshot.filled.toFixed());
+      console.log("更新", event.snapshot.status, event.snapshot.filled);
       break;
     case "order.filled":
-      console.log("全部成交", event.snapshot.avgFillPrice?.toFixed());
+      console.log("全部成交", event.snapshot.avgFillPrice);
       break;
     case "order.canceled":
       console.log("已撤单");
@@ -1100,13 +1100,13 @@ interface MarketDefinition {
   contract: boolean;
   linear?: boolean;
   inverse?: boolean;
-  contractSize?: BigNumber;
+  contractSize?: string;
   pricePrecision: number;
   amountPrecision: number;
-  priceStep: BigNumber;
-  amountStep: BigNumber;
-  minAmount?: BigNumber;
-  minNotional?: BigNumber;
+  priceStep: string;
+  amountStep: string;
+  minAmount?: string;
+  minNotional?: string;
   expiry?: number;
   raw: Record<string, unknown>;
 }
@@ -1155,10 +1155,10 @@ interface MarketEventFilter {
 interface L1Book {
   venue: Venue;
   symbol: string;
-  bidPrice: BigNumber;
-  bidSize: BigNumber;
-  askPrice: BigNumber;
-  askSize: BigNumber;
+  bidPrice: string;
+  bidSize: string;
+  askPrice: string;
+  askSize: string;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -1169,10 +1169,10 @@ interface L1Book {
 interface FundingRateSnapshot {
   venue: Venue;
   symbol: string;
-  fundingRate: BigNumber;
+  fundingRate: string;
   nextFundingTime?: number;
-  markPrice?: BigNumber;
-  indexPrice?: BigNumber;
+  markPrice?: string;
+  indexPrice?: string;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -1210,9 +1210,9 @@ interface BalanceSnapshot {
   accountId: string;
   venue: Venue;
   asset: string;
-  free: BigNumber;
-  used: BigNumber;
-  total: BigNumber;
+  free: string;
+  used: string;
+  total: string;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -1221,12 +1221,12 @@ interface BalanceSnapshot {
 }
 
 interface LendingBalanceFacet {
-  supplied: BigNumber;
-  borrowed: BigNumber;
-  interest: BigNumber;
-  netAsset: BigNumber;
-  supplyAPY?: BigNumber;
-  borrowAPY?: BigNumber;
+  supplied: string;
+  borrowed: string;
+  interest: string;
+  netAsset: string;
+  supplyAPY?: string;
+  borrowAPY?: string;
 }
 
 interface PositionSnapshot {
@@ -1234,12 +1234,12 @@ interface PositionSnapshot {
   venue: Venue;
   symbol: string;
   side: PositionSide;
-  size: BigNumber;
-  entryPrice?: BigNumber;
-  markPrice?: BigNumber;
-  unrealizedPnl?: BigNumber;
-  leverage?: BigNumber;
-  liquidationPrice?: BigNumber;
+  size: string;
+  entryPrice?: string;
+  markPrice?: string;
+  unrealizedPnl?: string;
+  leverage?: string;
+  liquidationPrice?: string;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -1249,12 +1249,12 @@ interface PositionSnapshot {
 interface RiskSnapshot {
   accountId: string;
   venue: Venue;
-  netEquity?: BigNumber;
-  riskEquity?: BigNumber;
-  riskRatio?: BigNumber;
-  riskLeverage?: BigNumber;
-  initialMargin?: BigNumber;
-  maintenanceMargin?: BigNumber;
+  netEquity?: string;
+  riskEquity?: string;
+  riskRatio?: string;
+  riskLeverage?: string;
+  initialMargin?: string;
+  maintenanceMargin?: string;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;
@@ -1263,12 +1263,12 @@ interface RiskSnapshot {
 }
 
 interface LendingRiskFacet {
-  marginLevel?: BigNumber;
-  healthFactor?: BigNumber;
-  ltv?: BigNumber;
-  liquidationThreshold?: BigNumber;
-  totalCollateralUSD?: BigNumber;
-  totalDebtUSD?: BigNumber;
+  marginLevel?: string;
+  healthFactor?: string;
+  ltv?: string;
+  liquidationThreshold?: string;
+  totalCollateralUSD?: string;
+  totalDebtUSD?: string;
 }
 
 interface AccountSnapshot {
@@ -1350,14 +1350,14 @@ interface OrderSnapshot {
   side: OrderSide;
   type: string;              // 交易所原始 type 字符串
   status: OrderStatus;
-  price?: BigNumber;
-  triggerPrice?: BigNumber;
-  amount: BigNumber;
-  filled: BigNumber;
-  remaining?: BigNumber;
+  price?: string;
+  triggerPrice?: string;
+  amount: string;
+  filled: string;
+  remaining?: string;
   reduceOnly?: boolean;
   positionSide?: PositionSide;
-  avgFillPrice?: BigNumber;
+  avgFillPrice?: string;
   exchangeTs?: number;
   receivedAt: number;
   updatedAt: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.3.0",
+  "version": "0.4.0-beta.1",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

package/src/adapters/binance/adapter.ts

@@ -1,3 +1,4 @@
+import { SubscriptionMultiplexer } from "../../internal/subscription-multiplexer.ts";
 import type {
   MarketDefinition,
   VenueMarketCapabilities,
@@ -10,12 +11,34 @@ import type {
   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";
+import {
+  type BinanceStreamDescriptor,
+  type BinanceStreamMessage,
+  type BinanceStreamPayload,
+  BinanceStreamProtocol,
+} from "./stream-protocol.ts";
+
+const BINANCE_CONTROL_FRAME_MAX_PER_SEC = 5;
+// Binance allows up to 1024 streams per connection; keep a conservative pool cap.
+const BINANCE_MAX_SUBSCRIPTIONS_PER_CONNECTION = 200;
+
+type BinanceMarketMultiplexer = SubscriptionMultiplexer<
+  BinanceStreamMessage,
+  BinanceStreamDescriptor,
+  BinanceStreamPayload
+>;
+
+interface BinanceMultiplexerConfig {
+  readonly initialMessageTimeoutMs: number;
+  readonly staleAfterMs: number;
+  readonly reconnectDelayMs: number;
+  readonly reconnectMaxDelayMs: number;
+  readonly now?: () => number;
+}
 
 export class BinanceMarketAdapter implements MarketAdapter {
   readonly venue = "binance" as const;
@@ -27,6 +50,8 @@ export class BinanceMarketAdapter implements MarketAdapter {
   };
 
   private readonly definitions = new Map<string, BinanceMarketDefinition>();
+  private multiplexer: BinanceMarketMultiplexer | undefined;
+  private multiplexerConfig: BinanceMultiplexerConfig | undefined;
 
   async loadMarkets(): Promise<MarketDefinition[]> {
     const markets = await loadBinanceMarkets();
@@ -49,18 +74,38 @@ export class BinanceMarketAdapter implements MarketAdapter {
       throw new Error(`Unknown Binance market: ${market.symbol}`);
     }
 
-    return subscribeBinanceBookTicker(
-      binanceMarket,
+    const handle = this.getMultiplexer(options).subscribe(
+      {
+        channel: "l1book",
+        market: binanceMarket,
+      },
       {
-        onBookTicker(update) {
-          callbacks.onUpdate(update);
+        onPayload(payload, receivedAt) {
+          if (payload.channel !== "l1book") {
+            return;
+          }
+
+          callbacks.onUpdate({
+            bidPrice: payload.bidPrice,
+            bidSize: payload.bidSize,
+            askPrice: payload.askPrice,
+            askSize: payload.askSize,
+            exchangeTs: payload.exchangeTs,
+            receivedAt,
+          });
         },
         onFreshnessChange: callbacks.onFreshnessChange,
         onDisconnected: callbacks.onDisconnected,
         onError: callbacks.onError,
       },
-      options,
     );
+
+    return {
+      ready: handle.ready,
+      close(): void {
+        handle.close();
+      },
+    };
   }
 
   createFundingRateStream(
@@ -73,17 +118,91 @@ export class BinanceMarketAdapter implements MarketAdapter {
       throw new Error(`Unknown Binance market: ${market.symbol}`);
     }
 
-    return subscribeBinanceMarkPrice(
-      binanceMarket,
+    const handle = this.getMultiplexer(options).subscribe(
       {
-        onFundingRate(update) {
-          callbacks.onUpdate(update);
+        channel: "fundingRate",
+        market: binanceMarket,
+      },
+      {
+        onPayload(payload, receivedAt) {
+          if (payload.channel !== "fundingRate") {
+            return;
+          }
+
+          callbacks.onUpdate({
+            fundingRate: payload.fundingRate,
+            nextFundingTime: payload.nextFundingTime,
+            markPrice: payload.markPrice,
+            indexPrice: payload.indexPrice,
+            exchangeTs: payload.exchangeTs,
+            receivedAt,
+          });
         },
         onFreshnessChange: callbacks.onFreshnessChange,
         onDisconnected: callbacks.onDisconnected,
         onError: callbacks.onError,
       },
-      options,
     );
+
+    return {
+      ready: handle.ready,
+      close(): void {
+        handle.close();
+      },
+    };
+  }
+
+  private getMultiplexer(
+    options: L1BookStreamOptions | FundingRateStreamOptions,
+  ): BinanceMarketMultiplexer {
+    const config: BinanceMultiplexerConfig = {
+      initialMessageTimeoutMs: options.initialMessageTimeoutMs,
+      staleAfterMs: options.staleAfterMs,
+      reconnectDelayMs: options.reconnectDelayMs,
+      reconnectMaxDelayMs: options.reconnectMaxDelayMs,
+      now: options.now,
+    };
+
+    if (!this.multiplexer) {
+      this.multiplexer = new SubscriptionMultiplexer(
+        new BinanceStreamProtocol(),
+        {
+          initialMessageTimeoutMs: config.initialMessageTimeoutMs,
+          staleAfterMs: config.staleAfterMs,
+          reconnectDelayMs: config.reconnectDelayMs,
+          reconnectMaxDelayMs: config.reconnectMaxDelayMs,
+          controlFrameMaxPerSec: BINANCE_CONTROL_FRAME_MAX_PER_SEC,
+          maxSubscriptionsPerConnection:
+            BINANCE_MAX_SUBSCRIPTIONS_PER_CONNECTION,
+          now: config.now,
+        },
+      );
+      this.multiplexerConfig = config;
+      return this.multiplexer;
+    }
+
+    if (
+      !this.multiplexerConfig ||
+      !sameMultiplexerConfig(config, this.multiplexerConfig)
+    ) {
+      throw new Error(
+        "Binance market stream options differ from the active multiplexer; create a new adapter instance for different stream timing options",
+      );
+    }
+
+    return this.multiplexer;
   }
 }
+
+function sameMultiplexerConfig(
+  left: BinanceMultiplexerConfig,
+  right: BinanceMultiplexerConfig,
+): boolean {
+  return (
+    left.initialMessageTimeoutMs === right.initialMessageTimeoutMs &&
+    left.staleAfterMs === right.staleAfterMs &&
+    left.reconnectDelayMs === right.reconnectDelayMs &&
+    left.reconnectMaxDelayMs === right.reconnectMaxDelayMs &&
+    left.now === right.now
+  );
+}

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

@@ -1,4 +1,4 @@
-import BigNumber from "bignumber.js";
+import { toCanonical } from "../../internal/decimal.ts";
 import type { MarketDefinition, MarketType } from "../../types/index.ts";
 
 type FetchLike = typeof fetch;
@@ -146,12 +146,12 @@ function normalizeSpotSymbol(
     contract: false,
     pricePrecision: precisionFromStep(priceStep),
     amountPrecision: precisionFromStep(amountStep),
-    priceStep: new BigNumber(priceStep),
-    amountStep: new BigNumber(amountStep),
+    priceStep: toCanonical(priceStep),
+    amountStep: toCanonical(amountStep),
     minAmount: lotSizeFilter?.minQty
-      ? new BigNumber(lotSizeFilter.minQty)
+      ? toCanonical(lotSizeFilter.minQty)
       : undefined,
-    minNotional: notionalValue ? new BigNumber(notionalValue) : undefined,
+    minNotional: notionalValue ? toCanonical(notionalValue) : undefined,
     raw: toRecord(symbol),
   };
 }
@@ -198,15 +198,15 @@ function normalizeDerivativesSymbol(
     contract: true,
     linear: family === "usdm",
     inverse: family === "coinm",
-    contractSize: contractSize ? new BigNumber(contractSize) : undefined,
+    contractSize: contractSize ? toCanonical(contractSize) : undefined,
     pricePrecision: precisionFromStep(priceStep),
     amountPrecision: precisionFromStep(amountStep),
-    priceStep: new BigNumber(priceStep),
-    amountStep: new BigNumber(amountStep),
+    priceStep: toCanonical(priceStep),
+    amountStep: toCanonical(amountStep),
     minAmount: lotSizeFilter?.minQty
-      ? new BigNumber(lotSizeFilter.minQty)
+      ? toCanonical(lotSizeFilter.minQty)
       : undefined,
-    minNotional: notionalValue ? new BigNumber(notionalValue) : undefined,
+    minNotional: notionalValue ? toCanonical(notionalValue) : undefined,
     expiry: type === "future" ? symbol.deliveryDate : undefined,
     raw: toRecord(symbol),
   };