@imbingox/acex 0.4.0-beta.6 → 0.4.0-beta.8

package/docs/api.md

@@ -1458,8 +1458,30 @@ interface AcexInternalError {
   ts: number;
 }
 
+interface AcexErrorDetails {
+  venue?: Venue;
+  accountId?: string;
+  symbol?: string;
+  venueError?: {
+    code?: string;
+    message?: string;
+  };
+  transport?: {
+    kind?: "timeout" | "http" | "network" | "rate_limited" | "parse";
+    status?: number;
+    statusText?: string;
+    retryAfterMs?: number;
+    retryable?: boolean;
+    attempts?: number;
+    rawBody?: string;
+    url?: string;
+  };
+}
+
 class AcexError extends Error {
   readonly code: AcexErrorCode;
+  readonly details?: AcexErrorDetails;
+  readonly cause?: unknown;
 }
 ```
 
@@ -1475,10 +1497,23 @@ try {
 } catch (err) {
   if (err instanceof AcexError) {
     console.log(err.code, err.message);
+    console.log(err.details?.venueError?.code);
+    console.log(err.details?.venueError?.message);
   }
 }
 ```
 
+`details.venueError` 是下游读取交易所结构化拒绝原因的首选字段，例如 Binance 返回 `{ "code": -2010, "msg": "Order would immediately trigger." }` 时会映射为：
+
+```ts
+{
+  code: "-2010",
+  message: "Order would immediately trigger.",
+}
+```
+
+`details.transport` 保留已脱敏的 HTTP/transport 诊断信息，例如 `kind`、`status`、`retryAfterMs`、`attempts`、`rawBody`、`url`。`rawBody` 和 `url` 只用于排障兜底，不建议作为业务分支首选字段。market stream 首包超时时，`MARKET_STREAM_TIMEOUT` 会带 `details.venue` / `details.symbol` 和底层 `cause`，通常不填 `details.venueError`。`cause` 保留底层错误链，用于高级调试。
+
 完整错误码列表：
 
 | Code | 典型场景 |

package/package.json

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

package/src/adapters/binance/adapter.ts

