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

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,
     },
@@ -612,7 +618,9 @@ const btcPosition = client.account.getPosition({
 const risk = client.account.getRiskSnapshot("main-binance");
 ```
 
-所有数量字段（`free` / `used` / `total` / `size` / `entryPrice` / `equity` / ...）都是 `BigNumber`。
+所有数量字段（`free` / `used` / `total` / `size` / `entryPrice` / `netEquity` / `riskEquity` / ...）都是 `BigNumber`。
+
+`RiskSnapshot.netEquity` 表示不含风控折算的净资产价值；`riskEquity` 表示抵押系数或清算阈值折算后的风控净权益。Binance 使用 `actualEquity` / `accountEquity` 映射这两个字段；Juplend 使用 `totalCollateralUsd - totalDebtUsd` / `Σ(suppliedValue × liquidationThreshold) - totalDebtUsd`。
 
 > **注意**：`AccountSnapshot.balances` 是 `Record<string, BalanceSnapshot>`，不是数组；需要数组视图用 `getBalances()`。
 
@@ -902,9 +910,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 +935,9 @@ interface AccountRuntimeOptions {
   streamReconnectDelayMs?: number;
   streamReconnectMaxDelayMs?: number;
   listenKeyKeepAliveMs?: number;
+  binance?: {
+    riskPollIntervalMs?: number; // 默认 5_000
+  };
   juplend?: {
     pollIntervalMs?: number;
   };
@@ -1216,8 +1224,10 @@ interface PositionSnapshot {
 interface RiskSnapshot {
   accountId: string;
   venue: Venue;
-  equity?: BigNumber;
+  netEquity?: BigNumber;
+  riskEquity?: BigNumber;
   riskRatio?: BigNumber;
+  riskLeverage?: 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.5",
   "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

@@ -38,6 +38,7 @@ interface BinancePapiBalance {
 
 interface BinancePapiAccount {
   accountEquity?: string;
+  actualEquity?: string;
   totalEquity?: string;
   accountInitialMargin?: string;
   totalInitialMargin?: string;
@@ -56,6 +57,7 @@ interface BinancePapiUmPosition {
   unrealizedProfit?: string;
   liquidationPrice?: string;
   leverage?: string;
+  notional?: string;
   positionSide?: string;
   updateTime?: number;
 }
@@ -285,14 +287,20 @@ 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 netEquity = firstString(input.actualEquity);
+  const riskEquity = firstString(input.accountEquity, input.totalEquity);
+  const riskLeverage = calculateRiskLeverage(riskEquity, positions);
   const risk: RawRiskUpdate = {
-    equity: firstString(input.accountEquity, input.totalEquity),
+    netEquity,
+    riskEquity,
     riskRatio,
+    riskLeverage,
     initialMargin: firstString(
       input.accountInitialMargin,
       input.totalInitialMargin,
@@ -306,8 +314,10 @@ function mapAccountRisk(
   };
 
   if (
-    !risk.equity &&
+    !risk.netEquity &&
+    !risk.riskEquity &&
     !risk.riskRatio &&
+    !risk.riskLeverage &&
     !risk.initialMargin &&
     !risk.maintenanceMargin
   ) {
@@ -317,6 +327,34 @@ function mapAccountRisk(
   return risk;
 }
 
+function calculateRiskLeverage(
+  riskEquity: string | undefined,
+  positions: BinancePapiUmPosition[],
+): string | undefined {
+  if (!riskEquity) {
+    return undefined;
+  }
+
+  const riskEquityValue = new BigNumber(riskEquity);
+  if (!riskEquityValue.isFinite() || riskEquityValue.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(riskEquityValue).toString(10);
+}
+
 function mapUmPosition(
   input: BinancePapiUmPosition,
   receivedAt: number,
@@ -339,6 +377,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 +604,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/juplend/private-adapter.ts

@@ -222,7 +222,8 @@ function buildRisk(input: {
     : undefined;
 
   return {
-    equity: totalCollateralUsd.minus(totalDebtUsd).toString(10),
+    netEquity: totalCollateralUsd.minus(totalDebtUsd).toString(10),
+    riskEquity: weightedLiquidationValueUsd.minus(totalDebtUsd).toString(10),
     riskRatio,
     receivedAt: input.receivedAt,
     lending: {

package/src/adapters/types.ts

@@ -119,8 +119,10 @@ export interface RawPositionUpdate {
 }
 
 export interface RawRiskUpdate {
-  equity?: string;
+  netEquity?: string;
+  riskEquity?: string;
   riskRatio?: string;
+  riskLeverage?: string;
   initialMargin?: string;
   maintenanceMargin?: string;
   exchangeTs?: number;
@@ -222,6 +224,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);
   }
 
@@ -580,14 +589,22 @@ export class AccountManagerImpl
     return {
       accountId,
       venue,
-      equity:
-        input.equity === undefined
-          ? previous?.equity
-          : new BigNumber(input.equity),
+      netEquity:
+        input.netEquity === undefined
+          ? previous?.netEquity
+          : new BigNumber(input.netEquity),
+      riskEquity:
+        input.riskEquity === undefined
+          ? previous?.riskEquity
+          : new BigNumber(input.riskEquity),
       riskRatio:
         input.riskRatio === undefined
           ? previous?.riskRatio
           : new BigNumber(input.riskRatio),
+      riskLeverage:
+        input.riskLeverage === undefined
+          ? previous?.riskLeverage
+          : new BigNumber(input.riskLeverage),
       initialMargin:
         input.initialMargin === undefined
           ? previous?.initialMargin

package/src/types/account.ts

@@ -91,8 +91,10 @@ export interface PositionSnapshot {
 export interface RiskSnapshot {
   accountId: string;
   venue: Venue;
-  equity?: BigNumber;
+  netEquity?: BigNumber;
+  riskEquity?: BigNumber;
   riskRatio?: BigNumber;
+  riskLeverage?: 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;
   };