@imbingox/acex 0.2.0 → 0.3.0-beta.1

package/README.md

@@ -29,7 +29,9 @@ 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({
@@ -41,7 +43,9 @@ 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",
@@ -121,6 +125,26 @@ bun run type-check
 bun run test
 ```
 
+### 测试分层
+
+默认 `bun run test` 只运行快速、确定性的本地测试，不访问真实交易所：
+
+| 命令 | 覆盖范围 | 是否进入默认 CI |
+|------|----------|----------------|
+| `bun run test:unit` | `tests/unit/`，底层工具和无全局副作用的单元测试 | 是 |
+| `bun run test:integration` | `tests/integration/`，fake REST + fake WebSocket 的 SDK 跨层集成测试 | 是 |
+| `bun run test` | `test:unit` + `test:integration` | 是 |
+| `bun run test:soak` | `tests/soak/`，60 秒级稳定性/连续更新测试 | 否 |
+| `bun run test:all` | 默认快速测试 + soak 测试 | 否 |
+
+测试 support 结构：
+
+- `tests/support/test-utils.ts`：通用 fake WebSocket、事件等待、Response helper 和全局清理。
+- `tests/support/exchanges/binance.ts`：Binance 专用 REST/WS fixtures 与 installer。
+- 新增交易所时，优先新增 `tests/support/exchanges/<exchange>.ts`，复用通用 helper，避免把交易所 payload 写进通用测试工具。
+
+GitHub Actions 的 `CI` workflow 会在 PR 和 `main` push 时运行 lint、type-check、unit、integration；release workflow 继续复用 `bun run test`，不会执行 soak/live。
+
 ### 真实环境 smoke / soak 脚本
 
 不进默认 `bun run test`，单独执行：
@@ -141,7 +165,7 @@ bun run test:live:order:soak
 
 覆盖内容：
 
-- `market`：`loadMarkets()`、`subscribeL1Book()`、`subscribeFundingRate()`、`getL1Book()` / `getFundingRate()`、对应事件流和可选断线重连（`--disconnect-target funding` 可单独验证资金费率重连）
+- `market`：`loadMarkets()`、`subscribeL1Book()`、`subscribeFundingRate()`、`getL1Book()` / `getL1Books()`、`getFundingRate()` / `getFundingRates()`、对应事件流和可选断线重连（`--disconnect-target funding` 可单独验证资金费率重连）
 - `account`：Binance PAPI UM 账户 bootstrap、余额/仓位/风险投影、private stream 更新和可选重连
 - `order`：open orders bootstrap、`subscribeOrders()`、订单事件投影和可选重连
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.2.0",
+  "version": "0.3.0-beta.1",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "lint:fix": "biome check --write .",
     "release": "changeset publish",
     "type-check": "tsc --noEmit",
-    "test": "bun test --max-concurrency=1",
+    "test": "bun test --max-concurrency=1 tests/unit tests/integration",
     "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",
@@ -36,7 +36,11 @@
     "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"
+    "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",
+    "test:unit": "bun test tests/unit",
+    "test:integration": "bun test --max-concurrency=1 tests/integration",
+    "test:soak": "bun test --max-concurrency=1 tests/soak",
+    "test:all": "bun run test && bun run test:soak"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",

package/src/adapters/binance/mark-price.ts

@@ -43,13 +43,13 @@ interface BinanceMarkPriceMessage {
   T?: number;
 }
 
-const BINANCE_USDM_WS_BASE_URL = "wss://fstream.binance.com/ws";
+const BINANCE_USDM_MARKET_WS_BASE_URL = "wss://fstream.binance.com/market/ws";
 const BINANCE_COINM_WS_BASE_URL = "wss://dstream.binance.com/ws";
 
 function getWsBaseUrl(market: BinanceMarketDefinition): string {
   switch (market.family) {
     case "usdm":
-      return BINANCE_USDM_WS_BASE_URL;
+      return BINANCE_USDM_MARKET_WS_BASE_URL;
     case "coinm":
       return BINANCE_COINM_WS_BASE_URL;
     case "spot":
@@ -60,7 +60,7 @@ function getWsBaseUrl(market: BinanceMarketDefinition): string {
 }
 
 function buildMarkPriceUrl(market: BinanceMarketDefinition): string {
-  return `${getWsBaseUrl(market)}/${market.id.toLowerCase()}@markPrice@1s`;
+  return `${getWsBaseUrl(market)}/${market.id.toLowerCase()}@markPrice`;
 }
 
 function parseMarkPriceMessage(

package/src/adapters/binance/private-adapter.ts

@@ -551,7 +551,12 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         type: encodeOrderType(request.type),
         quantity: request.amount,
         price: request.price,
-        timeInForce: request.type === "limit" ? "GTC" : undefined,
+        timeInForce:
+          request.type === "limit"
+            ? request.postOnly === true
+              ? "GTX"
+              : "GTC"
+            : undefined,
         newClientOrderId: request.clientOrderId,
         reduceOnly:
           request.reduceOnly === undefined

package/src/adapters/types.ts

@@ -154,6 +154,7 @@ export interface CreateOrderRequest {
   type: CreateOrderType;
   amount: string;
   price?: string;
+  postOnly?: boolean;
   clientOrderId?: string;
   reduceOnly?: boolean;
   positionSide?: PositionSide;

package/src/client/runtime.ts

@@ -297,6 +297,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
       type: input.type,
       amount: input.amount,
       price: input.type === "limit" ? input.price : undefined,
+      postOnly: input.type === "limit" ? input.postOnly : undefined,
       clientOrderId: input.clientOrderId,
       reduceOnly: input.reduceOnly,
       positionSide: input.positionSide,

package/src/managers/market-manager.ts

@@ -31,6 +31,8 @@ import type {
   MarketKeyInput,
   MarketManager,
   MarketStatusChangedEvent,
+  NormalizedOrderInput,
+  NormalizeOrderInputInput,
   SubscribeFundingRateInput,
   SubscribeL1BookInput,
   SubscriptionActivity,
@@ -91,6 +93,17 @@ function cloneMarketDefinition(definition: MarketDefinition): MarketDefinition {
   return { ...definition, raw: { ...definition.raw } };
 }
 
+function floorToStep(value: BigNumber, step: BigNumber): BigNumber {
+  if (step.isLessThanOrEqualTo(0)) {
+    return value;
+  }
+  return value.dividedToIntegerBy(step).multipliedBy(step);
+}
+
+function normalizeDecimalInput(value: BigNumber): string {
+  return value.isFinite() ? value.toFixed() : value.toString();
+}
+
 export class MarketManagerImpl
   implements MarketManager, ManagerLifecycle, HealthReporter<MarketDataStatus>
 {
@@ -224,9 +237,10 @@ export class MarketManagerImpl
     return market ? cloneMarketDefinition(market) : undefined;
   }
 
-  findMarkets(symbol: string): MarketDefinition[] {
+  getMarkets(symbol: string): MarketDefinition[] {
     return [...this.definitions.values()]
       .filter((market) => market.symbol === symbol)
+      .sort((left, right) => left.exchange.localeCompare(right.exchange))
       .map((market) => cloneMarketDefinition(market));
   }
 
@@ -240,16 +254,96 @@ export class MarketManagerImpl
       .map((market) => cloneMarketDefinition(market));
   }
 
+  normalizeOrderInput(input: NormalizeOrderInputInput): NormalizedOrderInput {
+    const market = this.resolveLoadedMarket(input);
+    const rawPrice = new BigNumber(input.price);
+    const rawAmount = new BigNumber(input.amount);
+    const price = floorToStep(rawPrice, market.priceStep);
+    const amount = floorToStep(rawAmount, market.amountStep);
+
+    const normalized: NormalizedOrderInput = {
+      price: normalizeDecimalInput(price),
+      amount: normalizeDecimalInput(amount),
+      rawPrice: normalizeDecimalInput(rawPrice),
+      rawAmount: normalizeDecimalInput(rawAmount),
+      adjusted: !price.isEqualTo(rawPrice) || !amount.isEqualTo(rawAmount),
+      accepted: true,
+      priceStep: market.priceStep.toFixed(),
+      amountStep: market.amountStep.toFixed(),
+      minAmount: market.minAmount?.toFixed(),
+      minNotional: market.minNotional?.toFixed(),
+    };
+
+    if (!price.isFinite() || price.isLessThanOrEqualTo(0)) {
+      return {
+        ...normalized,
+        accepted: false,
+        rejectReason: "price_not_positive",
+      };
+    }
+
+    if (!amount.isFinite() || amount.isLessThanOrEqualTo(0)) {
+      return {
+        ...normalized,
+        accepted: false,
+        rejectReason: "amount_not_positive",
+      };
+    }
+
+    if (market.minAmount && amount.isLessThan(market.minAmount)) {
+      return {
+        ...normalized,
+        accepted: false,
+        rejectReason: "amount_below_min",
+      };
+    }
+
+    if (market.minNotional) {
+      const notional = amount.multipliedBy(price);
+      if (notional.isLessThan(market.minNotional)) {
+        return {
+          ...normalized,
+          accepted: false,
+          rejectReason: "notional_below_min",
+        };
+      }
+    }
+
+    return normalized;
+  }
+
   getL1Book(key: MarketKeyInput): L1Book | undefined {
     const book = this.records.get(marketKey(key))?.l1Book;
     return book ? cloneL1Book(book) : undefined;
   }
 
+  getL1Books(symbol: string): L1Book[] {
+    return [...this.records.values()]
+      .filter(
+        (record): record is MarketRecord & { l1Book: L1Book } =>
+          record.symbol === symbol && Boolean(record.l1Book),
+      )
+      .map((record) => cloneL1Book(record.l1Book))
+      .sort((left, right) => left.exchange.localeCompare(right.exchange));
+  }
+
   getFundingRate(key: MarketKeyInput): FundingRateSnapshot | undefined {
     const fundingRate = this.records.get(marketKey(key))?.fundingRate;
     return fundingRate ? cloneFundingRate(fundingRate) : undefined;
   }
 
+  getFundingRates(symbol: string): FundingRateSnapshot[] {
+    return [...this.records.values()]
+      .filter(
+        (
+          record,
+        ): record is MarketRecord & { fundingRate: FundingRateSnapshot } =>
+          record.symbol === symbol && Boolean(record.fundingRate),
+      )
+      .map((record) => cloneFundingRate(record.fundingRate))
+      .sort((left, right) => left.exchange.localeCompare(right.exchange));
+  }
+
   getMarketStatus(key: MarketKeyInput): MarketDataStatus | undefined {
     const status = this.records.get(marketKey(key))?.status;
     return status ? cloneMarketStatus(status) : undefined;
@@ -391,6 +485,20 @@ export class MarketManagerImpl
     return market;
   }
 
+  private resolveLoadedMarket(input: MarketKeyInput): MarketDefinition {
+    const market = this.definitions.get(marketKey(input));
+    if (!market) {
+      throw this.createError(
+        "MARKET_NOT_FOUND",
+        `Unknown market symbol: ${input.symbol}`,
+        { exchange: input.exchange, symbol: input.symbol },
+        "market",
+      );
+    }
+
+    return market;
+  }
+
   private assertSupportedExchange(exchange: Exchange): void {
     if (exchange === this.adapter.exchange) {
       return;

package/src/types/market.ts

@@ -57,6 +57,33 @@ export interface MarketKeyInput {
   symbol: string;
 }
 
+export type DecimalInput = string | number | BigNumber;
+
+export type NormalizeOrderInputRejectReason =
+  | "price_not_positive"
+  | "amount_not_positive"
+  | "amount_below_min"
+  | "notional_below_min";
+
+export interface NormalizeOrderInputInput extends MarketKeyInput {
+  price: DecimalInput;
+  amount: DecimalInput;
+}
+
+export interface NormalizedOrderInput {
+  price: string;
+  amount: string;
+  rawPrice: string;
+  rawAmount: string;
+  adjusted: boolean;
+  accepted: boolean;
+  rejectReason?: NormalizeOrderInputRejectReason;
+  priceStep: string;
+  amountStep: string;
+  minAmount?: string;
+  minNotional?: string;
+}
+
 export interface SubscribeL1BookInput extends MarketKeyInput {}
 
 export interface SubscribeFundingRateInput extends MarketKeyInput {}
@@ -142,9 +169,12 @@ export interface MarketManager {
   unsubscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;
 
   getMarket(exchange: Exchange, symbol: string): MarketDefinition | undefined;
-  findMarkets(symbol: string): MarketDefinition[];
+  getMarkets(symbol: string): MarketDefinition[];
   listMarkets(exchange?: Exchange): MarketDefinition[];
+  normalizeOrderInput(input: NormalizeOrderInputInput): NormalizedOrderInput;
   getL1Book(key: MarketKeyInput): L1Book | undefined;
+  getL1Books(symbol: string): L1Book[];
   getFundingRate(key: MarketKeyInput): FundingRateSnapshot | undefined;
+  getFundingRates(symbol: string): FundingRateSnapshot[];
   getMarketStatus(key: MarketKeyInput): MarketDataStatus | undefined;
 }

package/src/types/order.ts

@@ -66,6 +66,7 @@ interface CreateOrderInputBase {
 export interface CreateLimitOrderInput extends CreateOrderInputBase {
   type: "limit";
   price: string;
+  postOnly?: boolean;
 }
 
 export interface CreateMarketOrderInput extends CreateOrderInputBase {