@imbingox/acex 0.4.0-beta.13 → 0.4.0-beta.15

package/CHANGELOG.md

@@ -0,0 +1,182 @@
+# @imbingox/acex
+
+## 0.4.0-beta.15
+
+### Minor Changes
+
+- 3f6dcb8: 新增 `AcexError.details.venueError.reason`、订单命令错误的 `details.orderState`，并导出 `isOrderStateUnknown()`，方便调用方用稳定语义区分交易所拒单、限流、余额不足和订单状态未知场景。
+
+## 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

@@ -918,20 +918,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.13",
+  "version": "0.4.0-beta.15",
   "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",

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;

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";
@@ -312,6 +313,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-manager.ts

@@ -10,6 +10,7 @@ import type {
   PrivateOrderDataConsumer,
   PrivateSubscriptionState,
 } from "../client/context.ts";
+import type { AcexErrorDetails, AcexErrorTransportKind } from "../errors.ts";
 import {
   AcexError,
   buildAcexErrorDetails,
@@ -74,6 +75,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,
@@ -990,12 +1000,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 +1008,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 +1033,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";
 }