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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.3.0-beta.2",
+  "version": "0.3.0-beta.4",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",
@@ -16,7 +16,8 @@
   },
   "files": [
     "index.ts",
-    "src/"
+    "src/",
+    "docs/api.md"
   ],
   "scripts": {
     "changeset": "changeset",
@@ -47,11 +48,11 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
     "@changesets/cli": "^2.31.0",
+    "@mindfoldhq/trellis": "^0.4.0",
     "@types/bun": "latest",
     "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@mindfoldhq/trellis": "^0.4.0",
     "bignumber.js": "^11.0.0"
   }
 }

package/src/adapters/binance/adapter.ts

@@ -1,4 +1,7 @@
-import type { MarketDefinition } from "../../types/index.ts";
+import type {
+  MarketDefinition,
+  VenueMarketCapabilities,
+} from "../../types/index.ts";
 import type {
   FundingRateStreamCallbacks,
   FundingRateStreamOptions,
@@ -16,6 +19,12 @@ import {
 
 export class BinanceMarketAdapter implements MarketAdapter {
   readonly venue = "binance" as const;
+  readonly marketCapabilities: VenueMarketCapabilities = {
+    catalog: "supported",
+    l1Book: "supported",
+    fundingRate: "market_dependent",
+    marketTypes: ["spot", "swap", "future"],
+  };
 
   private readonly definitions = new Map<string, BinanceMarketDefinition>();
 

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

@@ -1,7 +1,12 @@
 import { createHmac } from "node:crypto";
 import BigNumber from "bignumber.js";
 import { createManagedWebSocket } from "../../internal/managed-websocket.ts";
-import type { AccountCredentials, PositionSide } from "../../types/index.ts";
+import type {
+  AccountCredentials,
+  PositionSide,
+  VenueAccountCapabilities,
+  VenueOrderCapabilities,
+} from "../../types/index.ts";
 import type {
   CancelAllOrdersRequest,
   CancelOrderRequest,
@@ -51,6 +56,7 @@ interface BinancePapiUmPosition {
   unrealizedProfit?: string;
   liquidationPrice?: string;
   leverage?: string;
+  notional?: string;
   positionSide?: string;
   updateTime?: number;
 }
@@ -280,14 +286,18 @@ function mapBalance(
 function mapAccountRisk(
   input: BinancePapiAccount,
   receivedAt: number,
+  positions: BinancePapiUmPosition[] = [],
 ): RawRiskUpdate | undefined {
   const uniMmr = firstString(input.uniMMR);
   const riskRatio = uniMmr
     ? new BigNumber(1).dividedBy(uniMmr).toString(10)
     : undefined;
+  const equity = firstString(input.accountEquity, input.totalEquity);
+  const actualLeverage = calculateActualLeverage(equity, positions);
   const risk: RawRiskUpdate = {
-    equity: firstString(input.accountEquity, input.totalEquity),
+    equity,
     riskRatio,
+    actualLeverage,
     initialMargin: firstString(
       input.accountInitialMargin,
       input.totalInitialMargin,
@@ -303,6 +313,7 @@ function mapAccountRisk(
   if (
     !risk.equity &&
     !risk.riskRatio &&
+    !risk.actualLeverage &&
     !risk.initialMargin &&
     !risk.maintenanceMargin
   ) {
@@ -312,6 +323,34 @@ function mapAccountRisk(
   return risk;
 }
 
+function calculateActualLeverage(
+  equity: string | undefined,
+  positions: BinancePapiUmPosition[],
+): string | undefined {
+  if (!equity) {
+    return undefined;
+  }
+
+  const equityValue = new BigNumber(equity);
+  if (!equityValue.isFinite() || equityValue.isZero()) {
+    return undefined;
+  }
+
+  const grossExposure = positions.reduce((total, position) => {
+    const notional = firstString(position.notional);
+    if (!notional) {
+      return total;
+    }
+
+    const value = new BigNumber(notional);
+    return value.isFinite() ? total.plus(value.absoluteValue()) : total;
+  }, new BigNumber(0));
+
+  return grossExposure.isZero()
+    ? undefined
+    : grossExposure.dividedBy(equityValue).toString(10);
+}
+
 function mapUmPosition(
   input: BinancePapiUmPosition,
   receivedAt: number,
@@ -334,6 +373,22 @@ function mapUmPosition(
   };
 }
 
+function mapAccountRefresh(
+  account: BinancePapiAccount,
+  positions: BinancePapiUmPosition[],
+  receivedAt: number,
+): RawAccountUpdate {
+  return {
+    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,
@@ -479,6 +534,36 @@ async function readJson<T>(response: Response, url: string): Promise<T> {
 
 export class BinancePrivateAdapter implements PrivateUserDataAdapter {
   readonly venue = "binance" as const;
+  readonly readOnly = false;
+  readonly notes = [
+    "Capabilities describe the current SDK runtime, not Binance's full exchange API surface.",
+    "Funding rate support depends on the market type.",
+    "Order commands currently target Binance PAPI UM USD-M symbols; venue-level order.supported does not mean every Binance market type is orderable.",
+  ];
+  readonly accountCapabilities: VenueAccountCapabilities = {
+    register: "supported",
+    snapshot: "supported",
+    updates: "websocket",
+    balances: "supported",
+    positions: "supported",
+    risk: "supported",
+    lending: "unsupported",
+    credentialsRequired: true,
+  };
+  readonly orderCapabilities: VenueOrderCapabilities = {
+    supported: true,
+    openOrders: "supported",
+    updates: "websocket",
+    create: "supported",
+    cancel: "supported",
+    cancelAll: "symbol",
+    orderTypes: ["limit", "market"],
+    timeInForce: ["gtc", "post_only"],
+    postOnly: true,
+    reduceOnly: true,
+    positionSide: "required_for_hedge",
+    clientOrderId: true,
+  };
 
   async bootstrapAccount(
     credentials: AccountCredentials,
@@ -515,12 +600,35 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         const mapped = mapUmPosition(position, receivedAt);
         return mapped ? [mapped] : [];
       }),
-      risk: mapAccountRisk(account, receivedAt),
+      risk: mapAccountRisk(account, receivedAt, positions),
       exchangeTs: account.updateTime,
       receivedAt,
     };
   }
 
+  async refreshAccount(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawAccountUpdate> {
+    const receivedAt = Date.now();
+    const [account, positions] = await Promise.all([
+      this.signedRequest<BinancePapiAccount>(
+        "GET",
+        "/papi/v1/account",
+        credentials,
+        accountOptions,
+      ),
+      this.signedRequest<BinancePapiUmPosition[]>(
+        "GET",
+        "/papi/v1/um/positionRisk",
+        credentials,
+        accountOptions,
+      ),
+    ]);
+
+    return mapAccountRefresh(account, positions, receivedAt);
+  }
+
   async bootstrapOpenOrders(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

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

@@ -1,6 +1,10 @@
 import BigNumber from "bignumber.js";
 import { AcexError } from "../../errors.ts";
-import type { AccountCredentials } from "../../types/index.ts";
+import type {
+  AccountCredentials,
+  VenueAccountCapabilities,
+  VenueOrderCapabilities,
+} from "../../types/index.ts";
 import type {
   CancelAllOrdersRequest,
   CancelOrderRequest,
@@ -361,6 +365,36 @@ function mapAccount(
 
 export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
   readonly venue = "juplend" as const;
+  readonly readOnly = true;
+  readonly notes = [
+    "Juplend support is limited to read-only lending account views.",
+    "Order and market data managers are not supported for this venue.",
+  ];
+  readonly accountCapabilities: VenueAccountCapabilities = {
+    register: "supported",
+    snapshot: "supported",
+    updates: "polling",
+    balances: "supported",
+    positions: "unsupported",
+    risk: "supported",
+    lending: "supported",
+    credentialsRequired: true,
+  };
+  readonly orderCapabilities: VenueOrderCapabilities = {
+    supported: false,
+    openOrders: "unsupported",
+    updates: "unsupported",
+    create: "unsupported",
+    cancel: "unsupported",
+    cancelAll: "unsupported",
+    orderTypes: [],
+    timeInForce: [],
+    postOnly: false,
+    reduceOnly: false,
+    positionSide: "unsupported",
+    clientOrderId: false,
+    reason: "read_only",
+  };
 
   async bootstrapAccount(
     credentials: AccountCredentials,

package/src/adapters/types.ts

@@ -6,6 +6,9 @@ import type {
   OrderStatus,
   PositionSide,
   Venue,
+  VenueAccountCapabilities,
+  VenueMarketCapabilities,
+  VenueOrderCapabilities,
 } from "../types/index.ts";
 
 export interface StreamHandle {
@@ -69,6 +72,7 @@ export interface FundingRateStreamOptions {
 
 export interface MarketAdapter {
   readonly venue: Venue;
+  readonly marketCapabilities: VenueMarketCapabilities;
   loadMarkets(): Promise<MarketDefinition[]>;
   createL1BookStream(
     market: MarketDefinition,
@@ -117,6 +121,7 @@ export interface RawPositionUpdate {
 export interface RawRiskUpdate {
   equity?: string;
   riskRatio?: string;
+  actualLeverage?: string;
   initialMargin?: string;
   maintenanceMargin?: string;
   exchangeTs?: number;
@@ -210,10 +215,18 @@ export interface PrivateStreamOptions {
 
 export interface PrivateUserDataAdapter {
   readonly venue: Venue;
+  readonly readOnly: boolean;
+  readonly notes: string[];
+  readonly accountCapabilities: VenueAccountCapabilities;
+  readonly orderCapabilities: VenueOrderCapabilities;
   bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
   ): Promise<RawAccountBootstrap>;
+  refreshAccount?(
+    credentials: AccountCredentials,
+    accountOptions?: Record<string, unknown>,
+  ): Promise<RawAccountUpdate>;
   bootstrapOpenOrders(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

package/src/client/context.ts

@@ -75,6 +75,7 @@ export interface PrivateAccountDataConsumer {
     accountId: string,
     venue: Venue,
     update: RawAccountUpdate,
+    options?: { preserveStatus?: boolean },
   ): void;
   onPrivateAccountStreamState(
     accountId: string,

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

@@ -19,6 +19,9 @@ interface PrivateSubscriptionRecord {
   accountReady: boolean;
   orderReady: boolean;
   stream?: StreamHandle;
+  accountRefreshTimer?: ReturnType<typeof setTimeout>;
+  accountRefreshInFlight?: Promise<void>;
+  accountRefreshGeneration: number;
   startPromise?: Promise<void>;
   reconcilePromise?: Promise<void>;
 }
@@ -27,6 +30,16 @@ const DEFAULT_STREAM_OPEN_TIMEOUT_MS = 15_000;
 const DEFAULT_STREAM_RECONNECT_DELAY_MS = 1_000;
 const DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS = 10_000;
 const DEFAULT_LISTEN_KEY_KEEPALIVE_MS = 30 * 60 * 1_000;
+const DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS = 5_000;
+
+function normalizePositiveInterval(
+  value: number | undefined,
+  fallback: number,
+): number {
+  return value !== undefined && Number.isFinite(value) && value > 0
+    ? value
+    : fallback;
+}
 
 export class PrivateSubscriptionCoordinator {
   private readonly context: ClientContext;
@@ -37,6 +50,7 @@ export class PrivateSubscriptionCoordinator {
   private readonly streamReconnectDelayMs: number;
   private readonly streamReconnectMaxDelayMs: number;
   private readonly listenKeyKeepAliveMs: number;
+  private readonly binanceRiskPollIntervalMs: number;
   private readonly juplendPollIntervalMs?: number;
   private readonly records = new Map<string, PrivateSubscriptionRecord>();
 
@@ -62,6 +76,10 @@ export class PrivateSubscriptionCoordinator {
       DEFAULT_STREAM_RECONNECT_MAX_DELAY_MS;
     this.listenKeyKeepAliveMs =
       options.listenKeyKeepAliveMs ?? DEFAULT_LISTEN_KEY_KEEPALIVE_MS;
+    this.binanceRiskPollIntervalMs = normalizePositiveInterval(
+      options.binance?.riskPollIntervalMs,
+      DEFAULT_BINANCE_RISK_POLL_INTERVAL_MS,
+    );
     this.juplendPollIntervalMs = options.juplend?.pollIntervalMs;
   }
 
@@ -81,6 +99,7 @@ export class PrivateSubscriptionCoordinator {
       } else {
         await this.ensureStream(record, account);
         await this.bootstrapAccount(record, account);
+        this.ensureAccountRefreshPolling(record);
       }
     } catch (error) {
       record.accountSubscribed = false;
@@ -96,6 +115,7 @@ export class PrivateSubscriptionCoordinator {
     }
 
     record.accountSubscribed = false;
+    this.stopAccountRefreshPolling(record);
     this.closeIfUnused(record);
   }
 
@@ -153,6 +173,7 @@ export class PrivateSubscriptionCoordinator {
 
   onClientStopping(): void {
     for (const record of this.records.values()) {
+      this.stopAccountRefreshPolling(record);
       this.closeStream(record);
     }
   }
@@ -164,6 +185,7 @@ export class PrivateSubscriptionCoordinator {
     }
 
     this.closeStream(record);
+    this.stopAccountRefreshPolling(record);
     this.records.delete(accountId);
   }
 
@@ -186,6 +208,7 @@ export class PrivateSubscriptionCoordinator {
   private async resumeRecord(record: PrivateSubscriptionRecord): Promise<void> {
     const account = this.getAccount(record.accountId);
     this.closeStream(record);
+    this.stopAccountRefreshPolling(record);
 
     try {
       if (record.venue === "juplend" && record.accountSubscribed) {
@@ -195,6 +218,7 @@ export class PrivateSubscriptionCoordinator {
         await this.ensureStream(record, account);
         if (record.accountSubscribed) {
           await this.bootstrapAccount(record, account);
+          this.ensureAccountRefreshPolling(record);
         }
       }
       if (record.ordersSubscribed) {
@@ -244,6 +268,7 @@ export class PrivateSubscriptionCoordinator {
       ordersSubscribed: false,
       accountReady: false,
       orderReady: false,
+      accountRefreshGeneration: 0,
     };
 
     this.records.set(account.accountId, record);
@@ -259,6 +284,7 @@ export class PrivateSubscriptionCoordinator {
       return;
     }
 
+    this.stopAccountRefreshPolling(record);
     this.closeStream(record);
     this.records.delete(record.accountId);
   }
@@ -268,6 +294,153 @@ export class PrivateSubscriptionCoordinator {
     record.stream = undefined;
   }
 
+  private ensureAccountRefreshPolling(record: PrivateSubscriptionRecord): void {
+    if (
+      record.venue !== "binance" ||
+      !record.accountSubscribed ||
+      record.accountRefreshTimer ||
+      record.accountRefreshInFlight
+    ) {
+      return;
+    }
+
+    this.scheduleAccountRefreshPoll(record);
+  }
+
+  private stopAccountRefreshPolling(record: PrivateSubscriptionRecord): void {
+    record.accountRefreshGeneration += 1;
+    if (record.accountRefreshTimer) {
+      clearTimeout(record.accountRefreshTimer);
+      record.accountRefreshTimer = undefined;
+    }
+    record.accountRefreshInFlight = undefined;
+  }
+
+  private scheduleAccountRefreshPoll(record: PrivateSubscriptionRecord): void {
+    if (record.venue !== "binance" || !record.accountSubscribed) {
+      return;
+    }
+
+    const generation = record.accountRefreshGeneration;
+    record.accountRefreshTimer = setTimeout(() => {
+      record.accountRefreshTimer = undefined;
+      if (
+        generation !== record.accountRefreshGeneration ||
+        record.venue !== "binance" ||
+        !record.accountSubscribed
+      ) {
+        return;
+      }
+
+      let latestAccount: RegisteredAccountRecord;
+      try {
+        latestAccount = this.getAccount(record.accountId);
+      } catch (error) {
+        this.handleAccountRefreshLookupError(record, error);
+        return;
+      }
+
+      record.accountRefreshInFlight = this.refreshAccount(
+        record,
+        latestAccount,
+        generation,
+      )
+        .catch(() => {})
+        .finally(() => {
+          if (generation !== record.accountRefreshGeneration) {
+            return;
+          }
+
+          record.accountRefreshInFlight = undefined;
+          if (record.accountSubscribed && record.venue === "binance") {
+            this.scheduleAccountRefreshPoll(record);
+          }
+        });
+    }, this.binanceRiskPollIntervalMs);
+  }
+
+  private handleAccountRefreshLookupError(
+    record: PrivateSubscriptionRecord,
+    error: unknown,
+  ): void {
+    this.stopAccountRefreshPolling(record);
+    if (error instanceof AcexError && error.code === "ACCOUNT_NOT_FOUND") {
+      return;
+    }
+
+    this.context.publishRuntimeError(
+      "adapter",
+      error instanceof Error
+        ? error
+        : new Error(`Failed to load ${record.venue} account for risk refresh`),
+      {
+        accountId: record.accountId,
+        venue: record.venue,
+      },
+    );
+  }
+
+  private async refreshAccount(
+    record: PrivateSubscriptionRecord,
+    account: RegisteredAccountRecord,
+    generation: number,
+  ): Promise<void> {
+    const adapter = this.getAdapter(record.venue);
+    if (!adapter.refreshAccount) {
+      return;
+    }
+
+    try {
+      const update = await adapter.refreshAccount(account.credentials ?? {}, {
+        ...account.options,
+        accountId: account.accountId,
+      });
+      if (
+        !record.accountSubscribed ||
+        generation !== record.accountRefreshGeneration
+      ) {
+        return;
+      }
+
+      record.accountReady = true;
+      this.accountConsumer.onPrivateAccountUpdate(
+        record.accountId,
+        record.venue,
+        update,
+        { preserveStatus: true },
+      );
+    } catch (error) {
+      if (
+        !record.accountSubscribed ||
+        generation !== record.accountRefreshGeneration
+      ) {
+        return;
+      }
+
+      this.context.publishRuntimeError(
+        "adapter",
+        error instanceof Error
+          ? error
+          : new Error(
+              `Failed to refresh ${record.venue} private account state`,
+            ),
+        {
+          accountId: record.accountId,
+          venue: record.venue,
+        },
+      );
+      this.accountConsumer.onPrivateAccountStreamState(
+        record.accountId,
+        record.venue,
+        {
+          runtimeStatus: "degraded",
+          ready: record.accountReady,
+          reason: "http_failed",
+        },
+      );
+    }
+  }
+
   private async ensureStream(
     record: PrivateSubscriptionRecord,
     account: RegisteredAccountRecord,

package/src/client/runtime.ts

@@ -5,6 +5,7 @@ import type {
   CancelAllOrdersRequest,
   CancelOrderRequest,
   CreateOrderRequest,
+  MarketAdapter,
   PrivateUserDataAdapter,
   RawOrderUpdate,
 } from "../adapters/types.ts";
@@ -35,6 +36,7 @@ import type {
   RegisterAccountResult,
   StopOptions,
   Venue,
+  VenueCapabilities,
 } from "../types/index.ts";
 import {
   type ClientContext,
@@ -45,6 +47,10 @@ import {
   type RegisteredAccountRecord,
 } from "./context.ts";
 import { PrivateSubscriptionCoordinator } from "./private-subscription-coordinator.ts";
+import {
+  getVenueCapabilitiesSnapshot,
+  listVenueCapabilitiesSnapshots,
+} from "./venue-capabilities.ts";
 
 const activeClients = new Set<AcexClientImpl>();
 
@@ -89,13 +95,15 @@ export class AcexClientImpl implements AcexClient, ClientContext {
   private readonly marketManager: MarketManagerImpl;
   private readonly accountManager: AccountManagerImpl;
   private readonly orderManager: OrderManagerImpl;
-  private readonly privateAdapters: Map<string, PrivateUserDataAdapter>;
+  private readonly marketAdapters: Map<Venue, MarketAdapter>;
+  private readonly privateAdapters: Map<Venue, PrivateUserDataAdapter>;
   private readonly privateCoordinator: PrivateSubscriptionCoordinator;
 
   constructor(options: CreateClientOptions = {}) {
     activeClients.add(this);
 
     const marketAdapter = new BinanceMarketAdapter();
+    this.marketAdapters = new Map([[marketAdapter.venue, marketAdapter]]);
     const privateAdapters = [
       new BinancePrivateAdapter(),
       new JuplendPrivateAdapter(),
@@ -142,6 +150,20 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     };
   }
 
+  getVenueCapabilities(venue: Venue): VenueCapabilities {
+    return getVenueCapabilitiesSnapshot(venue, {
+      marketAdapters: this.marketAdapters,
+      privateAdapters: this.privateAdapters,
+    });
+  }
+
+  listVenueCapabilities(): VenueCapabilities[] {
+    return listVenueCapabilitiesSnapshots({
+      marketAdapters: this.marketAdapters,
+      privateAdapters: this.privateAdapters,
+    });
+  }
+
   async registerAccount(
     input: RegisterAccountInput,
   ): Promise<RegisterAccountResult> {