@imbingox/acex 0.4.0-beta.1 → 0.4.0-beta.3

package/package.json

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

package/src/adapters/binance/market-catalog.ts

@@ -1,4 +1,8 @@
 import { toCanonical } from "../../internal/decimal.ts";
+import {
+  type HttpClientMessages,
+  httpRequest,
+} from "../../internal/http-client.ts";
 import type { MarketDefinition, MarketType } from "../../types/index.ts";
 
 type FetchLike = typeof fetch;
@@ -54,6 +58,11 @@ const BINANCE_USDM_EXCHANGE_INFO_URL =
   "https://fapi.binance.com/fapi/v1/exchangeInfo";
 const BINANCE_COINM_EXCHANGE_INFO_URL =
   "https://dapi.binance.com/dapi/v1/exchangeInfo";
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
+const BINANCE_CATALOG_HTTP_MESSAGES: HttpClientMessages = {
+  http: ({ status, statusText }) =>
+    `Binance request failed: ${status} ${statusText ?? ""}`,
+};
 
 function toRecord(value: unknown): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -212,15 +221,24 @@ function normalizeDerivativesSymbol(
   };
 }
 
-async function fetchJson<T>(fetchFn: FetchLike, url: string): Promise<T> {
-  const response = await fetchFn(url);
-  if (!response.ok) {
-    throw new Error(
-      `Binance request failed: ${response.status} ${response.statusText}`,
-    );
-  }
+async function requestCatalogJson<T>(
+  fetchFn: FetchLike,
+  url: string,
+): Promise<T> {
+  const response = await httpRequest<T>({
+    fetchFn,
+    url,
+    timeoutMs: DEFAULT_HTTP_TIMEOUT_MS,
+    parseAs: "json",
+    jsonParseMode: "response",
+    retryPolicy: {
+      idempotent: true,
+      maxAttempts: 3,
+    },
+    messages: BINANCE_CATALOG_HTTP_MESSAGES,
+  });
 
-  return (await response.json()) as T;
+  return response.body;
 }
 
 function sortMarkets(
@@ -235,12 +253,15 @@ export async function loadBinanceMarkets(
   fetchFn: FetchLike = fetch,
 ): Promise<BinanceMarketDefinition[]> {
   const [spot, usdm, coinm] = await Promise.all([
-    fetchJson<BinanceSpotExchangeInfo>(fetchFn, BINANCE_SPOT_EXCHANGE_INFO_URL),
-    fetchJson<BinanceDerivativesExchangeInfo>(
+    requestCatalogJson<BinanceSpotExchangeInfo>(
+      fetchFn,
+      BINANCE_SPOT_EXCHANGE_INFO_URL,
+    ),
+    requestCatalogJson<BinanceDerivativesExchangeInfo>(
       fetchFn,
       BINANCE_USDM_EXCHANGE_INFO_URL,
     ),
-    fetchJson<BinanceDerivativesExchangeInfo>(
+    requestCatalogJson<BinanceDerivativesExchangeInfo>(
       fetchFn,
       BINANCE_COINM_EXCHANGE_INFO_URL,
     ),

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

@@ -1,9 +1,15 @@
 import { createHmac } from "node:crypto";
 import BigNumber from "bignumber.js";
+import {
+  type HttpClientMessages,
+  type HttpRetryPolicy,
+  httpRequest,
+} from "../../internal/http-client.ts";
 import { createManagedWebSocket } from "../../internal/managed-websocket.ts";
 import type {
   AccountCredentials,
   PositionSide,
+  TimeProvider,
   VenueAccountCapabilities,
   VenueOrderCapabilities,
 } from "../../types/index.ts";
@@ -25,6 +31,7 @@ import type {
 
 type TimerHandle = ReturnType<typeof setInterval>;
 type SignedRequestMethod = "GET" | "POST" | "DELETE";
+type FetchLike = typeof fetch;
 
 interface BinancePapiBalance {
   asset?: string;
@@ -144,7 +151,31 @@ type BinancePrivateMessage =
 const BINANCE_PAPI_REST_BASE_URL = "https://papi.binance.com";
 const BINANCE_PAPI_WS_BASE_URL = "wss://fstream.binance.com/pm/ws";
 const DEFAULT_RECV_WINDOW = 5_000;
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
 const USDM_QUOTE_ASSETS = ["FDUSD", "USDC", "BUSD", "USDT"];
+const SAFE_READ_RETRY_POLICY: HttpRetryPolicy = {
+  idempotent: true,
+  maxAttempts: 3,
+};
+const NO_RETRY_POLICY: HttpRetryPolicy = {
+  idempotent: false,
+  maxAttempts: 1,
+};
+const LISTEN_KEY_KEEPALIVE_RETRY_POLICY: HttpRetryPolicy = {
+  idempotent: true,
+  maxAttempts: 3,
+};
+function getBinancePapiHttpMessages(timeoutMs: number): HttpClientMessages {
+  return {
+    http: ({ status, statusText, url, rawBody }) =>
+      `Binance PAPI request failed: ${status} ${statusText ?? ""} ${url}${
+        rawBody ? ` ${rawBody}` : ""
+      }`,
+    timeout: () => `Binance PAPI fetch timeout after ${timeoutMs}ms`,
+    aborted: () => "Binance PAPI fetch aborted",
+    parse: ({ url }) => `Binance PAPI response parse failed: ${url}`,
+  };
+}
 
 function requirePrivateCredentials(credentials: AccountCredentials): {
   apiKey: string;
@@ -521,21 +552,6 @@ function mapOrderUpdate(
   };
 }
 
-async function readJson<T>(response: Response, url: string): Promise<T> {
-  const text = await response.text();
-  if (!response.ok) {
-    throw new Error(
-      `Binance PAPI request failed: ${response.status} ${response.statusText} ${url} ${text}`,
-    );
-  }
-
-  if (!text) {
-    return {} as T;
-  }
-
-  return JSON.parse(text) as T;
-}
-
 export class BinancePrivateAdapter implements PrivateUserDataAdapter {
   readonly venue = "binance" as const;
   readonly readOnly = false;
@@ -569,6 +585,14 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     clientOrderId: true,
   };
 
+  constructor(
+    private readonly options: {
+      readonly fetchFn?: FetchLike;
+      readonly httpTimeoutMs?: number;
+      readonly signingClock?: TimeProvider;
+    } = {},
+  ) {}
+
   async bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
@@ -580,18 +604,24 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         "/papi/v1/balance",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
       this.signedRequest<BinancePapiAccount>(
         "GET",
         "/papi/v1/account",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
       this.signedRequest<BinancePapiUmPosition[]>(
         "GET",
         "/papi/v1/um/positionRisk",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
     ]);
 
@@ -621,12 +651,16 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         "/papi/v1/account",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
       this.signedRequest<BinancePapiUmPosition[]>(
         "GET",
         "/papi/v1/um/positionRisk",
         credentials,
         accountOptions,
+        undefined,
+        SAFE_READ_RETRY_POLICY,
       ),
     ]);
 
@@ -643,6 +677,8 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "/papi/v1/um/openOrders",
       credentials,
       accountOptions,
+      undefined,
+      SAFE_READ_RETRY_POLICY,
     );
 
     return orders.flatMap((order) => {
@@ -681,6 +717,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
             : `${request.reduceOnly}`,
         positionSide: encodePositionSide(request.positionSide),
       },
+      NO_RETRY_POLICY,
     );
 
     const mapped = mapOpenOrder(response, receivedAt);
@@ -709,6 +746,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         orderId: request.orderId,
         origClientOrderId: request.clientOrderId,
       },
+      NO_RETRY_POLICY,
     );
 
     const mapped = mapOpenOrder(response, receivedAt);
@@ -735,6 +773,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       {
         symbol: encodeUmSymbol(request.symbol),
       },
+      NO_RETRY_POLICY,
     );
 
     return responses.flatMap((response) => {
@@ -863,6 +902,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
     queryParams?: Record<string, string | undefined>,
+    retryPolicy?: HttpRetryPolicy,
   ): Promise<T> {
     const { apiKey, secret } = requirePrivateCredentials(credentials);
     const params = new URLSearchParams();
@@ -873,7 +913,11 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     }
     params.set(
       "timestamp",
-      `${getNumberOption(accountOptions, "timestamp") ?? Date.now()}`,
+      `${
+        getNumberOption(accountOptions, "timestamp") ??
+        this.options.signingClock?.now() ??
+        Date.now()
+      }`,
     );
     params.set(
       "recvWindow",
@@ -882,14 +926,22 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     params.set("signature", signQuery(params.toString(), secret));
 
     const url = `${BINANCE_PAPI_REST_BASE_URL}${path}?${params.toString()}`;
-    const response = await fetch(url, {
+    const timeoutMs = this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    const response = await httpRequest<T>({
+      fetchFn: this.options.fetchFn,
+      url,
       method,
       headers: {
         "X-MBX-APIKEY": apiKey,
       },
+      timeoutMs,
+      parseAs: "json",
+      emptyBody: "empty_object",
+      retryPolicy: retryPolicy ?? NO_RETRY_POLICY,
+      messages: getBinancePapiHttpMessages(timeoutMs),
     });
 
-    return readJson<T>(response, url);
+    return response.body;
   }
 
   private async startUserDataStream(
@@ -898,6 +950,8 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     const response = await this.userStreamRequest<BinanceListenKeyResponse>(
       "POST",
       credentials,
+      undefined,
+      NO_RETRY_POLICY,
     );
     if (!response.listenKey) {
       throw new Error("Binance PAPI did not return a listenKey");
@@ -914,6 +968,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "PUT",
       credentials,
       listenKey,
+      LISTEN_KEY_KEEPALIVE_RETRY_POLICY,
     );
   }
 
@@ -925,6 +980,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "DELETE",
       credentials,
       listenKey,
+      NO_RETRY_POLICY,
     );
   }
 
@@ -932,6 +988,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     method: "POST" | "PUT" | "DELETE",
     credentials: AccountCredentials,
     listenKey?: string,
+    retryPolicy: HttpRetryPolicy = NO_RETRY_POLICY,
   ): Promise<T> {
     const { apiKey } = requirePrivateCredentials(credentials);
     const params = new URLSearchParams();
@@ -943,13 +1000,21 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     const url = `${BINANCE_PAPI_REST_BASE_URL}/papi/v1/listenKey${
       query ? `?${query}` : ""
     }`;
-    const response = await fetch(url, {
+    const timeoutMs = this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    const response = await httpRequest<T>({
+      fetchFn: this.options.fetchFn,
+      url,
       method,
       headers: {
         "X-MBX-APIKEY": apiKey,
       },
+      timeoutMs,
+      parseAs: "json",
+      emptyBody: "empty_object",
+      retryPolicy,
+      messages: getBinancePapiHttpMessages(timeoutMs),
     });
 
-    return readJson<T>(response, url);
+    return response.body;
   }
 }

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

@@ -1,5 +1,9 @@
 import BigNumber from "bignumber.js";
 import { AcexError } from "../../errors.ts";
+import {
+  type HttpClientMessages,
+  httpRequest,
+} from "../../internal/http-client.ts";
 import type {
   AccountCredentials,
   VenueAccountCapabilities,
@@ -66,6 +70,8 @@ interface JuplendPriceApiEntry {
   decimals?: number | string;
 }
 
+type FetchLike = typeof fetch;
+
 interface JuplendTokenSearchEntry {
   id?: string;
   address?: string;
@@ -86,6 +92,13 @@ const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
 // not mint-atomic token amounts.
 const POSITION_AMOUNT_SCALE_DECIMALS = 9;
 const VAULT_CACHE_TTL_MS = 60 * 60 * 1_000;
+function getJuplendHttpMessages(timeoutMs: number): HttpClientMessages {
+  return {
+    http: ({ status, statusText }) => `Juplend HTTP ${status}: ${statusText}`,
+    timeout: () => `Juplend fetch timeout after ${timeoutMs}ms`,
+    aborted: () => "Juplend fetch aborted",
+  };
+}
 
 interface JuplendVaultEnrichmentCacheEntry {
   loadedAt: number;
@@ -260,52 +273,30 @@ function buildRisk(input: {
   };
 }
 
-async function readJson<T>(url: string, init?: RequestInit): Promise<T> {
-  const controller = new AbortController();
-  const upstreamSignal = init?.signal;
-  let timedOut = false;
-  const onUpstreamAbort = () => {
-    controller.abort();
-  };
-
-  if (upstreamSignal?.aborted) {
-    controller.abort();
-  } else if (upstreamSignal) {
-    upstreamSignal.addEventListener("abort", onUpstreamAbort, { once: true });
-  }
-
-  const timeout = setTimeout(() => {
-    timedOut = true;
-    controller.abort();
-  }, DEFAULT_HTTP_TIMEOUT_MS);
-
-  try {
-    const response = await fetch(url, {
-      ...init,
-      signal: controller.signal,
-    });
-    if (!response.ok) {
-      throw new Error(
-        `Juplend HTTP ${response.status}: ${response.statusText}`,
-      );
-    }
+async function requestJuplendJson<T>(
+  url: string,
+  init: RequestInit | undefined,
+  fetchFn: FetchLike | undefined,
+  timeoutMs: number,
+): Promise<T> {
+  const response = await httpRequest<T>({
+    fetchFn,
+    url,
+    method: init?.method,
+    headers: init?.headers,
+    body: init?.body,
+    signal: init?.signal ?? undefined,
+    timeoutMs,
+    parseAs: "json",
+    jsonParseMode: "response",
+    retryPolicy: {
+      idempotent: true,
+      maxAttempts: 3,
+    },
+    messages: getJuplendHttpMessages(timeoutMs),
+  });
 
-    return (await response.json()) as T;
-  } catch (error) {
-    if (error instanceof Error && error.name === "AbortError") {
-      throw new Error(
-        timedOut
-          ? `Juplend fetch timeout after ${DEFAULT_HTTP_TIMEOUT_MS}ms`
-          : "Juplend fetch aborted",
-      );
-    }
-    throw error;
-  } finally {
-    clearTimeout(timeout);
-    if (upstreamSignal) {
-      upstreamSignal.removeEventListener("abort", onUpstreamAbort);
-    }
-  }
+  return response.body;
 }
 
 function getJupApiKey(explicitApiKey?: string): string | undefined {
@@ -326,12 +317,19 @@ function withBaseUrl(baseUrl: string, path: string): string {
 
 async function loadVaultMetadataFromLiteApi(
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendVaultMetadata>> {
-  const response = await readJson<
+  const response = await requestJuplendJson<
     JuplendVaultMetadata[] | { data?: JuplendVaultMetadata[] }
-  >(withBaseUrl(JUP_LITE_API_BASE_URL, LEND_VAULTS_PATH), {
-    headers: buildApiHeaders(apiKey),
-  });
+  >(
+    withBaseUrl(JUP_LITE_API_BASE_URL, LEND_VAULTS_PATH),
+    {
+      headers: buildApiHeaders(apiKey),
+    },
+    fetchFn,
+    timeoutMs,
+  );
   const rawVaults = Array.isArray(response) ? response : response.data;
   const vaults = new Map<string, JuplendVaultMetadata>();
 
@@ -348,17 +346,21 @@ async function loadVaultMetadataFromLiteApi(
 async function loadTokenSearchMap(
   mintAddresses: string[],
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendTokenMetadata>> {
   if (mintAddresses.length === 0) {
     return new Map();
   }
 
   const query = encodeURIComponent(mintAddresses.join(","));
-  const response = await readJson<JuplendTokenSearchEntry[]>(
+  const response = await requestJuplendJson<JuplendTokenSearchEntry[]>(
     `${withBaseUrl(JUP_API_BASE_URL, TOKENS_SEARCH_PATH)}?query=${query}`,
     {
       headers: buildApiHeaders(apiKey),
     },
+    fetchFn,
+    timeoutMs,
   );
 
   const tokens = new Map<string, JuplendTokenMetadata>();
@@ -385,17 +387,23 @@ async function loadTokenSearchMap(
 async function loadPriceMap(
   mintAddresses: string[],
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendPriceApiEntry>> {
   if (mintAddresses.length === 0) {
     return new Map();
   }
 
   const ids = encodeURIComponent(mintAddresses.join(","));
-  const response = await readJson<Record<string, JuplendPriceApiEntry>>(
+  const response = await requestJuplendJson<
+    Record<string, JuplendPriceApiEntry>
+  >(
     `${withBaseUrl(JUP_API_BASE_URL, PRICE_V3_PATH)}?ids=${ids}`,
     {
       headers: buildApiHeaders(apiKey),
     },
+    fetchFn,
+    timeoutMs,
   );
 
   return new Map(Object.entries(response ?? {}));
@@ -436,6 +444,8 @@ function mergeTokenMetadata(
 async function enrichVaultsWithJupApi(input: {
   apiKey?: string;
   baseVaults: Map<string, JuplendVaultMetadata>;
+  fetchFn?: FetchLike;
+  timeoutMs: number;
 }): Promise<Map<string, JuplendVaultMetadata>> {
   const mintAddresses = new Set<string>();
   for (const vault of input.baseVaults.values()) {
@@ -450,8 +460,18 @@ async function enrichVaultsWithJupApi(input: {
   }
 
   const [tokenMap, priceMap] = await Promise.all([
-    loadTokenSearchMap([...mintAddresses], input.apiKey),
-    loadPriceMap([...mintAddresses], input.apiKey),
+    loadTokenSearchMap(
+      [...mintAddresses],
+      input.apiKey,
+      input.fetchFn,
+      input.timeoutMs,
+    ),
+    loadPriceMap(
+      [...mintAddresses],
+      input.apiKey,
+      input.fetchFn,
+      input.timeoutMs,
+    ),
   ]);
 
   const enriched = new Map<string, JuplendVaultMetadata>();
@@ -480,6 +500,8 @@ async function enrichVaultsWithJupApi(input: {
 async function loadVaults(
   now: number,
   apiKey?: string,
+  fetchFn?: FetchLike,
+  timeoutMs = DEFAULT_HTTP_TIMEOUT_MS,
 ): Promise<Map<string, JuplendVaultMetadata>> {
   const cacheKey = getEnrichmentCacheKey(apiKey);
   const cached = enrichmentCache.get(cacheKey);
@@ -492,7 +514,11 @@ async function loadVaults(
   const inflight = enrichmentCachePromise.get(cacheKey);
   if (!inflight) {
     const nextPromise = (async () => {
-      const baseVaults = await loadVaultMetadataFromLiteApi(apiKey);
+      const baseVaults = await loadVaultMetadataFromLiteApi(
+        apiKey,
+        fetchFn,
+        timeoutMs,
+      );
       if (!apiKey) {
         enrichmentCache.set(cacheKey, {
           loadedAt: now,
@@ -506,6 +532,8 @@ async function loadVaults(
         const enrichedVaults = await enrichVaultsWithJupApi({
           apiKey,
           baseVaults,
+          fetchFn,
+          timeoutMs,
         });
         enrichmentCache.set(cacheKey, {
           loadedAt: now,
@@ -545,9 +573,11 @@ async function mapAccount(
   receivedAt: number,
   rpcUrl: string | undefined,
   jupApiKey: string | undefined,
+  fetchFn: FetchLike | undefined,
+  timeoutMs: number,
 ): Promise<JuplendMappedAccount> {
   const [vaults, positionResult] = await Promise.all([
-    loadVaults(receivedAt, jupApiKey),
+    loadVaults(receivedAt, jupApiKey, fetchFn, timeoutMs),
     readJuplendPositions({
       walletAddress: accountOptions.walletAddress,
       vaultId: accountOptions.vaultId,
@@ -666,6 +696,10 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
   constructor(
     private readonly rpcUrl?: string,
     private readonly jupApiKey?: string,
+    private readonly options: {
+      readonly fetchFn?: FetchLike;
+      readonly httpTimeoutMs?: number;
+    } = {},
   ) {}
 
   async bootstrapAccount(
@@ -679,6 +713,8 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
       receivedAt,
       this.rpcUrl,
       getJupApiKey(this.jupApiKey),
+      this.options.fetchFn,
+      this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
     );
 
     return {

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

@@ -3,7 +3,12 @@ import type {
   StreamHandle,
 } from "../adapters/types.ts";
 import { AcexError } from "../errors.ts";
-import type { AccountRuntimeOptions, Venue } from "../types/index.ts";
+import { isTransportError, redactSecrets } from "../internal/http-client.ts";
+import type {
+  AccountRuntimeOptions,
+  PrivateRuntimeReason,
+  Venue,
+} from "../types/index.ts";
 import type {
   ClientContext,
   PrivateAccountDataConsumer,
@@ -41,6 +46,23 @@ function normalizePositiveInterval(
     : fallback;
 }
 
+function transportReason(
+  error: unknown,
+  fallback: PrivateRuntimeReason,
+): PrivateRuntimeReason {
+  return isTransportError(error) && error.kind === "rate_limited"
+    ? "rate_limited"
+    : 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>;
@@ -435,7 +457,7 @@ export class PrivateSubscriptionCoordinator {
         {
           runtimeStatus: "degraded",
           ready: record.accountReady,
-          reason: "http_failed",
+          reason: transportReason(error, "http_failed"),
         },
       );
     }
@@ -559,7 +581,7 @@ export class PrivateSubscriptionCoordinator {
               {
                 runtimeStatus: "degraded",
                 ready: record.accountReady,
-                reason: "http_failed",
+                reason: transportReason(error, "http_failed"),
               },
             );
           }
@@ -676,11 +698,13 @@ export class PrivateSubscriptionCoordinator {
         {
           runtimeStatus: "degraded",
           ready: false,
-          reason: record.venue === "juplend" ? "http_failed" : "auth_failed",
+          reason: transportReason(
+            error,
+            record.venue === "juplend" ? "http_failed" : "auth_failed",
+          ),
         },
       );
-      const reason =
-        error instanceof Error && error.message ? ` (${error.message})` : "";
+      const reason = bootstrapErrorDetail(error);
       throw new AcexError(
         "ACCOUNT_BOOTSTRAP_FAILED",
         `Failed to bootstrap account data: ${record.accountId}${reason}`,
@@ -727,7 +751,7 @@ export class PrivateSubscriptionCoordinator {
         {
           runtimeStatus: "degraded",
           ready: false,
-          reason: "auth_failed",
+          reason: transportReason(error, "auth_failed"),
         },
       );
       throw new AcexError(

package/src/client/runtime.ts

@@ -105,7 +105,9 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     const marketAdapter = new BinanceMarketAdapter();
     this.marketAdapters = new Map([[marketAdapter.venue, marketAdapter]]);
     const privateAdapters = [
-      new BinancePrivateAdapter(),
+      new BinancePrivateAdapter({
+        signingClock: options.clock,
+      }),
       new JuplendPrivateAdapter(
         options.account?.juplend?.rpcUrl,
         options.account?.juplend?.jupApiKey,

package/src/internal/http-client.ts

@@ -0,0 +1,608 @@
+export type TransportErrorKind =
+  | "timeout"
+  | "http"
+  | "network"
+  | "rate_limited"
+  | "parse";
+
+export type HttpParseAs = "json" | "text" | "none";
+export type JsonParseMode = "text" | "response";
+export type EmptyBodyStrategy = "empty_object" | "empty_string" | "undefined";
+
+export interface HttpRetryPolicy {
+  readonly idempotent: boolean;
+  readonly maxAttempts: number;
+  readonly initialDelayMs?: number;
+  readonly maxDelayMs?: number;
+  readonly jitterRatio?: number;
+  readonly random?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+export interface HttpClientMessages {
+  http?(input: HttpErrorMessageInput): string;
+  timeout?(input: HttpErrorMessageInput): string;
+  aborted?(input: HttpErrorMessageInput): string;
+  network?(input: HttpErrorMessageInput): string;
+  parse?(input: HttpErrorMessageInput): string;
+}
+
+export interface HttpRequestOptions {
+  readonly fetchFn?: FetchLike;
+  readonly url: string | URL;
+  readonly method?: string;
+  readonly headers?: RequestInit["headers"];
+  readonly body?: RequestInit["body"];
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+  readonly parseAs: HttpParseAs;
+  readonly jsonParseMode?: JsonParseMode;
+  readonly emptyBody?: EmptyBodyStrategy;
+  readonly retryPolicy: HttpRetryPolicy;
+  readonly messages?: HttpClientMessages;
+}
+
+export interface HttpClientResponse<T> {
+  readonly body: T;
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: Headers;
+  readonly rawBody?: string;
+  readonly url: string;
+  readonly redactedUrl: string;
+  readonly attempts: number;
+}
+
+export interface HttpErrorMessageInput {
+  readonly kind: TransportErrorKind;
+  readonly status?: number;
+  readonly statusText?: string;
+  readonly retryAfterMs?: number;
+  readonly attempts: number;
+  readonly rawBody?: string;
+  readonly url: string;
+}
+
+export interface TransportErrorInit extends HttpErrorMessageInput {
+  readonly headers?: Headers;
+  readonly retryable: boolean;
+  readonly cause?: unknown;
+}
+
+export class TransportError extends Error {
+  readonly isAcexTransportError = true;
+  readonly kind: TransportErrorKind;
+  readonly status?: number;
+  readonly statusText?: string;
+  readonly retryAfterMs?: number;
+  readonly retryable: boolean;
+  readonly attempts: number;
+  readonly headers: Headers;
+  readonly rawBody?: string;
+  readonly url: string;
+  override readonly cause?: unknown;
+
+  constructor(message: string, init: TransportErrorInit) {
+    super(message, { cause: init.cause });
+    this.name = "TransportError";
+    this.kind = init.kind;
+    this.status = init.status;
+    this.statusText = init.statusText;
+    this.retryAfterMs = init.retryAfterMs;
+    this.retryable = init.retryable;
+    this.attempts = init.attempts;
+    this.headers = init.headers ?? new Headers();
+    this.rawBody = init.rawBody;
+    this.url = init.url;
+    this.cause = init.cause;
+  }
+}
+
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+interface AttemptErrorInput {
+  readonly kind: TransportErrorKind;
+  readonly status?: number;
+  readonly statusText?: string;
+  readonly headers?: Headers;
+  readonly rawBody?: string;
+  readonly retryAfterMs?: number;
+  readonly attempts: number;
+  readonly redactedUrl: string;
+  readonly retryable: boolean;
+  readonly aborted?: boolean;
+  readonly cause?: unknown;
+  readonly messages?: HttpClientMessages;
+}
+
+const DEFAULT_INITIAL_DELAY_MS = 100;
+const DEFAULT_MAX_DELAY_MS = 1_000;
+const DEFAULT_JITTER_RATIO = 0.2;
+const SENSITIVE_QUERY_KEYS = new Set([
+  "apikey",
+  "api_key",
+  "api-key",
+  "key",
+  "secret",
+  "signature",
+  "token",
+  "access_token",
+  "listenkey",
+  "listen_key",
+  "passphrase",
+]);
+
+export function isTransportError(error: unknown): error is TransportError {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+
+  const record = error as Record<string, unknown>;
+  return (
+    record.isAcexTransportError === true &&
+    typeof record.kind === "string" &&
+    typeof record.retryable === "boolean" &&
+    typeof record.attempts === "number"
+  );
+}
+
+export function redactSecrets(value: string): string {
+  let redacted = value.replace(/https?:\/\/[^\s)]+/g, redactUrlMatch);
+  // Bare (non-URL) signed query fragments — e.g. a relative path like
+  // "/papi/v1/order?symbol=...&signature=..." — never match the http(s) URL
+  // branch above. Fold the whole fragment so the non-secret params riding
+  // alongside a signature do not leak; mirrors the "?query=[REDACTED]"
+  // collapse redactUrl applies to full signed URLs.
+  redacted = redacted.replace(
+    /\?[^\s)#?]*\bsignature=[^&\s)#]+/gi,
+    "?query=[REDACTED]",
+  );
+  redacted = redacted.replace(
+    /([?&](?:api[_-]?key|key|secret|signature|token|access_token|listen[_-]?key|passphrase)=)[^&\s)]+/gi,
+    "$1[REDACTED]",
+  );
+  redacted = redacted.replace(
+    /("(?:api[_-]?key|key|secret|signature|token|access_token|listen[_-]?key|passphrase)"\s*:\s*")[^"]*(")/gi,
+    "$1[REDACTED]$2",
+  );
+  redacted = redacted.replace(
+    /((?:api[_-]?key|key|secret|signature|token|access_token|listen[_-]?key|passphrase)\s*[:=]\s*)[^\s,;)"']+/gi,
+    "$1[REDACTED]",
+  );
+  redacted = redacted.replace(
+    /([?&])signature=\[REDACTED\]/gi,
+    "$1query=[REDACTED]",
+  );
+  redacted = redacted.replace(
+    /"signature"\s*:\s*"\[REDACTED\]"/gi,
+    '"redacted":"[REDACTED]"',
+  );
+  redacted = redacted.replace(
+    /signature\s*[:=]\s*\[REDACTED\]/gi,
+    "query=[REDACTED]",
+  );
+  return redacted;
+}
+
+function redactUrlMatch(match: string): string {
+  try {
+    const url = new URL(match);
+    if (url.searchParams.has("signature")) {
+      url.search = "?query=[REDACTED]";
+      return url.toString();
+    }
+
+    for (const key of [...url.searchParams.keys()]) {
+      if (SENSITIVE_QUERY_KEYS.has(key.toLowerCase())) {
+        url.searchParams.set(key, "[REDACTED]");
+      }
+    }
+
+    return url.toString();
+  } catch {
+    return match;
+  }
+}
+
+export function redactUrl(input: string | URL): string {
+  const rawUrl = input.toString();
+  try {
+    const url = new URL(rawUrl);
+    const hasSignature = url.searchParams.has("signature");
+    if (hasSignature) {
+      url.search = "?query=[REDACTED]";
+      return url.toString();
+    }
+
+    let changed = false;
+    for (const key of [...url.searchParams.keys()]) {
+      if (SENSITIVE_QUERY_KEYS.has(key.toLowerCase())) {
+        url.searchParams.set(key, "[REDACTED]");
+        changed = true;
+      }
+    }
+
+    return changed ? url.toString() : rawUrl;
+  } catch {
+    return redactSecrets(rawUrl);
+  }
+}
+
+export function parseRetryAfterMs(value: string | null): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1_000);
+  }
+
+  const dateMs = Date.parse(value);
+  if (!Number.isFinite(dateMs)) {
+    return undefined;
+  }
+
+  const deltaMs = dateMs - Date.now();
+  return deltaMs > 0 ? deltaMs : 0;
+}
+
+export async function httpRequest<T>(
+  options: HttpRequestOptions,
+): Promise<HttpClientResponse<T>> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const url = options.url.toString();
+  const redactedUrl = redactUrl(options.url);
+  const maxAttempts = Math.max(1, Math.floor(options.retryPolicy.maxAttempts));
+  let lastError: TransportError | undefined;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    if (options.signal?.aborted) {
+      throw buildAttemptError({
+        kind: "network",
+        attempts: attempt,
+        redactedUrl,
+        retryable: false,
+        aborted: true,
+        messages: options.messages,
+      });
+    }
+
+    try {
+      return await executeAttempt<T>(
+        options,
+        fetchFn,
+        url,
+        redactedUrl,
+        attempt,
+      );
+    } catch (error) {
+      const transportError = isTransportError(error)
+        ? error
+        : buildAttemptError({
+            kind: "network",
+            attempts: attempt,
+            redactedUrl,
+            retryable: retryableForKind("network", undefined, options),
+            cause: error,
+            messages: options.messages,
+          });
+      lastError = transportError;
+      if (!shouldRetry(transportError, attempt, maxAttempts, options)) {
+        throw transportError;
+      }
+
+      await delayBeforeRetry(attempt, options.retryPolicy, options.signal);
+    }
+  }
+
+  throw lastError;
+}
+
+async function executeAttempt<T>(
+  options: HttpRequestOptions,
+  fetchFn: FetchLike,
+  url: string,
+  redactedUrl: string,
+  attempts: number,
+): Promise<HttpClientResponse<T>> {
+  const controller = new AbortController();
+  const timeoutMs = options.timeoutMs;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const onUpstreamAbort = (): void => {
+    controller.abort();
+  };
+
+  if (options.signal?.aborted) {
+    controller.abort();
+  } else {
+    options.signal?.addEventListener("abort", onUpstreamAbort, { once: true });
+  }
+
+  if (timeoutMs !== undefined) {
+    timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+  }
+
+  try {
+    const response = await fetchFn(url, {
+      method: options.method,
+      headers: options.headers,
+      body: options.body,
+      signal: controller.signal,
+    });
+    const headers = new Headers(response.headers);
+
+    if (!response.ok) {
+      const rawBody = redactSecrets(await response.text());
+      const kind: TransportErrorKind =
+        response.status === 429 || response.status === 418
+          ? "rate_limited"
+          : "http";
+      const retryAfterMs = parseRetryAfterMs(headers.get("Retry-After"));
+      throw buildAttemptError({
+        kind,
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        rawBody,
+        retryAfterMs,
+        attempts,
+        redactedUrl,
+        retryable: retryableForKind(kind, response.status, options),
+        messages: options.messages,
+      });
+    }
+
+    const parsed = await parseResponseBody<T>(
+      response,
+      options,
+      attempts,
+      redactedUrl,
+    );
+    return {
+      body: parsed.body,
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+      rawBody: parsed.rawBody,
+      url,
+      redactedUrl,
+      attempts,
+    };
+  } catch (error) {
+    if (isTransportError(error)) {
+      throw error;
+    }
+
+    if (isAbortError(error)) {
+      throw buildAttemptError({
+        kind: timedOut ? "timeout" : "network",
+        attempts,
+        redactedUrl,
+        retryable: timedOut
+          ? retryableForKind("timeout", undefined, options)
+          : false,
+        aborted: !timedOut,
+        cause: error,
+        messages: options.messages,
+      });
+    }
+
+    throw buildAttemptError({
+      kind: "network",
+      attempts,
+      redactedUrl,
+      retryable: retryableForKind("network", undefined, options),
+      cause: error,
+      messages: options.messages,
+    });
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    options.signal?.removeEventListener("abort", onUpstreamAbort);
+  }
+}
+
+async function parseResponseBody<T>(
+  response: Response,
+  options: HttpRequestOptions,
+  attempts: number,
+  redactedUrl: string,
+): Promise<{ body: T; rawBody?: string }> {
+  if (options.parseAs === "none") {
+    return { body: undefined as T };
+  }
+
+  if (options.parseAs === "text") {
+    const rawBody = await response.text();
+    return { body: rawBody as T, rawBody };
+  }
+
+  if (options.jsonParseMode === "response") {
+    try {
+      return { body: (await response.json()) as T };
+    } catch (error) {
+      throw buildAttemptError({
+        kind: "parse",
+        status: response.status,
+        statusText: response.statusText,
+        headers: new Headers(response.headers),
+        attempts,
+        redactedUrl,
+        retryable: false,
+        cause: error,
+        messages: options.messages,
+      });
+    }
+  }
+
+  const rawBody = await response.text();
+  if (!rawBody) {
+    switch (options.emptyBody ?? "undefined") {
+      case "empty_object":
+        return { body: {} as T, rawBody };
+      case "empty_string":
+        return { body: "" as T, rawBody };
+      case "undefined":
+        return { body: undefined as T, rawBody };
+    }
+  }
+
+  try {
+    return { body: JSON.parse(rawBody) as T, rawBody };
+  } catch (error) {
+    throw buildAttemptError({
+      kind: "parse",
+      status: response.status,
+      statusText: response.statusText,
+      headers: new Headers(response.headers),
+      rawBody: redactSecrets(rawBody),
+      attempts,
+      redactedUrl,
+      retryable: false,
+      cause: error,
+      messages: options.messages,
+    });
+  }
+}
+
+function buildAttemptError(input: AttemptErrorInput): TransportError {
+  const messageInput: HttpErrorMessageInput = {
+    kind: input.kind,
+    status: input.status,
+    statusText: input.statusText,
+    retryAfterMs: input.retryAfterMs,
+    attempts: input.attempts,
+    rawBody: input.rawBody,
+    url: input.redactedUrl,
+  };
+  const message =
+    messageForKind(input.messages, input.kind, input.aborted)?.(messageInput) ??
+    defaultMessage(messageInput);
+
+  return new TransportError(message, {
+    ...messageInput,
+    headers: input.headers,
+    retryable: input.retryable,
+    cause: input.cause,
+  });
+}
+
+function messageForKind(
+  messages: HttpClientMessages | undefined,
+  kind: TransportErrorKind,
+  aborted: boolean | undefined,
+): ((input: HttpErrorMessageInput) => string) | undefined {
+  if (kind === "network" && aborted) {
+    return messages?.aborted ?? messages?.network;
+  }
+  if (kind === "http" || kind === "rate_limited") {
+    return messages?.http;
+  }
+  return messages?.[kind];
+}
+
+function defaultMessage(input: HttpErrorMessageInput): string {
+  switch (input.kind) {
+    case "timeout":
+      return `HTTP request timeout after attempt ${input.attempts}: ${input.url}`;
+    case "network":
+      return `HTTP request failed: ${input.url}`;
+    case "parse":
+      return `HTTP response parse failed: ${input.url}`;
+    case "rate_limited":
+    case "http": {
+      const status = [input.status, input.statusText].filter(Boolean).join(" ");
+      const body = input.rawBody ? ` ${input.rawBody}` : "";
+      return `HTTP request failed: ${status} ${input.url}${body}`;
+    }
+  }
+}
+
+function retryableForKind(
+  kind: TransportErrorKind,
+  status: number | undefined,
+  options: HttpRequestOptions,
+): boolean {
+  if (!options.retryPolicy.idempotent || options.signal?.aborted) {
+    return false;
+  }
+
+  if (kind === "network" || kind === "timeout") {
+    return true;
+  }
+
+  if (kind === "http" && status !== undefined) {
+    return status >= 500 && status <= 599;
+  }
+
+  return false;
+}
+
+function shouldRetry(
+  error: TransportError,
+  attempt: number,
+  maxAttempts: number,
+  options: HttpRequestOptions,
+): boolean {
+  return error.retryable && attempt < maxAttempts && !options.signal?.aborted;
+}
+
+async function delayBeforeRetry(
+  attempt: number,
+  retryPolicy: HttpRetryPolicy,
+  signal?: AbortSignal,
+): Promise<void> {
+  const sleep = retryPolicy.sleep ?? defaultSleep;
+  const baseDelay = Math.min(
+    retryPolicy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,
+    (retryPolicy.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS) *
+      2 ** Math.max(0, attempt - 1),
+  );
+  const jitterRatio = retryPolicy.jitterRatio ?? DEFAULT_JITTER_RATIO;
+  const random = retryPolicy.random ?? Math.random;
+  const jitter = baseDelay * jitterRatio * (random() * 2 - 1);
+  const delayMs = Math.max(0, Math.round(baseDelay + jitter));
+
+  if (signal === undefined) {
+    await sleep(delayMs);
+    return;
+  }
+  if (signal.aborted) {
+    return;
+  }
+  // Race the backoff against the upstream abort so a cancel mid-backoff
+  // returns immediately instead of waiting out the full delay. The retry
+  // loop re-checks signal.aborted on the next iteration and throws.
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = (): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      signal.removeEventListener("abort", finish);
+      resolve();
+    };
+    signal.addEventListener("abort", finish, { once: true });
+    void Promise.resolve(sleep(delayMs)).then(finish);
+  });
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/types/shared.ts

@@ -24,6 +24,11 @@ export interface Logger {
   error(msg: string, context?: Record<string, unknown>): void;
 }
 
+export interface TimeProvider {
+  /** Millisecond timestamp used for outbound request/signing timestamps. */
+  now(): number;
+}
+
 export interface MarketRuntimeOptions {
   l1InitialMessageTimeoutMs?: number;
   l1StaleAfterMs?: number;
@@ -48,6 +53,8 @@ export interface AccountRuntimeOptions {
 
 export interface CreateClientOptions {
   sandbox?: boolean;
+  /** Request/signing clock; local receivedAt/freshness clocks stay independent. */
+  clock?: TimeProvider;
   logger?: Logger;
   logLevel?: LogLevel;
   market?: MarketRuntimeOptions;