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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @imbingox/acex
 
+## 0.4.0-beta.16
+
+### Minor Changes
+
+- bdaf9ea: 订单生命周期增加 confirmed-missing 收尾与 pending claim TTL：`OrderStatus` 新增 `unknown` 终态，open 订单在 reconcile 单笔回查连续确认不存在后会移入 closed；`CreateClientOptions.order` 新增 `missingOrderEvictionThreshold` 与 `pendingClaimTtlMs`，用于配置幽灵 open 订单驱逐阈值和 `createOrder` timeout claim 回查 TTL。
+
+## 0.4.0-beta.15
+
+### Minor Changes
+
+- 3f6dcb8: 新增 `AcexError.details.venueError.reason`、订单命令错误的 `details.orderState`，并导出 `isOrderStateUnknown()`，方便调用方用稳定语义区分交易所拒单、限流、余额不足和订单状态未知场景。
+
 ## 0.4.0-beta.14
 
 ### Patch Changes

package/docs/api.md

@@ -442,7 +442,7 @@ interface OrderManager {
 
 ### 7.3 本地缓存与查询
 
-- OrderManager 内部按 open / closed 分层缓存订单。**closed（filled / canceled / rejected / expired）订单按 symbol 各保留最近 N 个**，`N = CreateClientOptions.order.maxClosedOrdersPerSymbol`（默认 500，非正或非整数回退默认），超限按 FIFO 裁剪最旧；**open 订单不受此上限限制**。`getOpenOrders()` 查询复杂度与历史终态订单数量无关。
+- OrderManager 内部按 open / closed 分层缓存订单。**closed（filled / canceled / rejected / expired / unknown）订单按 symbol 各保留最近 N 个**，`N = CreateClientOptions.order.maxClosedOrdersPerSymbol`（默认 500，非正或非整数回退默认），超限按 FIFO 裁剪最旧；**open 订单不受此上限限制**。`getOpenOrders()` 查询复杂度与历史终态订单数量无关。
 - `getOrder(input)` 需带 `orderId` 或 `clientOrderId`（否则返回 `undefined`），`symbol` 可选：
   - **精确查单推荐传 `symbol + orderId`**（O(1) 精确索引、唯一命中）。
   - 仅 `clientOrderId` 查询可命中 open 与未被裁剪的 closed；当 `clientOrderId` 唯一（你自定义的或 SDK 生成的 `acex-*`）时可精确命中，但同一 `clientOrderId` 命中多笔时返回**最新一笔**（精确定位历史某一笔请用 `symbol + orderId`）。
@@ -450,7 +450,7 @@ interface OrderManager {
   - 同时给 `orderId` 与 `clientOrderId` 时，两者都匹配才命中。
   - 已超出保留上限被裁剪的 closed 订单将查不到（返回 `undefined`）。
 
-Order 事件用于消费订单状态变化和 open orders 快照校准。Binance private reconcile 会先用 `/papi/v1/um/openOrders` 校验当前 open set；本地 open order 从 open set 消失时，SDK 会优先查询单笔订单终态并发布 `order.filled` / `order.canceled` 等事件。若 Binance retention / not found 导致无法证明终态，SDK 不会合成 filled/canceled，而是保留原 snapshot 并把 order status 标记为 `degraded`，下一轮继续尝试。
+Order 事件用于消费订单状态变化和 open orders 快照校准。Binance private reconcile 会先用 `/papi/v1/um/openOrders` 校验当前 open set；本地 open order 从 open set 消失时，SDK 会优先查询单笔订单终态并发布 `order.filled` / `order.canceled` 等事件。若单笔查询连续确认订单不存在（默认 3 次，`CreateClientOptions.order.missingOrderEvictionThreshold` 可配置），SDK 会把该订单终态化为 `status: "unknown"`、移出 open 缓存并发布一次 runtime error；网络/超时/限流等 transport 错误不会计入该阈值。`createOrder()` 超时保留的 pending claim 会在 reconcile 周期里按 `CreateClientOptions.order.pendingClaimTtlMs`（默认 90s）过期回查：查到订单则正常入库，确认不存在则清理 claim 并发布 runtime error；无 `fetchOrder` 能力的 venue 会保守保留 claim。
 
 ```ts
 for await (const event of client.order.events.updates({
@@ -499,7 +499,8 @@ type OrderStatus =
   | "filled"
   | "canceled"
   | "rejected"
-  | "expired";
+  | "expired"
+  | "unknown";
 
 type PrivateRuntimeReason =
   | "credentials_missing"
@@ -597,6 +598,8 @@ interface CreateClientOptions {
   };
   order?: {
     maxClosedOrdersPerSymbol?: number;
+    missingOrderEvictionThreshold?: number;
+    pendingClaimTtlMs?: number;
   };
 }
 
@@ -918,20 +921,43 @@ type OrderEvent =
 可预期错误统一抛 `AcexError`：
 
 ```ts
-import { AcexError } from "@imbingox/acex";
+import { AcexError, isOrderStateUnknown } from "@imbingox/acex";
 
 try {
-  await client.market.subscribeL1Book({ venue: "binance", symbol: "X/Y:Z" });
+  await client.order.createOrder({
+    accountId: "main-binance",
+    symbol: "BTC/USDT:USDT",
+    side: "buy",
+    type: "limit",
+    price: "101000",
+    amount: "0.01",
+    postOnly: true,
+  });
 } catch (error) {
   if (error instanceof AcexError) {
     console.log(error.code);
     console.log(error.details?.venueError?.code);
+    console.log(error.details?.venueError?.reason);
+    console.log(error.details?.orderState);
     console.log(error.details?.transport?.status);
+    console.log(isOrderStateUnknown(error));
   }
 }
 ```
 
-`details.venueError` 是读取交易所结构化拒绝原因的首选字段；`details.transport` 保存已脱敏的 HTTP / transport 诊断信息；`cause` 保留底层错误链。
+`details.venueError` 是读取交易所结构化拒绝原因的首选字段；`details.venueError.reason` 是 SDK 归一后的稳定原因，原始 `code/message` 会继续保留。`details.orderState` 只在订单命令错误中填写：`not_placed` 表示 SDK 判定订单未落地，`unknown` 表示请求可能已经到达交易所，应由调用方后续查询或对账确认。`details.transport` 保存已脱敏的 HTTP / transport 诊断信息；`cause` 保留底层错误链。
+
+归一错误原因：
+
+| `VenueErrorReason` | 典型含义 |
+|---|---|
+| `insufficient_balance` | 余额或保证金不足 |
+| `would_take` | Post Only / maker-only 订单会吃单而被拒 |
+| `order_not_found` | 订单不存在、已不在可撤订单簿或超过交易所可查询范围 |
+| `filter_violation` | 价格、数量、精度、最小名义金额或订单数量限制不满足 |
+| `rate_limited` | 请求权重、订单频率或账户排队被限流 |
+| `timestamp_out_of_sync` | 请求时间戳或 `recvWindow` 与交易所时间不匹配 |
+| `unknown` | 交易所原始码未归入稳定语义，调用方仍可读取原始 `code/message` |
 
 完整错误码：
 

package/package.json

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

package/src/adapters/binance/error-codes.ts

@@ -0,0 +1,53 @@
+import type { VenueErrorReason } from "../../errors.ts";
+
+const BINANCE_RATE_LIMITED_CODES = new Set([
+  "-1003",
+  "-1008",
+  "-1015",
+  "-5041",
+]);
+const BINANCE_TIMESTAMP_OUT_OF_SYNC_CODES = new Set(["-1021", "-5028"]);
+const BINANCE_ORDER_NOT_FOUND_CODES = new Set(["-2011", "-2013"]);
+const BINANCE_INSUFFICIENT_BALANCE_CODES = new Set(["-2018", "-2019"]);
+const BINANCE_WOULD_TAKE_CODES = new Set(["-5022"]);
+const BINANCE_FILTER_VIOLATION_CODES = new Set([
+  "-4131",
+  "-2025",
+  "-1111",
+  "-4002",
+  "-4004",
+  "-4005",
+  "-4013",
+  "-4014",
+  "-4016",
+  "-4023",
+  "-4024",
+  "-4029",
+  "-4030",
+  "-4164",
+  "-4183",
+  "-4184",
+]);
+
+export function normalizeBinanceErrorCode(code: string): VenueErrorReason {
+  if (BINANCE_RATE_LIMITED_CODES.has(code)) {
+    return "rate_limited";
+  }
+  if (BINANCE_TIMESTAMP_OUT_OF_SYNC_CODES.has(code)) {
+    return "timestamp_out_of_sync";
+  }
+  if (BINANCE_ORDER_NOT_FOUND_CODES.has(code)) {
+    return "order_not_found";
+  }
+  if (BINANCE_INSUFFICIENT_BALANCE_CODES.has(code)) {
+    return "insufficient_balance";
+  }
+  if (BINANCE_WOULD_TAKE_CODES.has(code)) {
+    return "would_take";
+  }
+  if (BINANCE_FILTER_VIOLATION_CODES.has(code)) {
+    return "filter_violation";
+  }
+
+  return "unknown";
+}

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

@@ -33,6 +33,7 @@ import type {
   RawRiskUpdate,
   StreamHandle,
 } from "../types.ts";
+import { normalizeBinanceErrorCode } from "./error-codes.ts";
 import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
 
 type TimerHandle = ReturnType<typeof setInterval>;
@@ -183,7 +184,6 @@ const LISTEN_KEY_KEEPALIVE_RETRY_POLICY: HttpRetryPolicy = {
   idempotent: true,
   maxAttempts: 3,
 };
-const BINANCE_ORDER_NOT_FOUND_CODES = new Set(["-2011", "-2013"]);
 function getBinancePapiHttpMessages(timeoutMs: number): HttpClientMessages {
   return {
     http: ({ status, statusText, url, rawBody }) =>
@@ -628,7 +628,7 @@ function isBinanceOrderNotFound(error: unknown): boolean {
 
   try {
     const parsed = JSON.parse(rawBody) as { code?: unknown };
-    return BINANCE_ORDER_NOT_FOUND_CODES.has(`${parsed.code}`);
+    return normalizeBinanceErrorCode(`${parsed.code}`) === "order_not_found";
   } catch {
     return false;
   }
@@ -676,6 +676,10 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     } = {},
   ) {}
 
+  normalizeVenueErrorCode(code: string) {
+    return normalizeBinanceErrorCode(code);
+  }
+
   async bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

package/src/adapters/types.ts

@@ -1,3 +1,4 @@
+import type { VenueErrorReason } from "../errors.ts";
 import type {
   AccountCredentials,
   CreateOrderType,
@@ -233,6 +234,7 @@ export interface PrivateUserDataAdapter {
   readonly notes: string[];
   readonly accountCapabilities: VenueAccountCapabilities;
   readonly orderCapabilities: VenueOrderCapabilities;
+  normalizeVenueErrorCode?(code: string): VenueErrorReason;
   bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

package/src/client/context.ts

@@ -4,6 +4,7 @@ import type {
   RawOpenOrdersSnapshot,
   RawOrderUpdate,
 } from "../adapters/types.ts";
+import type { VenueErrorReason } from "../errors.ts";
 import type {
   AccountCredentials,
   AcexInternalError,
@@ -30,6 +31,10 @@ export interface ClientContext {
   assertStarted(): void;
   getRegisteredAccount(accountId: string): RegisteredAccountRecord;
   getPrivateOrderCapabilities(venue: Venue): VenueOrderCapabilities | undefined;
+  normalizeVenueErrorCode(
+    venue: Venue,
+    code: string,
+  ): VenueErrorReason | undefined;
   ensurePrivateCredentials(accountId: string): void;
   subscribePrivateAccountFeed(accountId: string): Promise<void>;
   unsubscribePrivateAccountFeed(accountId: string): void;
@@ -68,6 +73,13 @@ export interface PrivateSubscriptionState {
   lastReadyAt?: number;
 }
 
+export interface ExpiredPendingOrderClaim {
+  venueClientOrderId: string;
+  localOrderId: string;
+  symbol: string;
+  claimedAt: number;
+}
+
 export interface PrivateAccountDataConsumer {
   onPrivateAccountPending(accountId: string, venue: Venue): void;
   onPrivateAccountBootstrap(
@@ -114,7 +126,22 @@ export interface PrivateOrderDataConsumer {
     update: RawOrderUpdate,
     options?: { requestStartedAt?: number; preserveStatus?: boolean },
   ): void;
+  onPrivateOrderConfirmedMissing(
+    accountId: string,
+    venue: Venue,
+    order: OrderSnapshot,
+  ): void;
   getPrivateOpenOrders(accountId: string): OrderSnapshot[];
+  getExpiredPrivateOrderClaims(
+    accountId: string,
+    now: number,
+    ttlMs: number,
+  ): ExpiredPendingOrderClaim[];
+  onPrivateOrderClaimNotFound(
+    accountId: string,
+    venue: Venue,
+    claim: ExpiredPendingOrderClaim,
+  ): void;
   onPrivateOrderStreamState(
     accountId: string,
     venue: Venue,

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

@@ -12,12 +12,14 @@ import {
 import { isTransportError } from "../internal/http-client.ts";
 import type {
   AccountRuntimeOptions,
+  OrderRuntimeOptions,
   OrderSnapshot,
   PrivateRuntimeReason,
   Venue,
 } from "../types/index.ts";
 import type {
   ClientContext,
+  ExpiredPendingOrderClaim,
   PrivateAccountDataConsumer,
   PrivateOrderDataConsumer,
   RegisteredAccountRecord,
@@ -50,6 +52,7 @@ 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 DEFAULT_PENDING_CLAIM_TTL_MS = 90_000;
 const MAX_ORDER_TERMINAL_BACKFILLS_PER_RECONCILE = 20;
 const MAX_ORDER_TERMINAL_BACKFILL_CONCURRENCY = 4;
 
@@ -94,6 +97,7 @@ export class PrivateSubscriptionCoordinator {
   private readonly binancePrivateStreamStaleAfterMs: number;
   private readonly binanceRiskPollIntervalMs: number;
   private readonly binancePrivateReconcileIntervalMs: number | undefined;
+  private readonly pendingClaimTtlMs: number;
   private readonly records = new Map<string, PrivateSubscriptionRecord>();
 
   constructor(
@@ -102,6 +106,7 @@ export class PrivateSubscriptionCoordinator {
     accountConsumer: PrivateAccountDataConsumer,
     orderConsumer: PrivateOrderDataConsumer,
     options: AccountRuntimeOptions = {},
+    orderOptions: OrderRuntimeOptions = {},
   ) {
     this.context = context;
     this.adapters = new Map(
@@ -130,6 +135,10 @@ export class PrivateSubscriptionCoordinator {
       options.binance?.privateReconcileIntervalMs,
       DEFAULT_BINANCE_PRIVATE_RECONCILE_INTERVAL_MS,
     );
+    this.pendingClaimTtlMs = normalizePositiveInterval(
+      orderOptions.pendingClaimTtlMs,
+      DEFAULT_PENDING_CLAIM_TTL_MS,
+    );
   }
 
   async subscribeAccountFeed(accountId: string): Promise<void> {
@@ -940,6 +949,12 @@ export class PrivateSubscriptionCoordinator {
         orderGeneration,
         disappeared,
       );
+      await this.reconcileExpiredPendingOrderClaims(
+        record,
+        account,
+        generation,
+        orderGeneration,
+      );
     } catch (error) {
       if (
         !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
@@ -1054,11 +1069,104 @@ export class PrivateSubscriptionCoordinator {
       }
 
       if (!update) {
-        this.handleOrderReconcileError(
-          record,
-          new Error(
-            `Failed to backfill disappeared ${record.venue} order terminal state`,
-          ),
+        this.orderConsumer.onPrivateOrderConfirmedMissing(
+          record.accountId,
+          record.venue,
+          order,
+        );
+        return;
+      }
+
+      this.orderConsumer.onPrivateOrderUpdate(
+        record.accountId,
+        record.venue,
+        update,
+        {
+          requestStartedAt,
+        },
+      );
+    } catch (error) {
+      if (
+        !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+      ) {
+        return;
+      }
+
+      this.handleOrderReconcileError(record, error);
+    }
+  }
+
+  private async reconcileExpiredPendingOrderClaims(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+    generation: number,
+    orderGeneration: number,
+  ): Promise<void> {
+    const adapter = this.getAdapter(record.venue);
+    if (
+      !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+    ) {
+      return;
+    }
+
+    if (!adapter.fetchOrder) {
+      // Pending createOrder claims can only be retired after the venue confirms
+      // the clientOrderId is absent. Adapters without fetchOrder keep claims.
+      return;
+    }
+
+    const expiredClaims = this.orderConsumer.getExpiredPrivateOrderClaims(
+      record.accountId,
+      this.context.now(),
+      this.pendingClaimTtlMs,
+    );
+    for (const claim of expiredClaims) {
+      await this.reconcileExpiredPendingOrderClaim(
+        record,
+        account,
+        generation,
+        orderGeneration,
+        claim,
+      );
+    }
+  }
+
+  private async reconcileExpiredPendingOrderClaim(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+    generation: number,
+    orderGeneration: number,
+    claim: ExpiredPendingOrderClaim,
+  ): Promise<void> {
+    const adapter = this.getAdapter(record.venue);
+    if (
+      !adapter.fetchOrder ||
+      !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+    ) {
+      return;
+    }
+
+    const requestStartedAt = this.context.now();
+    try {
+      const update = await adapter.fetchOrder(
+        account.credentials ?? {},
+        {
+          symbol: claim.symbol,
+          clientOrderId: claim.venueClientOrderId,
+        },
+        { ...account.options, accountId: account.accountId },
+      );
+      if (
+        !this.shouldContinueOrderBootstrap(record, generation, orderGeneration)
+      ) {
+        return;
+      }
+
+      if (!update) {
+        this.orderConsumer.onPrivateOrderClaimNotFound(
+          record.accountId,
+          record.venue,
+          claim,
         );
         return;
       }

package/src/client/runtime.ts

@@ -13,6 +13,7 @@ import {
   AcexError,
   type AcexErrorCode,
   buildAcexErrorDetails,
+  type VenueErrorReason,
 } from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { matchesHealthFilter } from "../internal/filters.ts";
@@ -142,6 +143,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
       this.accountManager as PrivateAccountDataConsumer,
       this.orderManager as PrivateOrderDataConsumer,
       options.account,
+      options.order,
     );
 
     this.market = this.marketManager;
@@ -312,6 +314,13 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.privateAdapters.get(venue)?.orderCapabilities;
   }
 
+  normalizeVenueErrorCode(
+    venue: Venue,
+    code: string,
+  ): VenueErrorReason | undefined {
+    return this.privateAdapters.get(venue)?.normalizeVenueErrorCode?.(code);
+  }
+
   ensurePrivateCredentials(accountId: string): void {
     const account = this.getRegisteredAccount(accountId);
     if (

package/src/errors.ts

@@ -27,9 +27,19 @@ export type AcexErrorTransportKind =
   | "rate_limited"
   | "parse";
 
+export type VenueErrorReason =
+  | "insufficient_balance"
+  | "would_take"
+  | "order_not_found"
+  | "filter_violation"
+  | "rate_limited"
+  | "timestamp_out_of_sync"
+  | "unknown";
+
 export interface AcexVenueErrorDetails {
   readonly code?: string;
   readonly message?: string;
+  readonly reason?: VenueErrorReason;
 }
 
 export interface AcexErrorTransportDetails {
@@ -49,6 +59,7 @@ export interface AcexErrorDetails {
   readonly symbol?: string;
   readonly venueError?: AcexVenueErrorDetails;
   readonly transport?: AcexErrorTransportDetails;
+  readonly orderState?: "not_placed" | "unknown";
 }
 
 export interface AcexErrorOptions {
@@ -91,6 +102,10 @@ export function buildAcexErrorDetails(
   return hasDetails(details) ? details : undefined;
 }
 
+export function isOrderStateUnknown(error: unknown): boolean {
+  return error instanceof AcexError && error.details?.orderState === "unknown";
+}
+
 export function formatAcexErrorMessage(
   message: string,
   details?: AcexErrorDetails,
@@ -166,7 +181,8 @@ function hasDetails(details: AcexErrorDetails): boolean {
       details.accountId ||
       details.symbol ||
       details.venueError ||
-      details.transport,
+      details.transport ||
+      details.orderState,
   );
 }
 

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   AcexErrorTransportDetails,
   AcexErrorTransportKind,
   AcexVenueErrorDetails,
+  VenueErrorReason,
 } from "./errors.ts";
-export { AcexError } from "./errors.ts";
+export { AcexError, isOrderStateUnknown } from "./errors.ts";
 export * from "./types/index.ts";

package/src/managers/order/data-status.ts

@@ -1,6 +1,7 @@
 import type { OrderDataStatus, Venue } from "../../types/index.ts";
 
 export const DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL = 500;
+export const DEFAULT_MISSING_ORDER_EVICTION_THRESHOLD = 3;
 
 export function cloneOrderStatus(status: OrderDataStatus): OrderDataStatus {
   return { ...status };
@@ -28,6 +29,14 @@ export function normalizeMaxClosedOrdersPerSymbol(
     : DEFAULT_MAX_CLOSED_ORDERS_PER_SYMBOL;
 }
 
+export function normalizeMissingOrderEvictionThreshold(
+  value: number | undefined,
+): number {
+  return value !== undefined && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MISSING_ORDER_EVICTION_THRESHOLD;
+}
+
 export function successfulStatus(
   status: OrderDataStatus,
   options: {

package/src/managers/order/model.ts

@@ -15,6 +15,7 @@ export interface OrderRecord {
   orderIdOnlyIndex: Map<string, Set<string>>;
   clientOrderIdIndex: Map<string, Set<string>>;
   pendingClientOrderIdIndex: Map<string, PendingOrderClaim>;
+  missingOrderConfirmations: Map<string, number>;
   status: OrderDataStatus;
 }
 
@@ -29,8 +30,10 @@ export interface OrderLocation {
 export interface PendingOrderClaim {
   localOrderId: string;
   symbol: string;
+  claimedAt: number;
 }
 
 export interface OrderManagerOptions {
   maxClosedOrdersPerSymbol?: number;
+  missingOrderEvictionThreshold?: number;
 }

package/src/managers/order/snapshot.ts

@@ -78,6 +78,7 @@ export function orderPriority(status: OrderSnapshot["status"]): number {
     case "expired":
       return 4;
     case "rejected":
+    case "unknown":
       return 3;
     case "partially_filled":
       return 2;

package/src/managers/order-manager.ts

@@ -5,11 +5,13 @@ import type {
 import type {
   AccountAwareManager,
   ClientContext,
+  ExpiredPendingOrderClaim,
   HealthReporter,
   ManagerLifecycle,
   PrivateOrderDataConsumer,
   PrivateSubscriptionState,
 } from "../client/context.ts";
+import type { AcexErrorDetails, AcexErrorTransportKind } from "../errors.ts";
 import {
   AcexError,
   buildAcexErrorDetails,
@@ -42,6 +44,7 @@ import {
   cloneOrderStatus,
   createOrderDataStatus,
   normalizeMaxClosedOrdersPerSymbol,
+  normalizeMissingOrderEvictionThreshold,
   successfulStatus,
 } from "./order/data-status.ts";
 import {
@@ -60,6 +63,7 @@ import { createSnapshot, isOpenOrder } from "./order/snapshot.ts";
 import {
   getAllSnapshots,
   getExistingSnapshot,
+  getExistingSnapshotLocation,
   getLocalOrderIdForVenueOrderId,
   getLocationByLocalOrderId,
   getOpenOrderSnapshots,
@@ -74,6 +78,15 @@ import {
   setSnapshot,
 } from "./order/store.ts";
 
+type OrderCommandErrorCode =
+  | "ORDER_CANCEL_ALL_FAILED"
+  | "ORDER_CANCEL_FAILED"
+  | "ORDER_CREATE_FAILED";
+
+type OrderErrorCode = OrderCommandErrorCode | "ORDER_INPUT_INVALID";
+
+type OrderCommandOrderState = NonNullable<AcexErrorDetails["orderState"]>;
+
 export class OrderManagerImpl
   implements
     OrderManager,
@@ -86,6 +99,7 @@ export class OrderManagerImpl
 
   private readonly context: ClientContext;
   private readonly maxClosedOrdersPerSymbol: number;
+  private readonly missingOrderEvictionThreshold: number;
   private readonly orderBus = new AsyncEventBus<OrderEvent>();
   private readonly orderStatusBus =
     new AsyncEventBus<OrderStatusChangedEvent>();
@@ -97,6 +111,9 @@ export class OrderManagerImpl
     this.maxClosedOrdersPerSymbol = normalizeMaxClosedOrdersPerSymbol(
       options.maxClosedOrdersPerSymbol,
     );
+    this.missingOrderEvictionThreshold = normalizeMissingOrderEvictionThreshold(
+      options.missingOrderEvictionThreshold,
+    );
 
     this.events = {
       status: (filter) =>
@@ -484,6 +501,9 @@ export class OrderManagerImpl
         openSetKeys.add(lookupKey);
       }
       const current = getExistingSnapshot(record, update);
+      if (current) {
+        this.clearMissingOrderConfirmationsForUpdate(record, current);
+      }
       const nextSnapshot = this.applyUpdateToRecord(
         record,
         accountId,
@@ -555,6 +575,36 @@ export class OrderManagerImpl
     return this.getOpenOrders(accountId);
   }
 
+  getExpiredPrivateOrderClaims(
+    accountId: string,
+    now: number,
+    ttlMs: number,
+  ): ExpiredPendingOrderClaim[] {
+    const record = this.records.get(accountId);
+    if (!record || ttlMs <= 0) {
+      return [];
+    }
+
+    const expired: ExpiredPendingOrderClaim[] = [];
+    for (const [
+      venueClientOrderId,
+      claim,
+    ] of record.pendingClientOrderIdIndex) {
+      if (now - claim.claimedAt < ttlMs) {
+        continue;
+      }
+
+      expired.push({
+        venueClientOrderId,
+        localOrderId: claim.localOrderId,
+        symbol: claim.symbol,
+        claimedAt: claim.claimedAt,
+      });
+    }
+
+    return expired;
+  }
+
   onPrivateOrderUpdate(
     accountId: string,
     venue: Venue,
@@ -580,32 +630,129 @@ export class OrderManagerImpl
       return;
     }
 
-    const eventType =
-      snapshot.status === "filled"
-        ? "order.filled"
-        : snapshot.status === "rejected"
-          ? "order.rejected"
-          : snapshot.status === "canceled" || snapshot.status === "expired"
-            ? "order.canceled"
-            : "order.updated";
+    this.publishOrderEvent(accountId, venue, snapshot);
 
-    this.orderBus.publish({
-      type: eventType,
+    record.status = successfulStatus(record.status, {
+      preserveStatus: options.preserveStatus,
+      lastReceivedAt: snapshot.receivedAt,
+      lastReadyAt: snapshot.updatedAt,
+    });
+    this.publishStatus(record);
+  }
+
+  onPrivateOrderConfirmedMissing(
+    accountId: string,
+    venue: Venue,
+    order: OrderSnapshot,
+  ): void {
+    const record = this.getOrCreateRecord(accountId, venue);
+    if (!record.subscribed) {
+      return;
+    }
+
+    const location = getExistingSnapshotLocation(record, order);
+    if (!location || location.table !== "open") {
+      return;
+    }
+
+    const current = getSnapshotAtLocation(record, location);
+    if (!current || !isOpenOrder(current)) {
+      return;
+    }
+
+    const confirmations =
+      (record.missingOrderConfirmations.get(location.localOrderId) ?? 0) + 1;
+    if (confirmations < this.missingOrderEvictionThreshold) {
+      record.missingOrderConfirmations.set(
+        location.localOrderId,
+        confirmations,
+      );
+      return;
+    }
+
+    const receivedAt = this.context.now();
+    const snapshot = createSnapshot(
       accountId,
       venue,
-      symbol: snapshot.symbol,
-      snapshot,
-      ts: this.context.now(),
-    });
+      {
+        orderId: current.orderId,
+        clientOrderId: current.clientOrderId,
+        symbol: current.symbol,
+        side: current.side,
+        type: current.type,
+        status: "unknown",
+        price: current.price,
+        triggerPrice: current.triggerPrice,
+        amount: current.amount,
+        filled: current.filled,
+        remaining: current.remaining,
+        reduceOnly: current.reduceOnly,
+        positionSide: current.positionSide,
+        avgFillPrice: current.avgFillPrice,
+        receivedAt,
+      },
+      current,
+    );
+
+    if (
+      !this.writeSnapshot(record, location.localOrderId, snapshot, location)
+    ) {
+      return;
+    }
 
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        `Evicted ${venue} open order after ${confirmations} confirmed missing checks`,
+      ),
+      {
+        accountId,
+        venue,
+        symbol: current.symbol,
+      },
+    );
+    this.publishOrderEvent(accountId, venue, snapshot);
     record.status = successfulStatus(record.status, {
-      preserveStatus: options.preserveStatus,
       lastReceivedAt: snapshot.receivedAt,
       lastReadyAt: snapshot.updatedAt,
     });
     this.publishStatus(record);
   }
 
+  onPrivateOrderClaimNotFound(
+    accountId: string,
+    venue: Venue,
+    claim: ExpiredPendingOrderClaim,
+  ): void {
+    const record = this.records.get(accountId);
+    if (!record) {
+      return;
+    }
+
+    const pending = record.pendingClientOrderIdIndex.get(
+      claim.venueClientOrderId,
+    );
+    if (
+      pending?.localOrderId !== claim.localOrderId ||
+      pending.symbol !== claim.symbol
+    ) {
+      return;
+    }
+
+    record.pendingClientOrderIdIndex.delete(claim.venueClientOrderId);
+    this.context.publishRuntimeError(
+      "order",
+      new Error(
+        `createOrder timed out and the order was not found on the venue: ${claim.venueClientOrderId}`,
+      ),
+      {
+        accountId,
+        venue,
+        symbol: claim.symbol,
+      },
+    );
+  }
+
   onPrivateOrderStreamState(
     accountId: string,
     venue: Venue,
@@ -660,6 +807,7 @@ export class OrderManagerImpl
       orderIdOnlyIndex: new Map(),
       clientOrderIdIndex: new Map(),
       pendingClientOrderIdIndex: new Map(),
+      missingOrderConfirmations: new Map(),
       status: createOrderDataStatus(accountId, venue, "inactive"),
     };
 
@@ -708,9 +856,51 @@ export class OrderManagerImpl
 
     this.warnSystemClientOrderIdOnlyClaim(record, snapshot);
     this.warnProvisionalTerminalOrder(record, snapshot);
+    this.clearMissingOrderConfirmations(record, localOrderId);
     return true;
   }
 
+  private clearMissingOrderConfirmations(
+    record: OrderRecord,
+    localOrderId: string,
+  ): void {
+    record.missingOrderConfirmations.delete(localOrderId);
+  }
+
+  private clearMissingOrderConfirmationsForUpdate(
+    record: OrderRecord,
+    update: { symbol: string; orderId?: string; clientOrderId?: string },
+  ): void {
+    const location = getExistingSnapshotLocation(record, update);
+    if (location) {
+      this.clearMissingOrderConfirmations(record, location.localOrderId);
+    }
+  }
+
+  private publishOrderEvent(
+    accountId: string,
+    venue: Venue,
+    snapshot: OrderSnapshot,
+  ): void {
+    const eventType =
+      snapshot.status === "filled"
+        ? "order.filled"
+        : snapshot.status === "rejected"
+          ? "order.rejected"
+          : isOpenOrder(snapshot)
+            ? "order.updated"
+            : "order.canceled";
+
+    this.orderBus.publish({
+      type: eventType,
+      accountId,
+      venue,
+      symbol: snapshot.symbol,
+      snapshot,
+      ts: this.context.now(),
+    });
+  }
+
   private warnDroppedUnkeyedTerminalOrder(
     record: OrderRecord,
     snapshot: OrderSnapshot,
@@ -790,6 +980,9 @@ export class OrderManagerImpl
     options: { requestStartedAt?: number; preserveStatus?: boolean } = {},
   ): OrderSnapshot | undefined {
     const resolution = this.resolveLocalOrderIdForUpdate(record, update);
+    if (resolution.localOrderId) {
+      this.clearMissingOrderConfirmations(record, resolution.localOrderId);
+    }
     const localOrderId = resolution.localOrderId ?? this.generateLocalOrderId();
     const previousLocation = getLocationByLocalOrderId(record, localOrderId);
     const previous = previousLocation
@@ -864,6 +1057,7 @@ export class OrderManagerImpl
     record.pendingClientOrderIdIndex.set(venueClientOrderId, {
       localOrderId,
       symbol,
+      claimedAt: this.context.now(),
     });
   }
 
@@ -945,6 +1139,9 @@ export class OrderManagerImpl
       update,
       options.localOrderId,
     );
+    if (resolution.localOrderId) {
+      this.clearMissingOrderConfirmations(record, resolution.localOrderId);
+    }
     const localOrderId = resolution.localOrderId ?? this.generateLocalOrderId();
     const previousLocation = getLocationByLocalOrderId(record, localOrderId);
     const previous = previousLocation
@@ -990,12 +1187,7 @@ export class OrderManagerImpl
   }
 
   private createError(
-    code:
-      | "VENUE_NOT_SUPPORTED"
-      | "ORDER_CANCEL_ALL_FAILED"
-      | "ORDER_CANCEL_FAILED"
-      | "ORDER_CREATE_FAILED"
-      | "ORDER_INPUT_INVALID",
+    code: "VENUE_NOT_SUPPORTED" | OrderCommandErrorCode | "ORDER_INPUT_INVALID",
     message: string,
     metadata: {
       accountId: string;
@@ -1003,17 +1195,14 @@ export class OrderManagerImpl
       symbol?: string;
     },
   ): AcexError {
-    const details = buildAcexErrorDetails(metadata);
+    const details = this.buildOrderErrorDetails(code, metadata);
     const error = new AcexError(code, message, { details });
     this.context.publishRuntimeError("order", error, metadata);
     return error;
   }
 
   private wrapCommandError(
-    code:
-      | "ORDER_CANCEL_ALL_FAILED"
-      | "ORDER_CANCEL_FAILED"
-      | "ORDER_CREATE_FAILED",
+    code: OrderCommandErrorCode,
     message: string,
     error: unknown,
     metadata: {
@@ -1031,10 +1220,103 @@ export class OrderManagerImpl
       error instanceof Error ? error : new Error(message),
       metadata,
     );
-    const details = buildAcexErrorDetails(metadata, error);
+    const details = this.buildOrderErrorDetails(code, metadata, error);
     return new AcexError(code, formatAcexErrorMessage(message, details), {
       cause: error,
       details,
     });
   }
+
+  private buildOrderErrorDetails(
+    code: "VENUE_NOT_SUPPORTED" | OrderErrorCode,
+    metadata: {
+      accountId: string;
+      venue: Venue;
+      symbol?: string;
+    },
+    error?: unknown,
+  ): AcexErrorDetails | undefined {
+    const details = buildAcexErrorDetails(metadata, error);
+    if (!details || !isOrderErrorCode(code)) {
+      return details;
+    }
+
+    const detailsWithReason = this.addVenueErrorReason(metadata.venue, details);
+    return {
+      ...detailsWithReason,
+      orderState: getOrderState(code, detailsWithReason),
+    };
+  }
+
+  private addVenueErrorReason(
+    venue: Venue,
+    details: AcexErrorDetails,
+  ): AcexErrorDetails {
+    const venueErrorCode = details.venueError?.code;
+    if (!venueErrorCode) {
+      return details;
+    }
+
+    const reason = this.context.normalizeVenueErrorCode(venue, venueErrorCode);
+    if (!reason) {
+      return details;
+    }
+
+    return {
+      ...details,
+      venueError: {
+        ...details.venueError,
+        reason,
+      },
+    };
+  }
+}
+
+function isOrderErrorCode(
+  code: "VENUE_NOT_SUPPORTED" | OrderErrorCode,
+): code is OrderErrorCode {
+  return (
+    code === "ORDER_INPUT_INVALID" ||
+    code === "ORDER_CREATE_FAILED" ||
+    code === "ORDER_CANCEL_FAILED" ||
+    code === "ORDER_CANCEL_ALL_FAILED"
+  );
+}
+
+function getOrderState(
+  code: OrderErrorCode,
+  details: AcexErrorDetails,
+): OrderCommandOrderState {
+  if (code === "ORDER_INPUT_INVALID") {
+    return "not_placed";
+  }
+
+  const transport = details.transport;
+  if (!transport) {
+    return details.venueError ? "not_placed" : "unknown";
+  }
+
+  if (isUnknownOrderTransportKind(transport.kind)) {
+    return "unknown";
+  }
+  if (transport.kind === "rate_limited") {
+    return "not_placed";
+  }
+  if (transport.status !== undefined && transport.status >= 500) {
+    return "unknown";
+  }
+  if (details.venueError) {
+    return "not_placed";
+  }
+  if (transport.status !== undefined && transport.status < 500) {
+    return "not_placed";
+  }
+
+  return "unknown";
+}
+
+function isUnknownOrderTransportKind(
+  kind: AcexErrorTransportKind | undefined,
+): boolean {
+  return kind === "timeout" || kind === "network" || kind === "parse";
 }

package/src/types/order.ts

@@ -34,7 +34,8 @@ export type OrderStatus =
   | "filled"
   | "canceled"
   | "rejected"
-  | "expired";
+  | "expired"
+  | "unknown";
 
 export type CreateOrderType = "limit" | "market";
 

package/src/types/shared.ts

@@ -107,6 +107,8 @@ export interface AccountRuntimeOptions {
 
 export interface OrderRuntimeOptions {
   maxClosedOrdersPerSymbol?: number;
+  missingOrderEvictionThreshold?: number;
+  pendingClaimTtlMs?: number;
 }
 
 export interface CreateClientOptions {