@imbingox/acex 0.3.1-beta.0 → 0.4.0-beta.10

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

@@ -1,9 +1,18 @@
 import { createHmac } from "node:crypto";
 import BigNumber from "bignumber.js";
+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";
@@ -11,20 +20,24 @@ import type {
   CancelAllOrdersRequest,
   CancelOrderRequest,
   CreateOrderRequest,
+  FetchOrderRequest,
   PrivateStreamCallbacks,
   PrivateStreamOptions,
   PrivateUserDataAdapter,
   RawAccountBootstrap,
   RawAccountUpdate,
   RawBalanceUpdate,
+  RawOpenOrdersSnapshot,
   RawOrderUpdate,
   RawPositionUpdate,
   RawRiskUpdate,
   StreamHandle,
 } from "../types.ts";
+import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
 
 type TimerHandle = ReturnType<typeof setInterval>;
 type SignedRequestMethod = "GET" | "POST" | "DELETE";
+type FetchLike = typeof fetch;
 
 interface BinancePapiBalance {
   asset?: string;
@@ -144,7 +157,32 @@ 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,
+};
+const BINANCE_ORDER_NOT_FOUND_CODES = new Set(["-2011", "-2013"]);
+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;
@@ -174,6 +212,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");
 }
@@ -393,6 +439,27 @@ function mapAccountRefresh(
   };
 }
 
