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

package/package.json

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

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

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,
@@ -210,6 +214,10 @@ 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>,

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

package/src/client/venue-capabilities.ts

@@ -0,0 +1,109 @@
+import type {
+  MarketAdapter,
+  PrivateUserDataAdapter,
+} from "../adapters/types.ts";
+import type {
+  VenueAccountCapabilities,
+  VenueCapabilities,
+  VenueMarketCapabilities,
+  VenueOrderCapabilities,
+} from "../types/client.ts";
+import { SUPPORTED_VENUES, type Venue } from "../types/shared.ts";
+
+const unsupportedAccount: VenueAccountCapabilities = {
+  register: "unsupported",
+  snapshot: "unsupported",
+  updates: "unsupported",
+  balances: "unsupported",
+  positions: "unsupported",
+  risk: "unsupported",
+  lending: "unsupported",
+  credentialsRequired: false,
+};
+
+const unsupportedOrder: Omit<VenueOrderCapabilities, "reason"> = {
+  supported: false,
+  openOrders: "unsupported",
+  updates: "unsupported",
+  create: "unsupported",
+  cancel: "unsupported",
+  cancelAll: "unsupported",
+  orderTypes: [],
+  timeInForce: [],
+  postOnly: false,
+  reduceOnly: false,
+  positionSide: "unsupported",
+  clientOrderId: false,
+};
+
+const typeOnlyNotes = [
+  "Venue is declared in public types but has no runtime adapter yet.",
+];
+
+const unsupportedMarket: VenueMarketCapabilities = {
+  catalog: "unsupported",
+  l1Book: "unsupported",
+  fundingRate: "unsupported",
+  marketTypes: [],
+};
+
+export interface VenueCapabilityAdapterRegistry {
+  marketAdapters: ReadonlyMap<Venue, MarketAdapter>;
+  privateAdapters: ReadonlyMap<Venue, PrivateUserDataAdapter>;
+}
+
+export function getVenueCapabilitiesSnapshot(
+  venue: Venue,
+  registry: VenueCapabilityAdapterRegistry,
+): VenueCapabilities {
+  const marketAdapter = registry.marketAdapters.get(venue);
+  const privateAdapter = registry.privateAdapters.get(venue);
+
+  return cloneVenueCapabilities({
+    venue,
+    runtimeStatus: marketAdapter || privateAdapter ? "available" : "type_only",
+    readOnly: privateAdapter?.readOnly ?? false,
+    notes:
+      privateAdapter?.notes ??
+      (marketAdapter
+        ? [
+            "Capabilities describe the current SDK runtime, not the venue's full API surface.",
+          ]
+        : typeOnlyNotes),
+    market: marketAdapter?.marketCapabilities ?? unsupportedMarket,
+    account: privateAdapter?.accountCapabilities ?? unsupportedAccount,
+    order: privateAdapter?.orderCapabilities ?? {
+      ...unsupportedOrder,
+      reason: "not_implemented",
+    },
+  });
+}
+
+export function listVenueCapabilitiesSnapshots(
+  registry: VenueCapabilityAdapterRegistry,
+): VenueCapabilities[] {
+  return SUPPORTED_VENUES.map((venue) =>
+    getVenueCapabilitiesSnapshot(venue, registry),
+  );
+}
+
+function cloneVenueCapabilities(
+  capabilities: VenueCapabilities,
+): VenueCapabilities {
+  return {
+    ...capabilities,
+    notes: [...capabilities.notes],
+    market: {
+      ...capabilities.market,
+      marketTypes: [...capabilities.market.marketTypes],
+    },
+    account: {
+      ...capabilities.account,
+    },
+    order: {
+      ...capabilities.order,
+      orderTypes: [...capabilities.order.orderTypes],
+      timeInForce: [...capabilities.order.timeInForce],
+    },
+  };
+}

package/src/types/client.ts

@@ -7,8 +7,10 @@ import type {
   MarketDataStatus,
   MarketManager,
   MarketStatusChangedEvent,
+  MarketType,
 } from "./market.ts";
 import type {
+  CreateOrderType,
   OrderDataStatus,
   OrderManager,
   OrderStatusChangedEvent,
@@ -56,6 +58,73 @@ export interface ClientEventStreams {
   errors(): AsyncIterable<AcexInternalError>;
 }
 
+export type VenueRuntimeStatus = "available" | "type_only" | "reserved";
+
+export type VenueCapabilitySupport = "supported" | "unsupported";
+
+export type VenueCapabilityReason =
+  | "not_implemented"
+  | "read_only"
+  | "market_type_unsupported"
+  | "sdk_reserved";
+
+export type FundingRateCapability = VenueCapabilitySupport | "market_dependent";
+
+export type PrivateUpdateCapability = "websocket" | "polling" | "unsupported";
+
+export type CancelAllOrdersCapability = "symbol" | "account" | "unsupported";
+
+export type PositionSideCapability =
+  | "optional"
+  | "required_for_hedge"
+  | "unsupported";
+
+export type OrderTimeInForceCapability = "gtc" | "post_only";
+
+export interface VenueMarketCapabilities {
+  catalog: VenueCapabilitySupport;
+  l1Book: VenueCapabilitySupport;
+  fundingRate: FundingRateCapability;
+  marketTypes: MarketType[];
+}
+
+export interface VenueAccountCapabilities {
+  register: VenueCapabilitySupport;
+  snapshot: VenueCapabilitySupport;
+  updates: PrivateUpdateCapability;
+  balances: VenueCapabilitySupport;
+  positions: VenueCapabilitySupport;
+  risk: VenueCapabilitySupport;
+  lending: VenueCapabilitySupport;
+  credentialsRequired: boolean;
+}
+
+export interface VenueOrderCapabilities {
+  supported: boolean;
+  openOrders: VenueCapabilitySupport;
+  updates: PrivateUpdateCapability;
+  create: VenueCapabilitySupport;
+  cancel: VenueCapabilitySupport;
+  cancelAll: CancelAllOrdersCapability;
+  orderTypes: CreateOrderType[];
+  timeInForce: OrderTimeInForceCapability[];
+  postOnly: boolean;
+  reduceOnly: boolean;
+  positionSide: PositionSideCapability;
+  clientOrderId: boolean;
+  reason?: VenueCapabilityReason;
+}
+
+export interface VenueCapabilities {
+  venue: Venue;
+  runtimeStatus: VenueRuntimeStatus;
+  readOnly: boolean;
+  notes: string[];
+  market: VenueMarketCapabilities;
+  account: VenueAccountCapabilities;
+  order: VenueOrderCapabilities;
+}
+
 export interface AcexClient {
   readonly market: MarketManager;
   readonly account: AccountManager;
@@ -64,6 +133,8 @@ export interface AcexClient {
 
   getStatus(): ClientStatus;
   getHealth(): ClientHealthSnapshot;
+  getVenueCapabilities(venue: Venue): VenueCapabilities;
+  listVenueCapabilities(): VenueCapabilities[];
 
   registerAccount(input: RegisterAccountInput): Promise<RegisterAccountResult>;
   updateAccountCredentials(