@imbingox/acex 0.4.0-beta.12 → 0.4.0-beta.14

package/CHANGELOG.md

@@ -0,0 +1,176 @@
+# @imbingox/acex
+
+## 0.4.0-beta.14
+
+### Patch Changes
+
+- a57b1a0: Include `README.md` and `CHANGELOG.md` in the published npm package so downstream consumers can inspect package usage and release notes from the installed tarball.
+
+## 0.4.0-beta.13
+
+### Patch Changes
+
+- 3581ced: Binance private user streams now recover from `listenKeyExpired`, listenKey keepalive failure, and private stream message watchdog timeout by rotating the listenKey and rebuilding the WebSocket, then triggering the existing account/order reconcile path. Added optional `account.binance.privateStreamStaleAfterMs` tuning and a live order smoke entry for listenKey invalidation recovery.
+
+## 0.4.0-beta.12
+
+### Patch Changes
+
+- e98dba3: Fix Binance `cancelAllOrders` parsing of the PAPI `{code,msg}` response as an order array, which previously always threw against the live API after the venue had already canceled the orders. The adapter now pre-fetches symbol open orders and returns them as canceled snapshots after the cancel-all response succeeds.
+
+## 0.4.0-beta.11
+
+### Patch Changes
+
+- acbdfd8: OrderManager 内部订单主键改为 SDK 生成的 `localOrderId`，并维护 venue `orderId` / `clientOrderId` 反向索引与下单 pending claim，避免 REST 返回前早到的 WS 更新双建订单。公开 API 与类型不变。
+
+  行为变化：调用 `createOrder()` 未传 `clientOrderId` 时，SDK 现在会生成合规的 `acex-*` client id 并作为 Binance `newClientOrderId` 发送，返回的 `snapshot.clientOrderId` 也会是该生成值，而不再依赖 Binance 自动生成。
+
+## 0.4.0-beta.10
+
+### Patch Changes
+
+- 89f846e: OrderManager 内部订单存储改为 open / closed 分层（按 symbol 嵌套）+ 复合身份索引，终态订单不再无界累积：closed 订单按 symbol 保留最近 N 个（新增可选 `CreateClientOptions.order.maxClosedOrdersPerSymbol`，默认 500，超限按 FIFO 批量裁剪），`getOpenOrders()` 查询不再随历史订单数量增长而变慢。`getOrder()` 对外行为保持不变（仍可只按 `orderId` 或 `clientOrderId` 查询、可省略 `symbol`），`clientOrderId` 多命中时返回最新一笔。
+
+## 0.4.0-beta.9
+
+### Patch Changes
+
+- 153e2d8: Binance public market catalog now treats `TRADIFI_PERPETUAL` USDⓈ-M symbols as perpetual swaps, so TradFi Perps such as `AAPLUSDT` normalize to `AAPL/USDT:USDT` and support the existing L1 book and funding-rate public WebSocket subscriptions.
+
+## 0.4.0-beta.8
+
+### Minor Changes
+
+- d874b29: 公开 `AcexError.details` 与 `AcexError.cause`，让调用方在捕获订单、市场目录、server time、market stream 首包超时、account/order bootstrap 等失败时，既能继续使用稳定的 `error.code` 分支，也能读取交易所结构化拒绝原因（`details.venueError.code/message`）和已脱敏的 transport 诊断信息（`details.transport`）。
+
+## 0.4.0-beta.7
+
+### Minor Changes
+
+- dac87aa: Add `client.market.fetchServerTime(venue)` with Binance USDM server-time support, RTT measurement, estimated clock offset, venue capability reporting, and a structured failure code.
+
+## 0.4.0-beta.6
+
+### Minor Changes
+
+- f65bab7: 新增 `client.market.reloadMarkets(venue?)` 主动刷新市场目录能力，并公开 `MarketCatalogReloadSummary` 返回每个 venue 的新增、移除、总数和失败摘要。刷新失败会保留旧目录并在对应 summary 中返回错误，方便长运行进程在交易所新增 symbol 后无需重启即可加载新目录。
+
+## 0.4.0-beta.5
+
+### Patch Changes
+
+- e61f10f: private 编排层改为按 adapter capability 分派，移除残留的 venue 字面量：下单命令是否支持按 `orderCapabilities.supported`、订单订阅按 `orderCapabilities.updates`、private credentials 是否必需按 `accountCapabilities.credentialsRequired`、account stream 启动顺序按 `accountCapabilities.updates`（polling 先 bootstrap、websocket 先建流）、REST account refresh polling 按 adapter 是否实现可选的 `refreshAccount()` 判别。juplend 轮询间隔从内部 `PrivateStreamOptions` 收口进 adapter 构造。公开 API、公共类型与运行时行为均不变，为后续接入新交易所做准备。
+
+## 0.4.0-beta.4
+
+### Minor Changes
+
+- 0d99377: Add a public `RateLimiter` seam via `CreateClientOptions.rateLimiter`. The default reactive limiter tracks venue-provided REST usage metadata and honors `Retry-After` after 429/418 responses without proactively throttling normal requests or replaying non-idempotent order commands.
+
+## 0.4.0-beta.3
+
+### Minor Changes
+
+- c3c9460: Add an injectable request signing clock via `CreateClientOptions.clock` and the public `TimeProvider` type. The default remains the local system clock; this does not add server-time calibration.
+
+## 0.4.0-beta.2
+
+### Patch Changes
+
+- d9bacb6: 对外错误信息不再泄漏签名与密钥。请求失败时，错误的 `message` 与 URL 会对 `signature`、API key、`listenKey`、`token`、`passphrase` 等敏感 query 参数及对应的 JSON body 字段做脱敏（替换为 `[REDACTED]`），私有订阅 bootstrap 失败路径同样会对透传的错误信息脱敏。此前这些敏感值可能随错误信息进入日志。属向后兼容的行为修复，不改变公共类型与 API 形状。
+
+## 0.4.0-beta.1
+
+### Minor Changes
+
+- adc9274: 公共 snapshot / market 数值字段（包括 `L1Book`、`FundingRateSnapshot`、`OrderSnapshot`、`BalanceSnapshot`、`PositionSnapshot`、`RiskSnapshot`、`MarketDefinition` 及 lending facets）由 `BigNumber` 改为 canonical 十进制 string。
+
+  这是破坏性 public contract 变更：`snapshot.bidPrice.minus(...)`、`.multipliedBy(...)` 等链式调用不再可用，消费者需要改为 `new BigNumber(field)` 自行解析后运算（SDK 仍保留 `export { BigNumber }`）。不要用 `parseFloat()` 解析这些字段，否则会退回 JS 浮点精度。输入侧 `DecimalInput` 不变，仍接受 string / number / `BigNumber`。
+
+## 0.3.1-beta.0
+
+### Patch Changes
+
+- 19f60bc: Binance 行情订阅现在复用 WebSocket 连接：同一 connectionKey / base URL 下多个 symbol 复用物理连接（例如 USDM L1 与 funding 因 base URL 不同会分开），通过 JSON `SUBSCRIBE`/`UNSUBSCRIBE` 动态增删订阅，断线重连后自动重放，单连接订阅数达上限会自动开新连接。行情层改为按 venue 分派 adapter，为接入更多交易所打基础。公开 API 不变。
+
+## 0.3.0
+
+### Minor Changes
+
+- 14d25cb: 重命名账户风险权益字段并拆分净值与风控口径。`RiskSnapshot.equity` 替换为 `netEquity` / `riskEquity`，`actualLeverage` 替换为 `riskLeverage`；Binance 使用 `actualEquity` / `accountEquity` 分别映射净权益和风控折算权益，Juplend 使用清算阈值折算权益填充 `riskEquity`。
+- 50e4e09: 通过周期性 REST polling 刷新 Binance 账户风险和 mark-to-market 仓位字段。`RiskSnapshot` 现在暴露风控口径的 `riskLeverage`，Binance 账户运行时配置新增 `account.binance.riskPollIntervalMs`。
+- 680e315: Add strict-symbol market data aggregation APIs for markets, L1 books, and funding rates. Also update Binance USDⓈ-M funding mark price streams to use the current market websocket endpoint and default 3s `markPrice` stream.
+- 68356a0: Replace Juplend's portfolio-backed lending account implementation with native `@jup-ag/lend-read` reads. Juplend accounts no longer require credentials, can be loaded by `walletAddress` or direct `vaultId + positionId`, support optional RPC and Jup API enrichment via `SOL_HELIUS_RPC` / `account.juplend.rpcUrl` and `JUP_API` / `account.juplend.jupApiKey`, and now report more accurate lending balances, debt, collateral, and risk data from native vault sources.
+- c411b69: Add venue-based account registration and Juplend read-only lending account support. `Exchange` is renamed to `Venue`, account risk now uses unified `riskRatio`, and `RegisterAccountInput` is venue-specific so Juplend requires `credentials.apiKey` plus `options.walletAddress` with optional `positionId` filtering. Juplend account polling exposes lending balance/risk facets, replaces full snapshots to clear closed positions, and includes live smoke coverage.
+- 9dad2f0: Add post-only limit order support and market order input normalization. Binance PAPI UM limit orders now map `postOnly: true` to `timeInForce=GTX`, and callers can normalize price and amount strings with `market.normalizeOrderInput()` before placing orders.
+- ea9a4a7: Add top-level venue capability queries for SDK runtime support by venue.
+
+### Patch Changes
+
+- 46d1291: Include `docs/api.md` in the published npm package.
+
+## 0.3.0-beta.6
+
+### Minor Changes
+
+- 68356a0: Replace Juplend's portfolio-backed lending account implementation with native `@jup-ag/lend-read` reads. Juplend accounts no longer require credentials, can be loaded by `walletAddress` or direct `vaultId + positionId`, support optional RPC and Jup API enrichment via `SOL_HELIUS_RPC` / `account.juplend.rpcUrl` and `JUP_API` / `account.juplend.jupApiKey`, and now report more accurate lending balances, debt, collateral, and risk data from native vault sources.
+
+## 0.3.0-beta.5
+
+### Minor Changes
+
+- 14d25cb: 重命名账户风险权益字段并拆分净值与风控口径。`RiskSnapshot.equity` 替换为 `netEquity` / `riskEquity`，`actualLeverage` 替换为 `riskLeverage`；Binance 使用 `actualEquity` / `accountEquity` 分别映射净权益和风控折算权益，Juplend 使用清算阈值折算权益填充 `riskEquity`。
+
+## 0.3.0-beta.4
+
+### Minor Changes
+
+- 50e4e09: 通过周期性 REST polling 刷新 Binance 账户风险和 mark-to-market 仓位字段。`RiskSnapshot` 现在暴露 `actualLeverage`，Binance 账户运行时配置新增 `account.binance.riskPollIntervalMs`。
+
+## 0.3.0-beta.3
+
+### Minor Changes
+
+- ea9a4a7: Add top-level venue capability queries for SDK runtime support by venue.
+
+### Patch Changes
+
+- 46d1291: Include `docs/api.md` in the published npm package.
+
+## 0.3.0-beta.2
+
+### Minor Changes
+
+- c411b69: Add venue-based account registration and Juplend read-only lending account support. `Exchange` is renamed to `Venue`, account risk now uses unified `riskRatio`, and `RegisterAccountInput` is venue-specific so Juplend requires `credentials.apiKey` plus `options.walletAddress` with optional `positionId` filtering. Juplend account polling exposes lending balance/risk facets, replaces full snapshots to clear closed positions, and includes live smoke coverage.
+
+## 0.3.0-beta.1
+
+### Minor Changes
+
+- 9dad2f0: Add post-only limit order support and market order input normalization. Binance PAPI UM limit orders now map `postOnly: true` to `timeInForce=GTX`, and callers can normalize price and amount strings with `market.normalizeOrderInput()` before placing orders.
+
+## 0.3.0-beta.0
+
+### Minor Changes
+
+- 680e315: Add strict-symbol market data aggregation APIs for markets, L1 books, and funding rates. Also update Binance USDⓈ-M funding mark price streams to use the current market websocket endpoint and default 3s `markPrice` stream.
+
+## 0.2.0
+
+### Minor Changes
+
+- 5dcc3c1: Add Binance funding rate market data stream with per-stream market data status.
+- baeab15: Add Binance PAPI private account and order support, including the first `createOrder`, `cancelOrder`, and `cancelAllOrders` APIs.
+
+## 0.1.0-beta.4
+
+### Minor Changes
+
+- 5dcc3c1: Add Binance funding rate market data stream with per-stream market data status.
+
+## 0.1.0-beta.3
+
+### Minor Changes
+
+- baeab15: Add Binance PAPI private account and order support, including the first `createOrder`, `cancelOrder`, and `cancelAllOrders` APIs.