+function mapAccountBootstrap(
+  balances: BinancePapiBalance[],
+  account: BinancePapiAccount,
+  positions: BinancePapiUmPosition[],
+  receivedAt: number,
+): RawAccountBootstrap {
+  return {
+    balances: balances.flatMap((balance) => {
+      const mapped = mapBalance(balance, receivedAt);
+      return mapped ? [mapped] : [];
+    }),
+    positions: positions.flatMap((position) => {
+      const mapped = mapUmPosition(position, receivedAt);
+      return mapped ? [mapped] : [];
+    }),
+    risk: mapAccountRisk(account, receivedAt, positions),
+    exchangeTs: account.updateTime,
+    receivedAt,
+  };
+}
+
 function mapOpenOrder(
   input: BinancePapiOpenOrder,
   receivedAt: number,
@@ -521,19 +588,26 @@ 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}`,
-    );
+function isBinanceOrderNotFound(error: unknown): boolean {
+  if (!isTransportError(error) || error.kind !== "http") {
+    return false;
   }
 
-  if (!text) {
-    return {} as T;
+  if (error.status !== 400 && error.status !== 404) {
+    return false;
   }
 
-  return JSON.parse(text) as T;
+  const rawBody = error.rawBody;
+  if (!rawBody) {
+    return false;
+  }
+
+  try {
+    const parsed = JSON.parse(rawBody) as { code?: unknown };
+    return BINANCE_ORDER_NOT_FOUND_CODES.has(`${parsed.code}`);
+  } catch {
+    return false;
+  }
 }
 
 export class BinancePrivateAdapter implements PrivateUserDataAdapter {
@@ -569,6 +643,15 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     clientOrderId: true,
   };
 
+  constructor(
+    private readonly options: {
+      readonly fetchFn?: FetchLike;
+      readonly httpTimeoutMs?: number;
+      readonly signingClock?: TimeProvider;
+      readonly rateLimiter?: RateLimiter;
+    } = {},
+  ) {}
+
   async bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
@@ -580,34 +663,35 @@ 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,
       ),
     ]);
 
-    return {
-      balances: balances.flatMap((balance) => {
-        const mapped = mapBalance(balance, receivedAt);
-        return mapped ? [mapped] : [];
-      }),
-      positions: positions.flatMap((position) => {
-        const mapped = mapUmPosition(position, receivedAt);
-        return mapped ? [mapped] : [];
-      }),
-      risk: mapAccountRisk(account, receivedAt, positions),
-      exchangeTs: account.updateTime,
-      receivedAt,
-    };
+    return mapAccountBootstrap(balances, account, positions, receivedAt);
+  }
+
+  async reconcileAccount(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawAccountBootstrap> {
+    return this.bootstrapAccount(credentials, accountOptions);
   }
 
   async refreshAccount(
@@ -621,12 +705,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,
       ),
     ]);
 
@@ -637,18 +725,61 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
   ): Promise<RawOrderUpdate[]> {
+    const snapshot = await this.fetchOpenOrders(credentials, accountOptions);
+    return snapshot.orders;
+  }
+
+  async fetchOpenOrders(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawOpenOrdersSnapshot> {
     const receivedAt = Date.now();
     const orders = await this.signedRequest<BinancePapiOpenOrder[]>(
       "GET",
       "/papi/v1/um/openOrders",
       credentials,
       accountOptions,
+      undefined,
+      SAFE_READ_RETRY_POLICY,
     );
 
-    return orders.flatMap((order) => {
-      const mapped = mapOpenOrder(order, receivedAt);
-      return mapped ? [mapped] : [];
-    });
+    return {
+      orders: orders.flatMap((order) => {
+        const mapped = mapOpenOrder(order, receivedAt);
+        return mapped ? [mapped] : [];
+      }),
+      snapshotReceivedAt: receivedAt,
+    };
+  }
+
+  async fetchOrder(
+    credentials: AccountCredentials,
+    request: FetchOrderRequest,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawOrderUpdate | undefined> {
+    const receivedAt = Date.now();
+    try {
+      const response = await this.signedRequest<BinancePapiOpenOrder>(
+        "GET",
+        "/papi/v1/um/order",
+        credentials,
+        accountOptions,
+        {
+          symbol: encodeUmSymbol(request.symbol),
+          orderId: request.orderId,
+          origClientOrderId: request.clientOrderId,
+        },
+        SAFE_READ_RETRY_POLICY,
+      );
+
+      return mapOpenOrder(response, receivedAt);
+    } catch (error) {
+      if (isBinanceOrderNotFound(error)) {
+        return undefined;
+      }
+
+      throw error;
+    }
   }
 
   async createOrder(
@@ -681,6 +812,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
             : `${request.reduceOnly}`,
         positionSide: encodePositionSide(request.positionSide),
       },
+      NO_RETRY_POLICY,
     );
 
     const mapped = mapOpenOrder(response, receivedAt);
@@ -709,6 +841,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         orderId: request.orderId,
         origClientOrderId: request.clientOrderId,
       },
+      NO_RETRY_POLICY,
     );
 
     const mapped = mapOpenOrder(response, receivedAt);
@@ -735,6 +868,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       {
         symbol: encodeUmSymbol(request.symbol),
       },
+      NO_RETRY_POLICY,
     );
 
     return responses.flatMap((response) => {
@@ -747,7 +881,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;
@@ -769,17 +903,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;
@@ -790,15 +926,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>({
@@ -863,8 +1001,12 @@ 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 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) {
@@ -873,7 +1015,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,22 +1028,59 @@ 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, {
-      method,
-      headers: {
-        "X-MBX-APIKEY": apiKey,
-      },
-    });
+    const timeoutMs = this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    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),
+      });
 
-    return readJson<T>(response, url);
+      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),
+          },
+        );
+      }
+
+      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");
@@ -909,22 +1092,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,
     );
   }
 
@@ -932,8 +1121,17 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     method: "POST" | "PUT" | "DELETE",
     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);
@@ -943,13 +1141,58 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     const url = `${BINANCE_PAPI_REST_BASE_URL}/papi/v1/listenKey${
       query ? `?${query}` : ""
     }`;
-    const response = await fetch(url, {
-      method,
-      headers: {
-        "X-MBX-APIKEY": apiKey,
-      },
-    });
+    const timeoutMs = this.options.httpTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+    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 readJson<T>(response, url);
+      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;
+}