@@ -3,6 +3,7 @@ import type {
   MarketDefinition,
   RateLimiter,
   VenueMarketCapabilities,
+  VenueServerTime,
 } from "../../types/index.ts";
 import type {
   FundingRateStreamCallbacks,
@@ -16,6 +17,7 @@ import {
   type BinanceMarketDefinition,
   loadBinanceMarkets,
 } from "./market-catalog.ts";
+import { fetchBinanceServerTime } from "./server-time.ts";
 import {
   type BinanceStreamDescriptor,
   type BinanceStreamMessage,
@@ -45,6 +47,7 @@ export class BinanceMarketAdapter implements MarketAdapter {
   readonly venue = "binance" as const;
   readonly marketCapabilities: VenueMarketCapabilities = {
     catalog: "supported",
+    serverTime: "supported",
     l1Book: "supported",
     fundingRate: "market_dependent",
     marketTypes: ["spot", "swap", "future"],
@@ -73,6 +76,12 @@ export class BinanceMarketAdapter implements MarketAdapter {
     return markets;
   }
 
+  async fetchServerTime(): Promise<VenueServerTime> {
+    return await fetchBinanceServerTime({
+      rateLimiter: this.options.rateLimiter,
+    });
+  }
+
   createL1BookStream(
     market: MarketDefinition,
     callbacks: L1BookStreamCallbacks,

package/src/adapters/binance/server-time.ts

@@ -0,0 +1,106 @@
+import {
+  type HttpClientMessages,
+  httpRequest,
+  isTransportError,
+} from "../../internal/http-client.ts";
+import type {
+  RateLimiter,
+  RateLimitScope,
+  VenueServerTime,
+} from "../../types/index.ts";
+import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
+
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+interface BinanceServerTimeResponse {
+  serverTime?: unknown;
+}
+
+export interface FetchBinanceServerTimeOptions {
+  readonly rateLimiter?: RateLimiter;
+  readonly fetchFn?: FetchLike;
+  readonly now?: () => number;
+  readonly monotonicNow?: () => number;
+}
+
+const BINANCE_USDM_SERVER_TIME_URL = "https://fapi.binance.com/fapi/v1/time";
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
+const BINANCE_SERVER_TIME_HTTP_MESSAGES: HttpClientMessages = {
+  http: ({ status, statusText }) =>
+    `Binance server time request failed: ${status} ${statusText ?? ""}`,
+};
+
+export async function fetchBinanceServerTime(
+  options: FetchBinanceServerTimeOptions = {},
+): Promise<VenueServerTime> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const now = options.now ?? Date.now;
+  const monotonicNow = options.monotonicNow ?? (() => performance.now());
+  const scope: RateLimitScope = {
+    venue: "binance",
+    endpointKey: "GET /fapi/v1/time",
+  };
+
+  await options.rateLimiter?.beforeRequest({ scope });
+
+  const requestSentAt = now();
+  const startMono = monotonicNow();
+
+  try {
+    const response = await httpRequest<BinanceServerTimeResponse>({
+      fetchFn,
+      url: BINANCE_USDM_SERVER_TIME_URL,
+      timeoutMs: DEFAULT_HTTP_TIMEOUT_MS,
+      parseAs: "json",
+      jsonParseMode: "response",
+      retryPolicy: {
+        idempotent: true,
+        maxAttempts: 1,
+      },
+      messages: BINANCE_SERVER_TIME_HTTP_MESSAGES,
+    });
+    const responseReceivedAt = now();
+    const endMono = monotonicNow();
+
+    await options.rateLimiter?.afterResponse(
+      { scope },
+      {
+        status: response.status,
+        headers: response.headers,
+        usage: parseBinanceRateLimitUsage(response.headers),
+      },
+    );
+
+    const { serverTime } = response.body;
+    if (typeof serverTime !== "number" || !Number.isFinite(serverTime)) {
+      throw new Error(
+        "Binance server time response missing numeric serverTime",
+      );
+    }
+
+    return {
+      serverTime,
+      requestSentAt,
+      responseReceivedAt,
+      roundTripMs: endMono - startMono,
+      estimatedOffsetMs: serverTime - (requestSentAt + responseReceivedAt) / 2,
+    };
+  } catch (error) {
+    if (isTransportError(error)) {
+      await options.rateLimiter?.onTransportError(
+        { scope },
+        {
+          status: error.status,
+          headers: error.headers,
+          retryAfterMs: error.retryAfterMs,
+          usage: parseBinanceRateLimitUsage(error.headers),
+        },
+      );
+    }
+
+    throw error;
+  }
+}

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

@@ -1,5 +1,4 @@
 import BigNumber from "bignumber.js";
-import { AcexError } from "../../errors.ts";
 import {
   type HttpClientMessages,
   httpRequest,
@@ -734,28 +733,21 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
     _credentials: AccountCredentials,
     _request: CreateOrderRequest,
   ): Promise<RawOrderUpdate> {
-    throw new AcexError(
-      "VENUE_NOT_SUPPORTED",
-      "Juplend is read-only and does not support createOrder",
-    );
+    throw new Error("Juplend is read-only and does not support createOrder");
   }
 
   cancelOrder(
     _credentials: AccountCredentials,
     _request: CancelOrderRequest,
   ): Promise<RawOrderUpdate> {
-    throw new AcexError(
-      "VENUE_NOT_SUPPORTED",
-      "Juplend is read-only and does not support cancelOrder",
-    );
+    throw new Error("Juplend is read-only and does not support cancelOrder");
   }
 
   cancelAllOrders(
     _credentials: AccountCredentials,
     _request: CancelAllOrdersRequest,
   ): Promise<RawOrderUpdate[]> {
-    throw new AcexError(
-      "VENUE_NOT_SUPPORTED",
+    throw new Error(
       "Juplend is read-only and does not support cancelAllOrders",
     );
   }

package/src/adapters/types.ts

@@ -9,6 +9,7 @@ import type {
   VenueAccountCapabilities,
   VenueMarketCapabilities,
   VenueOrderCapabilities,
+  VenueServerTime,
 } from "../types/index.ts";
 
 export interface StreamHandle {
@@ -74,6 +75,7 @@ export interface MarketAdapter {
   readonly venue: Venue;
   readonly marketCapabilities: VenueMarketCapabilities;
   loadMarkets(): Promise<MarketDefinition[]>;
+  fetchServerTime?(): Promise<VenueServerTime>;
   createL1BookStream(
     market: MarketDefinition,
     callbacks: L1BookStreamCallbacks,

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

@@ -2,8 +2,12 @@ import type {
   PrivateUserDataAdapter,
   StreamHandle,
 } from "../adapters/types.ts";
-import { AcexError } from "../errors.ts";
-import { isTransportError, redactSecrets } from "../internal/http-client.ts";
+import {
+  AcexError,
+  buildAcexErrorDetails,
+  formatAcexErrorMessage,
+} from "../errors.ts";
+import { isTransportError } from "../internal/http-client.ts";
 import type {
   AccountRuntimeOptions,
   PrivateRuntimeReason,
@@ -55,14 +59,6 @@ function transportReason(
     : fallback;
 }
 
-function bootstrapErrorDetail(error: unknown): string {
-  if (!(error instanceof Error) || !error.message) {
-    return "";
-  }
-
-  return ` (${redactSecrets(error.message)})`;
-}
-
 export class PrivateSubscriptionCoordinator {
   private readonly context: ClientContext;
   private readonly adapters: Map<Venue, PrivateUserDataAdapter>;
@@ -260,6 +256,7 @@ export class PrivateSubscriptionCoordinator {
       throw new AcexError(
         "VENUE_NOT_SUPPORTED",
         `Venue is not supported yet: ${account.venue}`,
+        { details: buildAcexErrorDetails({ venue: account.venue }) },
       );
     }
 
@@ -272,6 +269,7 @@ export class PrivateSubscriptionCoordinator {
       throw new AcexError(
         "VENUE_NOT_SUPPORTED",
         `Venue is not supported yet: ${venue}`,
+        { details: buildAcexErrorDetails({ venue }) },
       );
     }
 
@@ -503,6 +501,12 @@ export class PrivateSubscriptionCoordinator {
       throw new AcexError(
         "CREDENTIALS_MISSING",
         `Account credentials are required for private subscriptions: ${account.accountId}`,
+        {
+          details: buildAcexErrorDetails({
+            accountId: account.accountId,
+            venue: account.venue,
+          }),
+        },
       );
     }
 
@@ -716,10 +720,23 @@ export class PrivateSubscriptionCoordinator {
           ),
         },
       );
-      const reason = bootstrapErrorDetail(error);
+      const details = buildAcexErrorDetails(
+        {
+          accountId: record.accountId,
+          venue: record.venue,
+        },
+        error,
+      );
       throw new AcexError(
         "ACCOUNT_BOOTSTRAP_FAILED",
-        `Failed to bootstrap account data: ${record.accountId}${reason}`,
+        formatAcexErrorMessage(
+          `Failed to bootstrap account data: ${record.accountId}`,
+          details,
+        ),
+        {
+          cause: error,
+          details,
+        },
       );
     }
   }
@@ -766,9 +783,23 @@ export class PrivateSubscriptionCoordinator {
           reason: transportReason(error, "auth_failed"),
         },
       );
+      const details = buildAcexErrorDetails(
+        {
+          accountId: record.accountId,
+          venue: record.venue,
+        },
+        error,
+      );
       throw new AcexError(
         "ORDER_BOOTSTRAP_FAILED",
-        `Failed to bootstrap order data: ${record.accountId}`,
+        formatAcexErrorMessage(
+          `Failed to bootstrap order data: ${record.accountId}`,
+          details,
+        ),
+        {
+          cause: error,
+          details,
+        },
       );
     }
   }

package/src/client/runtime.ts

@@ -9,7 +9,11 @@ import type {
   PrivateUserDataAdapter,
   RawOrderUpdate,
 } from "../adapters/types.ts";
-import { AcexError, type AcexErrorCode } from "../errors.ts";
+import {
+  AcexError,
+  type AcexErrorCode,
+  buildAcexErrorDetails,
+} from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { matchesHealthFilter } from "../internal/filters.ts";
 import { ReactiveRateLimiter } from "../internal/rate-limiter.ts";
@@ -431,7 +435,9 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     message: string,
     metadata?: Omit<AcexInternalError, "error" | "source" | "ts">,
   ): AcexError {
-    const error = new AcexError(code, message);
+    const error = new AcexError(code, message, {
+      details: buildAcexErrorDetails(metadata),
+    });
     this.errorBus.publish({
       source: "client",
       ts: this.now(),

package/src/client/venue-capabilities.ts

@@ -42,6 +42,7 @@ const typeOnlyNotes = [
 
 const unsupportedMarket: VenueMarketCapabilities = {
   catalog: "unsupported",
+  serverTime: "unsupported",
   l1Book: "unsupported",
   fundingRate: "unsupported",
   marketTypes: [],

package/src/errors.ts

@@ -1,3 +1,6 @@
+import { isTransportError } from "./internal/http-client.ts";
+import type { Venue } from "./types/shared.ts";
+
 export type AcexErrorCode =
   | "ACCOUNT_ALREADY_EXISTS"
   | "ACCOUNT_BOOTSTRAP_FAILED"
@@ -6,6 +9,7 @@ export type AcexErrorCode =
   | "CREDENTIALS_MISSING"
   | "VENUE_NOT_SUPPORTED"
   | "MARKET_CATALOG_LOAD_FAILED"
+  | "MARKET_SERVER_TIME_FETCH_FAILED"
   | "MARKET_INACTIVE"
   | "MARKET_FUNDING_RATE_UNSUPPORTED"
   | "MARKET_NOT_FOUND"
@@ -16,12 +20,162 @@ export type AcexErrorCode =
   | "ORDER_CREATE_FAILED"
   | "ORDER_INPUT_INVALID";
 
+export type AcexErrorTransportKind =
+  | "timeout"
+  | "http"
+  | "network"
+  | "rate_limited"
+  | "parse";
+
+export interface AcexVenueErrorDetails {
+  readonly code?: string;
+  readonly message?: string;
+}
+
+export interface AcexErrorTransportDetails {
+  readonly kind?: AcexErrorTransportKind;
+  readonly status?: number;
+  readonly statusText?: string;
+  readonly retryAfterMs?: number;
+  readonly retryable?: boolean;
+  readonly attempts?: number;
+  readonly rawBody?: string;
+  readonly url?: string;
+}
+
+export interface AcexErrorDetails {
+  readonly venue?: Venue;
+  readonly accountId?: string;
+  readonly symbol?: string;
+  readonly venueError?: AcexVenueErrorDetails;
+  readonly transport?: AcexErrorTransportDetails;
+}
+
+export interface AcexErrorOptions {
+  readonly cause?: unknown;
+  readonly details?: AcexErrorDetails;
+}
+
 export class AcexError extends Error {
   readonly code: AcexErrorCode;
+  readonly details?: AcexErrorDetails;
+  override readonly cause?: unknown;
 
-  constructor(code: AcexErrorCode, message: string) {
-    super(message);
+  constructor(
+    code: AcexErrorCode,
+    message: string,
+    options: AcexErrorOptions = {},
+  ) {
+    super(message, { cause: options.cause });
     this.name = "AcexError";
     this.code = code;
+    this.details = options.details;
+    this.cause = options.cause;
+  }
+}
+
+export function buildAcexErrorDetails(
+  context?: Pick<AcexErrorDetails, "venue" | "accountId" | "symbol">,
+  cause?: unknown,
+): AcexErrorDetails | undefined {
+  const transport = buildTransportDetails(cause);
+  const venueError = parseVenueErrorDetails(transport?.rawBody);
+  const details: AcexErrorDetails = {
+    venue: context?.venue,
+    accountId: context?.accountId,
+    symbol: context?.symbol,
+    venueError,
+    transport,
+  };
+
+  return hasDetails(details) ? details : undefined;
+}
+
+export function formatAcexErrorMessage(
+  message: string,
+  details?: AcexErrorDetails,
+): string {
+  const venueErrorMessage = details?.venueError?.message?.trim();
+  if (!venueErrorMessage) {
+    return message;
+  }
+
+  const venue = details?.venue;
+  const venueLabel = venue ? formatVenueLabel(venue) : "Exchange";
+  return `${message} (${venueLabel} rejected: ${venueErrorMessage})`;
+}
+
+function buildTransportDetails(
+  cause: unknown,
+): AcexErrorTransportDetails | undefined {
+  if (!isTransportError(cause)) {
+    return undefined;
+  }
+
+  return pruneUndefined({
+    kind: cause.kind,
+    status: cause.status,
+    statusText: cause.statusText,
+    retryAfterMs: cause.retryAfterMs,
+    retryable: cause.retryable,
+    attempts: cause.attempts,
+    rawBody: cause.rawBody,
+    url: cause.url,
+  });
+}
+
+function parseVenueErrorDetails(
+  rawBody: string | undefined,
+): AcexVenueErrorDetails | undefined {
+  if (!rawBody) {
+    return undefined;
   }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return undefined;
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return undefined;
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const code = record.code;
+  const message = record.msg ?? record.message;
+
+  if (
+    (typeof code !== "string" && typeof code !== "number") ||
+    typeof message !== "string" ||
+    message.trim() === ""
+  ) {
+    return undefined;
+  }
+
+  return {
+    code: String(code),
+    message,
+  };
+}
+
+function hasDetails(details: AcexErrorDetails): boolean {
+  return Boolean(
+    details.venue ||
+      details.accountId ||
+      details.symbol ||
+      details.venueError ||
+      details.transport,
+  );
+}
+
+function formatVenueLabel(venue: Venue): string {
+  return `${venue.charAt(0).toUpperCase()}${venue.slice(1)}`;
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(input: T): T {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, value]) => value !== undefined),
+  ) as T;
 }

package/src/index.ts

@@ -1,5 +1,12 @@
 export { BigNumber } from "bignumber.js";
 export { createClient } from "./client/create-client.ts";
-export type { AcexErrorCode } from "./errors.ts";
+export type {
+  AcexErrorCode,
+  AcexErrorDetails,
+  AcexErrorOptions,
+  AcexErrorTransportDetails,
+  AcexErrorTransportKind,
+  AcexVenueErrorDetails,
+} from "./errors.ts";
 export { AcexError } from "./errors.ts";
 export * from "./types/index.ts";

package/src/managers/market-manager.ts

@@ -14,7 +14,11 @@ import type {
   HealthReporter,
   ManagerLifecycle,
 } from "../client/context.ts";
-import { AcexError } from "../errors.ts";
+import {
+  AcexError,
+  buildAcexErrorDetails,
+  formatAcexErrorMessage,
+} from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { toCanonical } from "../internal/decimal.ts";
 import { matchesMarketFilter } from "../internal/filters.ts";
@@ -38,6 +42,7 @@ import type {
   SubscribeL1BookInput,
   SubscriptionActivity,
   Venue,
+  VenueServerTime,
 } from "../types/index.ts";
 
 export interface MarketManagerOptions {
@@ -201,6 +206,24 @@ export class MarketManagerImpl
     return summaries;
   }
 
+  async fetchServerTime(venue: Venue): Promise<VenueServerTime> {
+    const adapter = this.getMarketAdapter(venue);
+    if (!adapter.fetchServerTime) {
+      throw this.createError(
+        "VENUE_NOT_SUPPORTED",
+        `Venue is not supported yet: ${venue}`,
+        { venue },
+        "client",
+      );
+    }
+
+    try {
+      return await adapter.fetchServerTime();
+    } catch (error) {
+      throw this.createServerTimeFetchError(venue, error);
+    }
+  }
+
   async subscribeL1Book(input: SubscribeL1BookInput): Promise<void> {
     this.context.assertStarted();
     const market = await this.resolveMarketDefinition(input);
@@ -587,9 +610,17 @@ export class MarketManagerImpl
   }
 
   private createCatalogLoadError(venue: Venue, error: unknown): AcexError {
+    const details = buildAcexErrorDetails({ venue }, error);
     const wrapped = new AcexError(
       "MARKET_CATALOG_LOAD_FAILED",
-      `Failed to load market catalog from ${venue}`,
+      formatAcexErrorMessage(
+        `Failed to load market catalog from ${venue}`,
+        details,
+      ),
+      {
+        cause: error,
+        details,
+      },
     );
     this.context.publishRuntimeError(
       "adapter",
@@ -601,6 +632,29 @@ export class MarketManagerImpl
     return wrapped;
   }
 
+  private createServerTimeFetchError(venue: Venue, error: unknown): AcexError {
+    const details = buildAcexErrorDetails({ venue }, error);
+    const wrapped = new AcexError(
+      "MARKET_SERVER_TIME_FETCH_FAILED",
+      formatAcexErrorMessage(
+        `Failed to fetch server time from ${venue}`,
+        details,
+      ),
+      {
+        cause: error,
+        details,
+      },
+    );
+    this.context.publishRuntimeError(
+      "adapter",
+      error instanceof Error
+        ? error
+        : new Error("Unknown server time fetch failure"),
+      { venue },
+    );
+    return wrapped;
+  }
+
   private async resolveMarketDefinition(input: {
     venue: Venue;
     symbol: string;
@@ -724,11 +778,20 @@ export class MarketManagerImpl
 
     try {
       await record.l1BookStream.ready;
-    } catch {
+    } catch (error) {
+      record.l1BookStream.close();
       record.l1BookStream = undefined;
+      const details = buildAcexErrorDetails(
+        { venue: market.venue, symbol: market.symbol },
+        error,
+      );
       const timeoutError = new AcexError(
         "MARKET_STREAM_TIMEOUT",
         `Timed out waiting for market data: ${market.symbol}`,
+        {
+          cause: error,
+          details,
+        },
       );
       this.context.publishRuntimeError("runtime", timeoutError, {
         venue: market.venue,
@@ -752,11 +815,20 @@ export class MarketManagerImpl
 
     try {
       await record.fundingRateStream.ready;
-    } catch {
+    } catch (error) {
+      record.fundingRateStream.close();
       record.fundingRateStream = undefined;
+      const details = buildAcexErrorDetails(
+        { venue: market.venue, symbol: market.symbol },
+        error,
+      );
       const timeoutError = new AcexError(
         "MARKET_STREAM_TIMEOUT",
         `Timed out waiting for market data: ${market.symbol}`,
+        {
+          cause: error,
+          details,
+        },
       );
       this.context.publishRuntimeError("runtime", timeoutError, {
         venue: market.venue,
@@ -1155,7 +1227,9 @@ export class MarketManagerImpl
     metadata?: { venue?: Venue; symbol?: string },
     source: "market" | "client" = "market",
   ): AcexError {
-    const error = new AcexError(code, message);
+    const error = new AcexError(code, message, {
+      details: buildAcexErrorDetails(metadata),
+    });
     this.context.publishRuntimeError(source, error, metadata);
     return error;
   }

package/src/managers/order-manager.ts

@@ -8,7 +8,11 @@ import type {
   PrivateOrderDataConsumer,
   PrivateSubscriptionState,
 } from "../client/context.ts";
-import { AcexError } from "../errors.ts";
+import {
+  AcexError,
+  buildAcexErrorDetails,
+  formatAcexErrorMessage,
+} from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { toCanonical } from "../internal/decimal.ts";
 import { matchesOrderFilter } from "../internal/filters.ts";
@@ -656,7 +660,8 @@ export class OrderManagerImpl
       symbol?: string;
     },
   ): AcexError {
-    const error = new AcexError(code, message);
+    const details = buildAcexErrorDetails(metadata);
+    const error = new AcexError(code, message, { details });
     this.context.publishRuntimeError("order", error, metadata);
     return error;
   }
@@ -683,6 +688,10 @@ export class OrderManagerImpl
       error instanceof Error ? error : new Error(message),
       metadata,
     );
-    return new AcexError(code, message);
+    const details = buildAcexErrorDetails(metadata, error);
+    return new AcexError(code, formatAcexErrorMessage(message, details), {
+      cause: error,
+      details,
+    });
   }
 }

package/src/types/client.ts

@@ -83,6 +83,7 @@ export type OrderTimeInForceCapability = "gtc" | "post_only";
 
 export interface VenueMarketCapabilities {
   catalog: VenueCapabilitySupport;
+  serverTime: VenueCapabilitySupport;
   l1Book: VenueCapabilitySupport;
   fundingRate: FundingRateCapability;
   marketTypes: MarketType[];

package/src/types/market.ts

@@ -36,6 +36,19 @@ export interface MarketCatalogReloadSummary {
   error?: AcexError;
 }
 
+export interface VenueServerTime {
+  /** Exchange server time in epoch milliseconds. Binance currently measures the USDM cluster. */
+  serverTime: number;
+  /** Local wall-clock timestamp captured immediately before the HTTP request is sent. */
+  requestSentAt: number;
+  /** Local wall-clock timestamp captured immediately after the HTTP response is received. */
+  responseReceivedAt: number;
+  /** Round trip duration measured with a monotonic clock, in milliseconds. */
+  roundTripMs: number;
+  /** NTP-style offset estimate: serverTime - midpoint(requestSentAt, responseReceivedAt). */
+  estimatedOffsetMs: number;
+}
+
 export interface MarketDataStatus {
   venue: Venue;
   symbol: string;
@@ -170,6 +183,7 @@ export interface MarketManager {
 
   loadMarkets(): Promise<void>;
   reloadMarkets(venue?: Venue): Promise<MarketCatalogReloadSummary[]>;
+  fetchServerTime(venue: Venue): Promise<VenueServerTime>;
   subscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   unsubscribeL1Book(input: SubscribeL1BookInput): Promise<void>;
   subscribeFundingRate(input: SubscribeFundingRateInput): Promise<void>;