package/docs/api.md

@@ -100,7 +100,7 @@ const risk = client.account.getRiskSnapshot("main-binance");
 const openOrders = client.order.getOpenOrders("main-binance");
 ```
 
-Binance 账户能力当前面向 PAPI UM。账户风险字段会由私有 WS 事件和 `/papi/v1/account` + `/papi/v1/um/positionRisk` REST refresh 共同维护；默认每 60s 还会用 `/papi/v1/balance`、`/papi/v1/account`、`/papi/v1/um/positionRisk` 和订单 REST 接口做 private reconcile。Binance 全账户 `/papi/v1/um/openOrders` 不带 symbol 时 request weight 较高，默认 60s 是保守值。
+Binance 账户能力当前面向 PAPI UM。账户风险字段会由私有 WS 事件和 `/papi/v1/account` + `/papi/v1/um/positionRisk` REST refresh 共同维护；默认每 60s 还会用 `/papi/v1/balance`、`/papi/v1/account`、`/papi/v1/um/positionRisk` 和订单 REST 接口做 private reconcile。Binance 全账户 `/papi/v1/um/openOrders` 不带 symbol 时 request weight 较高，默认 60s 是保守值。读取余额、仓位或风险数据时必须订阅 `client.account.subscribeAccount()`；`client.order.subscribeOrders()` 只维护订单缓存，即使底层复用同一条 private WS，也不会维护 account 仓位缓存。
 
 ### 2.4 注册 Juplend 只读账户
 
@@ -242,6 +242,7 @@ const client = createClient({
     binance: {
       riskPollIntervalMs: 5_000,
       privateReconcileIntervalMs: 60_000,
+      privateStreamStaleAfterMs: 65 * 60_000,
     },
     juplend: {
       pollIntervalMs: 30_000,
@@ -392,7 +393,7 @@ interface AccountManager {
 
 `AccountSnapshot.balances` 是 `Record<string, BalanceSnapshot>`，数组视图用 `getBalances()`。
 
-Binance account update 是 REST bootstrap + WS 增量 + REST risk refresh + private reconcile 的组合。risk refresh 是增量语义，不会因 REST 缺失项删除本地 position；private reconcile 是全量校准语义，会清理 REST 全量余额/仓位中缺失或归零的本地记录。Juplend 每次 poll 都是全量快照，成功 poll 会替换 balances / positions / risk，用于清理已关闭或不再匹配的 position。
+Binance account update 是 REST bootstrap + WS 增量 + REST risk refresh + private reconcile 的组合。WS `ACCOUNT_UPDATE` 会更新发生变化的余额和仓位；`/papi/v1/account` + `/papi/v1/um/positionRisk` refresh 用于校准风险字段和 mark-to-market 仓位字段。risk refresh 是增量语义，不会因 REST 缺失项删除本地 position；private reconcile 是全量校准语义，会清理 REST 全量余额/仓位中缺失或归零的本地记录。Juplend 每次 poll 都是全量快照，成功 poll 会替换 balances / positions / risk，用于清理已关闭或不再匹配的 position。
 
 Account 事件用于消费余额、仓位、风险或全量快照替换：
 
@@ -586,6 +587,7 @@ interface CreateClientOptions {
     binance?: {
       riskPollIntervalMs?: number;
       privateReconcileIntervalMs?: number;
+      privateStreamStaleAfterMs?: number;
     };
     juplend?: {
       pollIntervalMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.12",
+  "version": "0.4.0-beta.14",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",
@@ -17,7 +17,9 @@
   "files": [
     "index.ts",
     "src/",
-    "docs/api.md"
+    "docs/api.md",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "changeset": "changeset",
@@ -25,7 +27,9 @@
     "changeset:pre:exit": "changeset pre exit && if [ -f .changeset/pre.json ]; then biome check --write .changeset/pre.json; fi",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
+    "pack:check": "bun run scripts/check-npm-pack.ts",
     "release": "changeset publish",
+    "release:notes": "bun run scripts/extract-changelog-section.ts",
     "type-check": "tsc --noEmit",
     "test": "bun test --max-concurrency=1 tests/unit tests/integration",
     "test:live:account": "bun run scripts/live-account-smoke.ts",
@@ -39,6 +43,7 @@
     "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",
+    "test:live:order:listen-key": "bun run scripts/live-order-smoke.ts --duration 60 --expire-listen-key-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",
     "test:unit": "bun test tests/unit",
     "test:integration": "bun test --max-concurrency=1 tests/integration",

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

@@ -155,9 +155,16 @@ interface BinanceOrderTradeUpdateMessage {
   o?: BinanceOrderTradeUpdatePayload;
 }
 
+interface BinanceListenKeyExpiredMessage {
+  e?: string;
+  E?: number;
+  listenKey?: string;
+}
+
 type BinancePrivateMessage =
   | BinanceAccountUpdateMessage
-  | BinanceOrderTradeUpdateMessage;
+  | BinanceOrderTradeUpdateMessage
+  | BinanceListenKeyExpiredMessage;
 
 const BINANCE_PAPI_REST_BASE_URL = "https://papi.binance.com";
 const BINANCE_PAPI_WS_BASE_URL = "wss://fstream.binance.com/pm/ws";
@@ -225,6 +232,10 @@ function getStringOption(
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
+function toError(value: unknown, fallback: string): Error {
+  return value instanceof Error ? value : new Error(fallback);
+}
+
 function signQuery(query: string, secret: string): string {
   return createHmac("sha256", secret).update(query).digest("hex");
 }
@@ -534,7 +545,9 @@ function mapAccountUpdatePosition(
 
 function parsePrivateMessage(data: string): BinancePrivateMessage | undefined {
   const parsed = JSON.parse(data) as BinancePrivateMessage;
-  return parsed.e === "ACCOUNT_UPDATE" || parsed.e === "ORDER_TRADE_UPDATE"
+  return parsed.e === "ACCOUNT_UPDATE" ||
+    parsed.e === "ORDER_TRADE_UPDATE" ||
+    parsed.e === "listenKeyExpired"
     ? parsed
     : undefined;
 }
@@ -545,6 +558,12 @@ function isAccountUpdateMessage(
   return message.e === "ACCOUNT_UPDATE";
 }
 
+function isListenKeyExpiredMessage(
+  message: BinancePrivateMessage,
+): message is BinanceListenKeyExpiredMessage {
+  return message.e === "listenKeyExpired";
+}
+
 function mapAccountUpdate(
   message: BinanceAccountUpdateMessage,
   receivedAt: number,
@@ -920,75 +939,158 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     options: PrivateStreamOptions,
     accountOptions?: Record<string, unknown>,
   ): StreamHandle {
+    interface PrivateStreamSession {
+      readonly listenKey: string;
+      websocket?: StreamHandle;
+      keepAliveTimer?: TimerHandle;
+      stopped: boolean;
+    }
+
+    type RecoveryReason =
+      | "heartbeat_timeout"
+      | "keepalive_failed"
+      | "listen_key_expired";
+
     let closed = false;
-    let listenKey: string | undefined;
-    let keepAliveTimer: TimerHandle | undefined;
-    let websocket: StreamHandle | undefined;
+    let activeSession: PrivateStreamSession | undefined;
+    let recoveryInFlight: Promise<void> | undefined;
+    let recoveryRetryTimer: ReturnType<typeof setTimeout> | undefined;
     let openedOnce = false;
 
-    const clearKeepAlive = () => {
-      if (keepAliveTimer) {
-        clearInterval(keepAliveTimer);
-        keepAliveTimer = undefined;
+    const clearRecoveryRetry = () => {
+      if (recoveryRetryTimer) {
+        clearTimeout(recoveryRetryTimer);
+        recoveryRetryTimer = undefined;
       }
     };
 
-    const closeListenKey = () => {
-      if (!listenKey) {
+    const closeListenKey = (listenKey: string) => {
+      void this.closeUserDataStream(
+        credentials,
+        listenKey,
+        accountOptions,
+      ).catch((error) => {
+        if (!closed) {
+          callbacks.onError(
+            toError(error, "Failed to close Binance PAPI listenKey"),
+          );
+        }
+      });
+    };
+
+    const closeSession = (
+      session: PrivateStreamSession | undefined,
+      shouldCloseListenKey: boolean,
+    ) => {
+      if (!session || session.stopped) {
         return;
       }
 
-      const key = listenKey;
-      listenKey = undefined;
-      void this.closeUserDataStream(credentials, key, accountOptions).catch(
-        (error) => {
-          callbacks.onError(
-            error instanceof Error
-              ? error
-              : new Error("Failed to close Binance PAPI listenKey"),
-          );
-        },
-      );
+      session.stopped = true;
+      if (session.keepAliveTimer) {
+        clearInterval(session.keepAliveTimer);
+        session.keepAliveTimer = undefined;
+      }
+      session.websocket?.close();
+      session.websocket = undefined;
+      if (shouldCloseListenKey) {
+        closeListenKey(session.listenKey);
+      }
     };
 
-    const ready = (async () => {
-      listenKey = await this.startUserDataStream(credentials, accountOptions);
+    const activateSession = (nextSession: PrivateStreamSession) => {
       if (closed) {
-        closeListenKey();
+        closeSession(nextSession, true);
         return;
       }
 
-      keepAliveTimer = setInterval(() => {
-        if (!listenKey) {
+      const previousSession = activeSession;
+      activeSession = nextSession;
+      closeSession(previousSession, true);
+
+      if (openedOnce) {
+        callbacks.onReconnected();
+      } else {
+        openedOnce = true;
+      }
+    };
+
+    const scheduleRecoveryRetry = (reason: RecoveryReason) => {
+      if (closed || recoveryRetryTimer) {
+        return;
+      }
+
+      recoveryRetryTimer = setTimeout(() => {
+        recoveryRetryTimer = undefined;
+        recoverPrivateStream(reason);
+      }, options.reconnectDelayMs);
+    };
+
+    const createSession = async (): Promise<
+      PrivateStreamSession | undefined
+    > => {
+      const listenKey = await this.startUserDataStream(
+        credentials,
+        accountOptions,
+      );
+      if (closed) {
+        closeListenKey(listenKey);
+        return undefined;
+      }
+
+      const nextSession: PrivateStreamSession = {
+        listenKey,
+        stopped: false,
+      };
+
+      nextSession.keepAliveTimer = setInterval(() => {
+        if (closed || activeSession !== nextSession) {
           return;
         }
 
         void this.keepAliveUserDataStream(
           credentials,
-          listenKey,
+          nextSession.listenKey,
           accountOptions,
         ).catch((error) => {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           callbacks.onError(
-            error instanceof Error
-              ? error
-              : new Error("Failed to keep Binance PAPI listenKey alive"),
+            toError(error, "Failed to keep Binance PAPI listenKey alive"),
           );
+          recoverPrivateStream("keepalive_failed");
         });
       }, options.listenKeyKeepAliveMs);
 
-      websocket = createManagedWebSocket<BinancePrivateMessage>({
+      nextSession.websocket = createManagedWebSocket<BinancePrivateMessage>({
         url: `${BINANCE_PAPI_WS_BASE_URL}/${listenKey}`,
         initialMessageTimeoutMs: options.openTimeoutMs,
         readyWhen: "open",
         now: options.now,
         parseMessage: parsePrivateMessage,
         onOpen() {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           if (openedOnce) {
             callbacks.onReconnected();
+          } else {
+            openedOnce = true;
           }
-          openedOnce = true;
         },
         onMessage(message, receivedAt) {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
+          if (isListenKeyExpiredMessage(message)) {
+            recoverPrivateStream("listen_key_expired");
+            return;
+          }
+
           if (isAccountUpdateMessage(message)) {
             callbacks.onAccountUpdate(mapAccountUpdate(message, receivedAt));
             return;
@@ -1000,13 +1102,31 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
           }
         },
         onUnexpectedClose() {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           callbacks.onDisconnected();
         },
         onError() {
+          if (closed || activeSession !== nextSession) {
+            return;
+          }
+
           callbacks.onError(
             new Error("WebSocket error for Binance PAPI private stream"),
           );
         },
+        messageWatchdog: {
+          staleAfterMs: options.staleAfterMs,
+          onStale() {
+            if (closed || activeSession !== nextSession) {
+              return;
+            }
+
+            recoverPrivateStream("heartbeat_timeout");
+          },
+        },
         reconnect: {
           initialDelayMs: options.reconnectDelayMs,
           maxDelayMs: options.reconnectMaxDelayMs,
@@ -1014,7 +1134,60 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         },
       });
 
-      await websocket.ready;
+      try {
+        await nextSession.websocket.ready;
+      } catch (error) {
+        closeSession(nextSession, true);
+        throw error;
+      }
+
+      return nextSession;
+    };
+
+    const recoverPrivateStream = (reason: RecoveryReason) => {
+      if (closed || recoveryInFlight) {
+        return;
+      }
+
+      clearRecoveryRetry();
+      if (reason === "heartbeat_timeout") {
+        callbacks.onFreshnessChange("stale", "heartbeat_timeout");
+      } else {
+        callbacks.onDisconnected();
+      }
+
+      const recovery = (async () => {
+        const previousSession = activeSession;
+        activeSession = undefined;
+        closeSession(previousSession, true);
+
+        try {
+          const nextSession = await createSession();
+          if (nextSession) {
+            activateSession(nextSession);
+          }
+        } catch (error) {
+          if (!closed) {
+            callbacks.onError(
+              toError(error, "Failed to rebuild Binance PAPI private stream"),
+            );
+            scheduleRecoveryRetry(reason);
+          }
+        }
+      })().finally(() => {
+        if (recoveryInFlight === recovery) {
+          recoveryInFlight = undefined;
+        }
+      });
+
+      recoveryInFlight = recovery;
+    };
+
+    const ready = (async () => {
+      const initialSession = await createSession();
+      if (initialSession) {
+        activateSession(initialSession);
+      }
     })();
 
     return {
@@ -1025,9 +1198,9 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         }
 
         closed = true;
-        clearKeepAlive();
-        websocket?.close();
-        closeListenKey();
+        clearRecoveryRetry();
+        closeSession(activeSession, true);
+        activeSession = undefined;
       },
     };
   }

package/src/adapters/types.ts

@@ -212,6 +212,7 @@ export interface PrivateStreamCallbacks {
   onAccountSnapshot(snapshot: RawAccountBootstrap): void;
   onAccountUpdate(update: RawAccountUpdate): void;
   onOrderUpdate(update: RawOrderUpdate): void;
+  onFreshnessChange(freshness: "stale", reason: "heartbeat_timeout"): void;
   onDisconnected(): void;
   onReconnected(): void;
   onError(error: Error): void;
@@ -222,6 +223,7 @@ export interface PrivateStreamOptions {
   reconnectDelayMs: number;
   reconnectMaxDelayMs: number;
   listenKeyKeepAliveMs: number;
+  staleAfterMs: number;
   now?: () => number;
 }
 

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

@@ -47,6 +47,7 @@ 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_PRIVATE_STREAM_STALE_AFTER_MS = 65 * 60_000;
 const DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS = 5_000;
 const DEFAULT_BINANCE_PRIVATE_RECONCILE_INTERVAL_MS = 60_000;
 const MAX_ORDER_TERMINAL_BACKFILLS_PER_RECONCILE = 20;
@@ -90,6 +91,7 @@ export class PrivateSubscriptionCoordinator {
   private readonly streamReconnectDelayMs: number;
   private readonly streamReconnectMaxDelayMs: number;
   private readonly listenKeyKeepAliveMs: number;
+  private readonly binancePrivateStreamStaleAfterMs: number;
   private readonly binanceRiskPollIntervalMs: number;
   private readonly binancePrivateReconcileIntervalMs: number | undefined;
   private readonly records = new Map<string, PrivateSubscriptionRecord>();
@@ -116,6 +118,10 @@ export class PrivateSubscriptionCoordinator {
       DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS;
     this.listenKeyKeepAliveMs =
       options.listenKeyKeepAliveMs ?? DEFAULT_LISTEN_KEY_KEEPALIVE_MS;
+    this.binancePrivateStreamStaleAfterMs = normalizePositiveInterval(
+      options.binance?.privateStreamStaleAfterMs,
+      DEFAULT_PRIVATE_STREAM_STALE_AFTER_MS,
+    );
     this.binanceRiskPollIntervalMs = normalizePositiveInterval(
       options.binance?.riskPollIntervalMs,
       DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS,
@@ -1180,6 +1186,30 @@ export class PrivateSubscriptionCoordinator {
             update,
           );
         },
+        onFreshnessChange: (_freshness, reason) => {
+          if (record.accountSubscribed) {
+            this.accountConsumer.onPrivateAccountStreamState(
+              record.accountId,
+              record.venue,
+              {
+                runtimeStatus: "reconnecting",
+                ready: record.accountReady,
+                reason,
+              },
+            );
+          }
+          if (record.ordersSubscribed) {
+            this.orderConsumer.onPrivateOrderStreamState(
+              record.accountId,
+              record.venue,
+              {
+                runtimeStatus: "reconnecting",
+                ready: record.orderReady,
+                reason,
+              },
+            );
+          }
+        },
         onDisconnected: () => {
           if (record.accountSubscribed) {
             this.accountConsumer.onPrivateAccountStreamState(
@@ -1236,6 +1266,7 @@ export class PrivateSubscriptionCoordinator {
         reconnectDelayMs: this.streamReconnectDelayMs,
         reconnectMaxDelayMs: this.streamReconnectMaxDelayMs,
         listenKeyKeepAliveMs: this.listenKeyKeepAliveMs,
+        staleAfterMs: this.binancePrivateStreamStaleAfterMs,
         now: () => this.context.now(),
       },
       { ...account.options, accountId: account.accountId },