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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.6",
+  "version": "0.4.0-beta.7",
   "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/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/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

@@ -6,6 +6,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"

package/src/managers/market-manager.ts

@@ -38,6 +38,7 @@ import type {
   SubscribeL1BookInput,
   SubscriptionActivity,
   Venue,
+  VenueServerTime,
 } from "../types/index.ts";
 
 export interface MarketManagerOptions {
@@ -201,6 +202,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);
@@ -601,6 +620,21 @@ export class MarketManagerImpl
     return wrapped;
   }
 
+  private createServerTimeFetchError(venue: Venue, error: unknown): AcexError {
+    const wrapped = new AcexError(
+      "MARKET_SERVER_TIME_FETCH_FAILED",
+      `Failed to fetch server time from ${venue}`,
+    );
+    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;

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>;