@imbingox/acex 0.4.0-beta.2 → 0.4.0-beta.4

package/docs/api.md

@@ -967,6 +967,8 @@ interface AccountRuntimeOptions {
 
 interface CreateClientOptions {
   sandbox?: boolean;   // 预留，当前不生效
+  clock?: TimeProvider;     // 注入签名/请求时钟，默认本地时钟
+  rateLimiter?: RateLimiter; // 注入限流器，默认 reactive（观测 + Retry-After 退避，不主动节流）
   logger?: Logger;     // 预留
   logLevel?: LogLevel; // 预留
   market?: MarketRuntimeOptions;

package/package.json

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

package/src/adapters/binance/adapter.ts

@@ -1,6 +1,7 @@
 import { SubscriptionMultiplexer } from "../../internal/subscription-multiplexer.ts";
 import type {
   MarketDefinition,
+  RateLimiter,
   VenueMarketCapabilities,
 } from "../../types/index.ts";
 import type {
@@ -53,8 +54,16 @@ export class BinanceMarketAdapter implements MarketAdapter {
   private multiplexer: BinanceMarketMultiplexer | undefined;
   private multiplexerConfig: BinanceMultiplexerConfig | undefined;
 
+  constructor(
+    private readonly options: {
+      readonly rateLimiter?: RateLimiter;
+    } = {},
+  ) {}
+
   async loadMarkets(): Promise<MarketDefinition[]> {
-    const markets = await loadBinanceMarkets();
+    const markets = await loadBinanceMarkets(fetch, {
+      rateLimiter: this.options.rateLimiter,
+    });
     this.definitions.clear();
 
     for (const market of markets) {

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

@@ -2,8 +2,15 @@ import { toCanonical } from "../../internal/decimal.ts";
 import {
   type HttpClientMessages,
   httpRequest,
+  isTransportError,
 } from "../../internal/http-client.ts";
-import type { MarketDefinition, MarketType } from "../../types/index.ts";
+import type {
+  MarketDefinition,
+  MarketType,
+  RateLimiter,
+  RateLimitScope,
+} from "../../types/index.ts";
+import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
 
 type FetchLike = typeof fetch;
 
@@ -224,21 +231,55 @@ function normalizeDerivativesSymbol(
 async function requestCatalogJson<T>(
   fetchFn: FetchLike,
   url: string,
+  rateLimiter: RateLimiter | undefined,
+  endpointKey: 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 response.body;
+  const scope: RateLimitScope = {
+    venue: "binance",
+    endpointKey,
+  };
+
+  await rateLimiter?.beforeRequest({ scope });
+
+  try {
+    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,
+    });
+
+    await rateLimiter?.afterResponse(
+      { scope },
+      {
+        status: response.status,
+        headers: response.headers,
+        usage: parseBinanceRateLimitUsage(response.headers),
+      },
+    );
+
+    return response.body;
+  } catch (error) {
+    if (isTransportError(error)) {
+      await rateLimiter?.onTransportError(
+        { scope },
+        {
+          status: error.status,
+          headers: error.headers,
+          retryAfterMs: error.retryAfterMs,
+          usage: parseBinanceRateLimitUsage(error.headers),
+        },
+      );
+    }
+
+    throw error;
+  }
 }
 
 function sortMarkets(
@@ -251,19 +292,26 @@ function sortMarkets(
 
 export async function loadBinanceMarkets(
   fetchFn: FetchLike = fetch,
+  options: { readonly rateLimiter?: RateLimiter } = {},
 ): Promise<BinanceMarketDefinition[]> {
   const [spot, usdm, coinm] = await Promise.all([
     requestCatalogJson<BinanceSpotExchangeInfo>(
       fetchFn,
       BINANCE_SPOT_EXCHANGE_INFO_URL,
+      options.rateLimiter,
+      "GET /api/v3/exchangeInfo",
     ),
     requestCatalogJson<BinanceDerivativesExchangeInfo>(
       fetchFn,
       BINANCE_USDM_EXCHANGE_INFO_URL,
+      options.rateLimiter,
+      "GET /fapi/v1/exchangeInfo",
     ),
     requestCatalogJson<BinanceDerivativesExchangeInfo>(
       fetchFn,
       BINANCE_COINM_EXCHANGE_INFO_URL,
+      options.rateLimiter,
+      "GET /dapi/v1/exchangeInfo",
     ),
   ]);
 

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

@@ -4,11 +4,15 @@ import {
   type HttpClientMessages,
   type HttpRetryPolicy,
   httpRequest,
+  isTransportError,
 } from "../../internal/http-client.ts";
 import { createManagedWebSocket } from "../../internal/managed-websocket.ts";
 import type {
   AccountCredentials,
   PositionSide,
+  RateLimiter,
+  RateLimitScope,
+  TimeProvider,
   VenueAccountCapabilities,
   VenueOrderCapabilities,
 } from "../../types/index.ts";
@@ -27,6 +31,7 @@ import type {
   RawRiskUpdate,
   StreamHandle,
 } from "../types.ts";
+import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
 
 type TimerHandle = ReturnType<typeof setInterval>;
 type SignedRequestMethod = "GET" | "POST" | "DELETE";
@@ -204,6 +209,14 @@ function getNumberOption(
     : undefined;
 }
 
+function getStringOption(
+  options: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined {
+  const value = options?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
 function signQuery(query: string, secret: string): string {
   return createHmac("sha256", secret).update(query).digest("hex");
 }
@@ -588,6 +601,8 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     private readonly options: {
       readonly fetchFn?: FetchLike;
       readonly httpTimeoutMs?: number;
+      readonly signingClock?: TimeProvider;
+      readonly rateLimiter?: RateLimiter;
     } = {},
   ) {}
 
@@ -784,7 +799,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     credentials: AccountCredentials,
     callbacks: PrivateStreamCallbacks,
     options: PrivateStreamOptions,
-    _accountOptions?: Record<string, unknown>,
+    accountOptions?: Record<string, unknown>,
   ): StreamHandle {
     let closed = false;
     let listenKey: string | undefined;
@@ -806,17 +821,19 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
 
       const key = listenKey;
       listenKey = undefined;
-      void this.closeUserDataStream(credentials, key).catch((error) => {
-        callbacks.onError(
-          error instanceof Error
-            ? error
-            : new Error("Failed to close Binance PAPI listenKey"),
-        );
-      });
+      void this.closeUserDataStream(credentials, key, accountOptions).catch(
+        (error) => {
+          callbacks.onError(
+            error instanceof Error
+              ? error
+              : new Error("Failed to close Binance PAPI listenKey"),
+          );
+        },
+      );
     };
 
     const ready = (async () => {
-      listenKey = await this.startUserDataStream(credentials);
+      listenKey = await this.startUserDataStream(credentials, accountOptions);
       if (closed) {
         closeListenKey();
         return;
@@ -827,15 +844,17 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
           return;
         }
 
-        void this.keepAliveUserDataStream(credentials, listenKey).catch(
-          (error) => {
-            callbacks.onError(
-              error instanceof Error
-                ? error
-                : new Error("Failed to keep Binance PAPI listenKey alive"),
-            );
-          },
-        );
+        void this.keepAliveUserDataStream(
+          credentials,
+          listenKey,
+          accountOptions,
+        ).catch((error) => {
+          callbacks.onError(
+            error instanceof Error
+              ? error
+              : new Error("Failed to keep Binance PAPI listenKey alive"),
+          );
+        });
       }, options.listenKeyKeepAliveMs);
 
       websocket = createManagedWebSocket<BinancePrivateMessage>({
@@ -903,6 +922,9 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     retryPolicy?: HttpRetryPolicy,
   ): Promise<T> {
     const { apiKey, secret } = requirePrivateCredentials(credentials);
+    const scope = this.rateLimitScope(method, path, accountOptions);
+    await this.options.rateLimiter?.beforeRequest({ scope });
+
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(queryParams ?? {})) {
       if (value !== undefined) {
@@ -911,7 +933,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",
@@ -921,31 +947,58 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
 
     const url = `${BINANCE_PAPI_REST_BASE_URL}${path}?${params.toString()}`;
     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),
-    });
+    try {
+      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),
+      });
+
+      await this.options.rateLimiter?.afterResponse(
+        { scope },
+        {
+          status: response.status,
+          headers: response.headers,
+          usage: parseBinanceRateLimitUsage(response.headers),
+        },
+      );
+
+      return response.body;
+    } catch (error) {
+      if (isTransportError(error)) {
+        await this.options.rateLimiter?.onTransportError(
+          { scope },
+          {
+            status: error.status,
+            headers: error.headers,
+            retryAfterMs: error.retryAfterMs,
+            usage: parseBinanceRateLimitUsage(error.headers),
+          },
+        );
+      }
 
-    return response.body;
+      throw error;
+    }
   }
 
   private async startUserDataStream(
     credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
   ): Promise<string> {
     const response = await this.userStreamRequest<BinanceListenKeyResponse>(
       "POST",
       credentials,
       undefined,
       NO_RETRY_POLICY,
+      accountOptions,
     );
     if (!response.listenKey) {
       throw new Error("Binance PAPI did not return a listenKey");
@@ -957,24 +1010,28 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
   private async keepAliveUserDataStream(
     credentials: AccountCredentials,
     listenKey: string,
+    accountOptions?: Record<string, unknown>,
   ): Promise<void> {
     await this.userStreamRequest<Record<string, never>>(
       "PUT",
       credentials,
       listenKey,
       LISTEN_KEY_KEEPALIVE_RETRY_POLICY,
+      accountOptions,
     );
   }
 
   private async closeUserDataStream(
     credentials: AccountCredentials,
     listenKey: string,
+    accountOptions?: Record<string, unknown>,
   ): Promise<void> {
     await this.userStreamRequest<Record<string, never>>(
       "DELETE",
       credentials,
       listenKey,
       NO_RETRY_POLICY,
+      accountOptions,
     );
   }
 
@@ -983,8 +1040,16 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     credentials: AccountCredentials,
     listenKey?: string,
     retryPolicy: HttpRetryPolicy = NO_RETRY_POLICY,
+    accountOptions?: Record<string, unknown>,
   ): Promise<T> {
     const { apiKey } = requirePrivateCredentials(credentials);
+    const scope = this.rateLimitScope(
+      method,
+      "/papi/v1/listenKey",
+      accountOptions,
+    );
+    await this.options.rateLimiter?.beforeRequest({ scope });
+
     const params = new URLSearchParams();
     if (listenKey) {
       params.set("listenKey", listenKey);
@@ -995,20 +1060,57 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       query ? `?${query}` : ""
     }`;
     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),
-    });
+    try {
+      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),
+      });
+
+      await this.options.rateLimiter?.afterResponse(
+        { scope },
+        {
+          status: response.status,
+          headers: response.headers,
+          usage: parseBinanceRateLimitUsage(response.headers),
+        },
+      );
+
+      return response.body;
+    } catch (error) {
+      if (isTransportError(error)) {
+        await this.options.rateLimiter?.onTransportError(
+          { scope },
+          {
+            status: error.status,
+            headers: error.headers,
+            retryAfterMs: error.retryAfterMs,
+            usage: parseBinanceRateLimitUsage(error.headers),
+          },
+        );
+      }
 
-    return response.body;
+      throw error;
+    }
+  }
+
+  private rateLimitScope(
+    method: string,
+    path: string,
+    accountOptions?: Record<string, unknown>,
+  ): RateLimitScope {
+    return {
+      venue: "binance",
+      accountId: getStringOption(accountOptions, "accountId"),
+      endpointKey: `${method} ${path}`,
+    };
   }
 }

package/src/adapters/binance/rate-limit.ts

@@ -0,0 +1,47 @@
+import type { RateLimitUsage } from "../../types/index.ts";
+
+const USED_WEIGHT_PREFIX = "x-mbx-used-weight-";
+const ORDER_COUNT_PREFIX = "x-mbx-order-count-";
+
+export function parseBinanceRateLimitUsage(
+  headers: Headers,
+): RateLimitUsage | undefined {
+  const weight: Record<string, number> = {};
+  const orderCount: Record<string, number> = {};
+
+  for (const name of headers.keys()) {
+    const normalizedName = name.toLowerCase();
+    if (normalizedName.startsWith(USED_WEIGHT_PREFIX)) {
+      const interval = normalizedName.slice(USED_WEIGHT_PREFIX.length);
+      const value = parseHeaderNumber(headers.get(name));
+      if (interval && value !== undefined) {
+        weight[interval] = value;
+      }
+      continue;
+    }
+
+    if (normalizedName.startsWith(ORDER_COUNT_PREFIX)) {
+      const interval = normalizedName.slice(ORDER_COUNT_PREFIX.length);
+      const value = parseHeaderNumber(headers.get(name));
+      if (interval && value !== undefined) {
+        orderCount[interval] = value;
+      }
+    }
+  }
+
+  return Object.keys(weight).length > 0 || Object.keys(orderCount).length > 0
+    ? {
+        weight: Object.keys(weight).length > 0 ? weight : undefined,
+        orderCount: Object.keys(orderCount).length > 0 ? orderCount : undefined,
+      }
+    : undefined;
+}
+
+function parseHeaderNumber(value: string | null): number | undefined {
+  if (value === null) {
+    return undefined;
+  }
+
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}

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

@@ -595,7 +595,7 @@ export class PrivateSubscriptionCoordinator {
         juplendPollIntervalMs: this.juplendPollIntervalMs,
         now: () => this.context.now(),
       },
-      account.options,
+      { ...account.options, accountId: account.accountId },
     );
 
     record.stream = stream;
@@ -719,7 +719,7 @@ export class PrivateSubscriptionCoordinator {
     try {
       const snapshots = await this.getAdapter(record.venue).bootstrapOpenOrders(
         account.credentials ?? {},
-        account.options,
+        { ...account.options, accountId: account.accountId },
       );
       if (!record.ordersSubscribed) {
         return;

package/src/client/runtime.ts

@@ -12,6 +12,7 @@ import type {
 import { AcexError, type AcexErrorCode } from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { matchesHealthFilter } from "../internal/filters.ts";
+import { ReactiveRateLimiter } from "../internal/rate-limiter.ts";
 import { AccountManagerImpl } from "../managers/account-manager.ts";
 import { MarketManagerImpl } from "../managers/market-manager.ts";
 import { OrderManagerImpl } from "../managers/order-manager.ts";
@@ -102,10 +103,14 @@ export class AcexClientImpl implements AcexClient, ClientContext {
   constructor(options: CreateClientOptions = {}) {
     activeClients.add(this);
 
-    const marketAdapter = new BinanceMarketAdapter();
+    const rateLimiter = options.rateLimiter ?? new ReactiveRateLimiter();
+    const marketAdapter = new BinanceMarketAdapter({ rateLimiter });
     this.marketAdapters = new Map([[marketAdapter.venue, marketAdapter]]);
     const privateAdapters = [
-      new BinancePrivateAdapter(),
+      new BinancePrivateAdapter({
+        signingClock: options.clock,
+        rateLimiter,
+      }),
       new JuplendPrivateAdapter(
         options.account?.juplend?.rpcUrl,
         options.account?.juplend?.jupApiKey,
@@ -339,7 +344,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.getPrivateAdapter(account.venue).createOrder(
       account.credentials ?? {},
       request,
-      account.options,
+      { ...account.options, accountId: account.accountId },
     );
   }
 
@@ -354,7 +359,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.getPrivateAdapter(account.venue).cancelOrder(
       account.credentials ?? {},
       request,
-      account.options,
+      { ...account.options, accountId: account.accountId },
     );
   }
 
@@ -367,7 +372,7 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.getPrivateAdapter(account.venue).cancelAllOrders(
       account.credentials ?? {},
       request,
-      account.options,
+      { ...account.options, accountId: account.accountId },
     );
   }
 

package/src/internal/rate-limiter.ts

@@ -0,0 +1,181 @@
+import type {
+  RateLimiter,
+  RateLimitRequestContext,
+  RateLimitResponseContext,
+  RateLimitScope,
+  RateLimitSnapshot,
+  RateLimitTransportErrorContext,
+  RateLimitUsage,
+} from "../types/index.ts";
+
+interface ReactiveRateLimiterOptions {
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly defaultRateLimitMs?: number;
+  readonly defaultBanMs?: number;
+}
+
+interface RateLimitState {
+  usage?: RateLimitUsage;
+  blockedUntil?: number;
+  retryAfterMs?: number;
+  state: RateLimitSnapshot["state"];
+  updatedAt?: number;
+}
+
+const DEFAULT_RATE_LIMIT_MS = 0;
+const DEFAULT_BAN_MS = 60_000;
+
+export class ReactiveRateLimiter implements RateLimiter {
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly defaultRateLimitMs: number;
+  private readonly defaultBanMs: number;
+  private readonly states = new Map<string, RateLimitState>();
+
+  constructor(options: ReactiveRateLimiterOptions = {}) {
+    this.now = options.now ?? Date.now;
+    this.sleep = options.sleep ?? defaultSleep;
+    this.defaultRateLimitMs =
+      options.defaultRateLimitMs ?? DEFAULT_RATE_LIMIT_MS;
+    this.defaultBanMs = options.defaultBanMs ?? DEFAULT_BAN_MS;
+  }
+
+  async beforeRequest(ctx: RateLimitRequestContext): Promise<void> {
+    const snapshot = this.getSnapshot(ctx.scope);
+    if (!snapshot?.blockedUntil || snapshot.blockedUntil <= this.now()) {
+      return;
+    }
+
+    await this.sleep(Math.max(0, snapshot.blockedUntil - this.now()));
+  }
+
+  afterResponse(
+    ctx: RateLimitRequestContext,
+    response: RateLimitResponseContext,
+  ): void {
+    if (response.usage) {
+      const existing = this.getState(ctx.scope);
+      const hasActiveBlock =
+        existing?.blockedUntil !== undefined &&
+        existing.blockedUntil > this.now();
+      this.updateState(ctx.scope, {
+        usage: cloneUsage(response.usage),
+        state: hasActiveBlock ? existing.state : "ok",
+      });
+    }
+  }
+
+  onTransportError(
+    ctx: RateLimitRequestContext,
+    error: RateLimitTransportErrorContext,
+  ): void {
+    if (error.usage) {
+      this.updateState(ctx.scope, {
+        usage: cloneUsage(error.usage),
+      });
+    }
+
+    if (error.status !== 429 && error.status !== 418) {
+      return;
+    }
+
+    const now = this.now();
+    const isBan = error.status === 418;
+    const retryAfterMs =
+      error.retryAfterMs ??
+      (isBan ? this.defaultBanMs : this.defaultRateLimitMs);
+    const blockedUntil =
+      retryAfterMs > 0
+        ? now + retryAfterMs
+        : this.getState(ctx.scope)?.blockedUntil;
+
+    this.updateState(ctx.scope, {
+      blockedUntil,
+      retryAfterMs,
+      state: isBan ? "banned" : "rate_limited",
+    });
+  }
+
+  getSnapshot(scope: RateLimitScope): RateLimitSnapshot | undefined {
+    const state = this.getState(scope);
+    if (!state) {
+      return undefined;
+    }
+
+    const now = this.now();
+    const blockedUntil =
+      state.blockedUntil !== undefined && state.blockedUntil > now
+        ? state.blockedUntil
+        : undefined;
+    const runtimeState =
+      blockedUntil === undefined && state.state !== "ok" ? "ok" : state.state;
+
+    return {
+      scope: { ...scope },
+      usage: state.usage ? cloneUsage(state.usage) : undefined,
+      blockedUntil,
+      retryAfterMs: blockedUntil ? state.retryAfterMs : undefined,
+      state: runtimeState,
+      updatedAt: state.updatedAt,
+    };
+  }
+
+  private getState(scope: RateLimitScope): RateLimitState | undefined {
+    return this.states.get(scopeKey(scope));
+  }
+
+  private updateState(
+    scope: RateLimitScope,
+    patch: Partial<RateLimitState>,
+  ): void {
+    const existing = this.getState(scope);
+    const nextBlockedUntil = maxOptional(
+      existing?.blockedUntil,
+      patch.blockedUntil,
+    );
+    const nextState =
+      patch.state ??
+      (nextBlockedUntil !== undefined
+        ? (existing?.state ?? "ok")
+        : existing?.state);
+
+    this.states.set(scopeKey(scope), {
+      usage: patch.usage ?? existing?.usage,
+      blockedUntil: nextBlockedUntil,
+      retryAfterMs: patch.retryAfterMs ?? existing?.retryAfterMs,
+      state: nextState ?? "ok",
+      updatedAt: this.now(),
+    });
+  }
+}
+
+function scopeKey(scope: RateLimitScope): string {
+  return [scope.venue, scope.accountId ?? "", scope.endpointKey].join("\0");
+}
+
+function cloneUsage(usage: RateLimitUsage): RateLimitUsage {
+  return {
+    weight: usage.weight ? { ...usage.weight } : undefined,
+    orderCount: usage.orderCount ? { ...usage.orderCount } : undefined,
+  };
+}
+
+function maxOptional(
+  left: number | undefined,
+  right: number | undefined,
+): number | undefined {
+  if (left === undefined) {
+    return right;
+  }
+  if (right === undefined) {
+    return left;
+  }
+  return Math.max(left, right);
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/types/shared.ts

@@ -24,6 +24,63 @@ 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 RateLimitScope {
+  venue: Venue;
+  accountId?: string;
+  endpointKey: string;
+}
+
+export interface RateLimitUsage {
+  /** Exchange request-weight usage by interval key, e.g. "1m". */
+  weight?: Record<string, number>;
+  /** Exchange order-count usage by interval key, separate from request weight. */
+  orderCount?: Record<string, number>;
+}
+
+export interface RateLimitRequestContext {
+  scope: RateLimitScope;
+}
+
+export interface RateLimitResponseContext {
+  status: number;
+  headers?: Headers;
+  usage?: RateLimitUsage;
+}
+
+export interface RateLimitTransportErrorContext {
+  status?: number;
+  headers?: Headers;
+  retryAfterMs?: number;
+  usage?: RateLimitUsage;
+}
+
+export interface RateLimitSnapshot {
+  scope: RateLimitScope;
+  usage?: RateLimitUsage;
+  blockedUntil?: number;
+  retryAfterMs?: number;
+  state: "ok" | "rate_limited" | "banned";
+  updatedAt?: number;
+}
+
+export interface RateLimiter {
+  beforeRequest(ctx: RateLimitRequestContext): Promise<void> | void;
+  afterResponse(
+    ctx: RateLimitRequestContext,
+    response: RateLimitResponseContext,
+  ): Promise<void> | void;
+  onTransportError(
+    ctx: RateLimitRequestContext,
+    error: RateLimitTransportErrorContext,
+  ): Promise<void> | void;
+  getSnapshot(scope: RateLimitScope): RateLimitSnapshot | undefined;
+}
+
 export interface MarketRuntimeOptions {
   l1InitialMessageTimeoutMs?: number;
   l1StaleAfterMs?: number;
@@ -48,6 +105,9 @@ export interface AccountRuntimeOptions {
 
 export interface CreateClientOptions {
   sandbox?: boolean;
+  /** Request/signing clock; local receivedAt/freshness clocks stay independent. */
+  clock?: TimeProvider;
+  rateLimiter?: RateLimiter;
   logger?: Logger;
   logLevel?: LogLevel;
   market?: MarketRuntimeOptions;