@imbingox/acex 0.3.0-beta.3 → 0.3.0-beta.4

package/README.md

@@ -60,11 +60,14 @@ await client.stop();
 
 ### 同一个 client 同时使用 Binance + Juplend
 
-`createClient({ account: { juplend: { pollIntervalMs } } })` 只是配置 Juplend 账户的 polling 间隔，不代表这个 client 只能注册 Juplend。一个 `AcexClient` 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户，用同一个 `AccountManager` 对比风险值。
+`createClient({ account: { binance: { riskPollIntervalMs }, juplend: { pollIntervalMs } } })` 只是分别配置 Binance 风险/仓位校准间隔和 Juplend 账户 polling 间隔，不代表这个 client 只能注册某个 venue。一个 `AcexClient` 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户，用同一个 `AccountManager` 对比风险值。
 
 ```ts
 const client = createClient({
   account: {
+    binance: {
+      riskPollIntervalMs: 5_000,
+    },
     juplend: {
       pollIntervalMs: 30_000,
     },

package/docs/api.md

@@ -64,11 +64,14 @@ for await (const event of client.market.events.l1BookUpdates({
 await client.stop();
 ```
 
-同一个 client 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户。`account.juplend.pollIntervalMs` 只是 Juplend polling 配置，不会把 client 限定为 Juplend 专用：
+同一个 client 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户。`account.binance.riskPollIntervalMs` 只配置 Binance 风险/仓位校准间隔；`account.juplend.pollIntervalMs` 只配置 Juplend polling 间隔，不会把 client 限定为某个 venue：
 
 ```ts
 const client = createClient({
   account: {
+    binance: {
+      riskPollIntervalMs: 5_000,
+    },
     juplend: {
       pollIntervalMs: 30_000,
     },
@@ -208,6 +211,9 @@ const client = createClient({
     streamReconnectDelayMs: 1_000,
     streamReconnectMaxDelayMs: 10_000,
     listenKeyKeepAliveMs: 30 * 60_000,
+    binance: {
+      riskPollIntervalMs: 5_000,
+    },
     juplend: {
       pollIntervalMs: 30_000,
     },
@@ -902,9 +908,6 @@ type PrivateRuntimeStatus =
 type PrivateRuntimeReason =
   | "credentials_missing" | "auth_failed" | "http_failed" | "rate_limited"
   | "ws_disconnected" | "heartbeat_timeout" | "reconciling";
-type PrivateRuntimeReason =
-  | "credentials_missing" | "auth_failed"
-  | "ws_disconnected" | "heartbeat_timeout" | "reconciling";
 
 type OrderSide = "buy" | "sell";
 type OrderStatus =
@@ -930,6 +933,9 @@ interface AccountRuntimeOptions {
   streamReconnectDelayMs?: number;
   streamReconnectMaxDelayMs?: number;
   listenKeyKeepAliveMs?: number;
+  binance?: {
+    riskPollIntervalMs?: number; // 默认 5_000
+  };
   juplend?: {
     pollIntervalMs?: number;
   };
@@ -1218,6 +1224,7 @@ interface RiskSnapshot {
   venue: Venue;
   equity?: BigNumber;
   riskRatio?: BigNumber;
+  actualLeverage?: BigNumber;
   initialMargin?: BigNumber;
   maintenanceMargin?: BigNumber;
   exchangeTs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.3.0-beta.3",
+  "version": "0.3.0-beta.4",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
     "@changesets/cli": "^2.31.0",
+    "@mindfoldhq/trellis": "^0.4.0",
     "@types/bun": "latest",
     "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@mindfoldhq/trellis": "^0.4.0",
     "bignumber.js": "^11.0.0"
   }
 }

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

@@ -56,6 +56,7 @@ interface BinancePapiUmPosition {
   unrealizedProfit?: string;
   liquidationPrice?: string;
   leverage?: string;
+  notional?: string;
   positionSide?: string;
   updateTime?: number;
 }
@@ -285,14 +286,18 @@ function mapBalance(
 function mapAccountRisk(
   input: BinancePapiAccount,
   receivedAt: number,
+  positions: BinancePapiUmPosition[] = [],
 ): RawRiskUpdate | undefined {
   const uniMmr = firstString(input.uniMMR);
   const riskRatio = uniMmr
     ? new BigNumber(1).dividedBy(uniMmr).toString(10)
     : undefined;
+  const equity = firstString(input.accountEquity, input.totalEquity);
+  const actualLeverage = calculateActualLeverage(equity, positions);
   const risk: RawRiskUpdate = {
-    equity: firstString(input.accountEquity, input.totalEquity),
+    equity,
     riskRatio,
+    actualLeverage,
     initialMargin: firstString(
       input.accountInitialMargin,
       input.totalInitialMargin,
@@ -308,6 +313,7 @@ function mapAccountRisk(
   if (
     !risk.equity &&
     !risk.riskRatio &&
+    !risk.actualLeverage &&
     !risk.initialMargin &&
     !risk.maintenanceMargin
   ) {
@@ -317,6 +323,34 @@ function mapAccountRisk(
   return risk;
 }
 
+function calculateActualLeverage(
+  equity: string | undefined,
+  positions: BinancePapiUmPosition[],
+): string | undefined {
+  if (!equity) {
+    return undefined;
+  }
+
+  const equityValue = new BigNumber(equity);
+  if (!equityValue.isFinite() || equityValue.isZero()) {
+    return undefined;
+  }
+
+  const grossExposure = positions.reduce((total, position) => {
+    const notional = firstString(position.notional);
+    if (!notional) {
+      return total;
+    }
+
+    const value = new BigNumber(notional);
+    return value.isFinite() ? total.plus(value.absoluteValue()) : total;
+  }, new BigNumber(0));
+
+  return grossExposure.isZero()
+    ? undefined
+    : grossExposure.dividedBy(equityValue).toString(10);
+}
+
 function mapUmPosition(
   input: BinancePapiUmPosition,
   receivedAt: number,
@@ -339,6 +373,22 @@ function mapUmPosition(
   };
 }
 
+function mapAccountRefresh(
+  account: BinancePapiAccount,
+  positions: BinancePapiUmPosition[],
+  receivedAt: number,
+): RawAccountUpdate {
+  return {
+    positions: positions.flatMap((position) => {
+      const mapped = mapUmPosition(position, receivedAt);
+      return mapped ? [mapped] : [];
+    }),
+    risk: mapAccountRisk(account, receivedAt, positions),
+    exchangeTs: account.updateTime,
+    receivedAt,
+  };
+}
+
 function mapOpenOrder(
   input: BinancePapiOpenOrder,
   receivedAt: number,
@@ -550,12 +600,35 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         const mapped = mapUmPosition(position, receivedAt);
         return mapped ? [mapped] : [];
       }),
-      risk: mapAccountRisk(account, receivedAt),
+      risk: mapAccountRisk(account, receivedAt, positions),
       exchangeTs: account.updateTime,
       receivedAt,
     };
   }
 
+  async refreshAccount(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawAccountUpdate> {
+    const receivedAt = Date.now();
+    const [account, positions] = await Promise.all([
+      this.signedRequest<BinancePapiAccount>(
+        "GET",
+        "/papi/v1/account",
+        credentials,
+        accountOptions,
+      ),
+      this.signedRequest<BinancePapiUmPosition[]>(
+        "GET",
+        "/papi/v1/um/positionRisk",
+        credentials,
+        accountOptions,
+      ),
+    ]);
+
+    return mapAccountRefresh(account, positions, receivedAt);
+  }
+
   async bootstrapOpenOrders(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

package/src/adapters/types.ts

@@ -121,6 +121,7 @@ export interface RawPositionUpdate {
 export interface RawRiskUpdate {
   equity?: string;
   riskRatio?: string;
+  actualLeverage?: string;
   initialMargin?: string;
   maintenanceMargin?: string;
   exchangeTs?: number;
@@ -222,6 +223,10 @@ export interface PrivateUserDataAdapter {
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
   ): Promise<RawAccountBootstrap>;
+  refreshAccount?(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawAccountUpdate>;
   bootstrapOpenOrders(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

package/src/client/context.ts

@@ -75,6 +75,7 @@ export interface PrivateAccountDataConsumer {
     accountId: string,
     venue: Venue,
     update: RawAccountUpdate,
+    options?: { preserveStatus?: boolean },
   ): void;
   onPrivateAccountStreamState(
     accountId: string,

package/src/client/private-subscription-coordinator.ts

@@ -19,6 +19,9 @@ interface PrivateSubscriptionRecord {
   accountReady: boolean;
   orderReady: boolean;
   stream?: StreamHandle;
+  accountRefreshTimer?: ReturnType<typeof setTimeout>;
+  accountRefreshInFlight?: Promise<void>;
+  accountRefreshGeneration: number;
   startPromise?: Promise<void>;
   reconcilePromise?: Promise<void>;
 }
@@ -27,6 +30,16 @@ const DEFAULT_STREAM_OPEN_TIMEOUT_MS = 15_000;
 const DEFAULT_STREAM_RECONNECT_DELAY_MS = 1_000;
 const DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS = 10_000;
 const DEFAULT_LISTEN_KEY_KEEPALIVE_MS = 30 * 60 * 1_000;
+const DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS = 5_000;
+
+function normalizePositiveInterval(
+  value: number | undefined,
+  fallback: number,
+): number {
+  return value !== undefined && Number.isFinite(value) && value > 0
+    ? value
+    : fallback;
+}
 
 export class PrivateSubscriptionCoordinator {
   private readonly context: ClientContext;
@@ -37,6 +50,7 @@ export class PrivateSubscriptionCoordinator {
   private readonly streamReconnectDelayMs: number;
   private readonly streamReconnectMaxDelayMs: number;
   private readonly listenKeyKeepAliveMs: number;
+  private readonly binanceRiskPollIntervalMs: number;
   private readonly juplendPollIntervalMs?: number;
   private readonly records = new Map<string, PrivateSubscriptionRecord>();
 
@@ -62,6 +76,10 @@ export class PrivateSubscriptionCoordinator {
       DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS;
     this.listenKeyKeepAliveMs =
       options.listenKeyKeepAliveMs ?? DEFAULT_LISTEN_KEY_KEEPALIVE_MS;
+    this.binanceRiskPollIntervalMs = normalizePositiveInterval(
+      options.binance?.riskPollIntervalMs,
+      DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS,
+    );
     this.juplendPollIntervalMs = options.juplend?.pollIntervalMs;
   }
 
@@ -81,6 +99,7 @@ export class PrivateSubscriptionCoordinator {
       } else {
         await this.ensureStream(record, account);
         await this.bootstrapAccount(record, account);
+        this.ensureAccountRefreshPolling(record);
       }
     } catch (error) {
       record.accountSubscribed = false;
@@ -96,6 +115,7 @@ export class PrivateSubscriptionCoordinator {
     }
 
     record.accountSubscribed = false;
+    this.stopAccountRefreshPolling(record);
     this.closeIfUnused(record);
   }
 
@@ -153,6 +173,7 @@ export class PrivateSubscriptionCoordinator {
 
   onClientStopping(): void {
     for (const record of this.records.values()) {
+      this.stopAccountRefreshPolling(record);
       this.closeStream(record);
     }
   }
@@ -164,6 +185,7 @@ export class PrivateSubscriptionCoordinator {
     }
 
     this.closeStream(record);
+    this.stopAccountRefreshPolling(record);
     this.records.delete(accountId);
   }
 
@@ -186,6 +208,7 @@ export class PrivateSubscriptionCoordinator {
   private async resumeRecord(record: PrivateSubscriptionRecord): Promise<void> {
     const account = this.getAccount(record.accountId);
     this.closeStream(record);
+    this.stopAccountRefreshPolling(record);
 
     try {
       if (record.venue === "juplend" && record.accountSubscribed) {
@@ -195,6 +218,7 @@ export class PrivateSubscriptionCoordinator {
         await this.ensureStream(record, account);
         if (record.accountSubscribed) {
           await this.bootstrapAccount(record, account);
+          this.ensureAccountRefreshPolling(record);
         }
       }
       if (record.ordersSubscribed) {
@@ -244,6 +268,7 @@ export class PrivateSubscriptionCoordinator {
       ordersSubscribed: false,
       accountReady: false,
       orderReady: false,
+      accountRefreshGeneration: 0,
     };
 
     this.records.set(account.accountId, record);
@@ -259,6 +284,7 @@ export class PrivateSubscriptionCoordinator {
       return;
     }
 
+    this.stopAccountRefreshPolling(record);
     this.closeStream(record);
     this.records.delete(record.accountId);
   }
@@ -268,6 +294,153 @@ export class PrivateSubscriptionCoordinator {
     record.stream = undefined;
   }
 
+  private ensureAccountRefreshPolling(record: PrivateSubscriptionRecord): void {
+    if (
+      record.venue !== "binance" ||
+      !record.accountSubscribed ||
+      record.accountRefreshTimer ||
+      record.accountRefreshInFlight
+    ) {
+      return;
+    }
+
+    this.scheduleAccountRefreshPoll(record);
+  }
+
+  private stopAccountRefreshPolling(record: PrivateSubscriptionRecord): void {
+    record.accountRefreshGeneration += 1;
+    if (record.accountRefreshTimer) {
+      clearTimeout(record.accountRefreshTimer);
+      record.accountRefreshTimer = undefined;
+    }
+    record.accountRefreshInFlight = undefined;
+  }
+
+  private scheduleAccountRefreshPoll(record: PrivateSubscriptionRecord): void {
+    if (record.venue !== "binance" || !record.accountSubscribed) {
+      return;
+    }
+
+    const generation = record.accountRefreshGeneration;
+    record.accountRefreshTimer = setTimeout(() => {
+      record.accountRefreshTimer = undefined;
+      if (
+        generation !== record.accountRefreshGeneration ||
+        record.venue !== "binance" ||
+        !record.accountSubscribed
+      ) {
+        return;
+      }
+
+      let latestAccount: RegisteredAccountRecord;
+      try {
+        latestAccount = this.getAccount(record.accountId);
+      } catch (error) {
+        this.handleAccountRefreshLookupError(record, error);
+        return;
+      }
+
+      record.accountRefreshInFlight = this.refreshAccount(
+        record,
+        latestAccount,
+        generation,
+      )
+        .catch(() => {})
+        .finally(() => {
+          if (generation !== record.accountRefreshGeneration) {
+            return;
+          }
+
+          record.accountRefreshInFlight = undefined;
+          if (record.accountSubscribed && record.venue === "binance") {
+            this.scheduleAccountRefreshPoll(record);
+          }
+        });
+    }, this.binanceRiskPollIntervalMs);
+  }
+
+  private handleAccountRefreshLookupError(
+    record: PrivateSubscriptionRecord,
+    error: unknown,
+  ): void {
+    this.stopAccountRefreshPolling(record);
+    if (error instanceof AcexError && error.code === "ACCOUNT_NOT_FOUND") {
+      return;
+    }
+
+    this.context.publishRuntimeError(
+      "adapter",
+      error instanceof Error
+        ? error
+        : new Error(`Failed to load ${record.venue} account for risk refresh`),
+      {
+        accountId: record.accountId,
+        venue: record.venue,
+      },
+    );
+  }
+
+  private async refreshAccount(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+    generation: number,
+  ): Promise<void> {
+    const adapter = this.getAdapter(record.venue);
+    if (!adapter.refreshAccount) {
+      return;
+    }
+
+    try {
+      const update = await adapter.refreshAccount(account.credentials ?? {}, {
+        ...account.options,
+        accountId: account.accountId,
+      });
+      if (
+        !record.accountSubscribed ||
+        generation !== record.accountRefreshGeneration
+      ) {
+        return;
+      }
+
+      record.accountReady = true;
+      this.accountConsumer.onPrivateAccountUpdate(
+        record.accountId,
+        record.venue,
+        update,
+        { preserveStatus: true },
+      );
+    } catch (error) {
+      if (
+        !record.accountSubscribed ||
+        generation !== record.accountRefreshGeneration
+      ) {
+        return;
+      }
+
+      this.context.publishRuntimeError(
+        "adapter",
+        error instanceof Error
+          ? error
+          : new Error(
+              `Failed to refresh ${record.venue} private account state`,
+            ),
+        {
+          accountId: record.accountId,
+          venue: record.venue,
+        },
+      );
+      this.accountConsumer.onPrivateAccountStreamState(
+        record.accountId,
+        record.venue,
+        {
+          runtimeStatus: "degraded",
+          ready: record.accountReady,
+          reason: "http_failed",
+        },
+      );
+    }
+  }
+
   private async ensureStream(
     record: PrivateSubscriptionRecord,
     account: RegisteredAccountRecord,

package/src/managers/account-manager.ts

@@ -277,6 +277,7 @@ export class AccountManagerImpl
     accountId: string,
     venue: Venue,
     update: RawAccountUpdate,
+    options: { preserveStatus?: boolean } = {},
   ): void {
     const record = this.getOrCreateRecord(accountId, venue);
     if (!record.subscribed) {
@@ -358,16 +359,24 @@ export class AccountManagerImpl
       receivedAt: update.receivedAt,
       updatedAt: update.receivedAt,
     };
-    record.status = {
-      ...record.status,
-      activity: "active",
-      ready: true,
-      runtimeStatus: "healthy",
-      reason: undefined,
-      lastReceivedAt: update.receivedAt,
-      lastReadyAt: update.receivedAt,
-      inactiveSince: undefined,
-    };
+    record.status = options.preserveStatus
+      ? {
+          ...record.status,
+          activity: "active",
+          lastReceivedAt: update.receivedAt,
+          lastReadyAt: record.status.lastReadyAt ?? update.receivedAt,
+          inactiveSince: undefined,
+        }
+      : {
+          ...record.status,
+          activity: "active",
+          ready: true,
+          runtimeStatus: "healthy",
+          reason: undefined,
+          lastReceivedAt: update.receivedAt,
+          lastReadyAt: update.receivedAt,
+          inactiveSince: undefined,
+        };
     this.publishStatus(record);
   }
 
@@ -588,6 +597,10 @@ export class AccountManagerImpl
         input.riskRatio === undefined
           ? previous?.riskRatio
           : new BigNumber(input.riskRatio),
+      actualLeverage:
+        input.actualLeverage === undefined
+          ? previous?.actualLeverage
+          : new BigNumber(input.actualLeverage),
       initialMargin:
         input.initialMargin === undefined
           ? previous?.initialMargin

package/src/types/account.ts

@@ -93,6 +93,7 @@ export interface RiskSnapshot {
   venue: Venue;
   equity?: BigNumber;
   riskRatio?: BigNumber;
+  actualLeverage?: BigNumber;
   initialMargin?: BigNumber;
   maintenanceMargin?: BigNumber;
   exchangeTs?: number;

package/src/types/shared.ts

@@ -36,6 +36,9 @@ export interface AccountRuntimeOptions {
   streamReconnectDelayMs?: number;
   streamReconnectMaxDelayMs?: number;
   listenKeyKeepAliveMs?: number;
+  binance?: {
+    riskPollIntervalMs?: number;
+  };
   juplend?: {
     pollIntervalMs?: number;
   };