@imbingox/acex 0.1.0-beta.0

package/README.md

@@ -0,0 +1,65 @@
+# acex
+
+Bun-only trading SDK. Current official verification target: `binance`.
+
+## Current Direction
+
+- Official release verification now focuses on the Binance USD-M testnet path.
+- `aster` remains in the repo as an exploration sample (via CCXT / CCXT Pro) but is not part of the current official support commitment.
+- The Aster branch was kept to preserve the generic runtime and adapter validation work without blocking the Binance verification focus.
+
+## Verification Direction
+
+The current official verification path is Binance USD-M testnet. The current validation target scope consists of:
+
+- market WebSocket connectivity
+- private WebSocket connectivity
+- baseline bootstrap for runtime readiness
+- market `placeOrder`
+- reduce-only market `placeOrder`
+
+Run the verification script via:
+
+```bash
+bun run scripts/verify-binance-usdm-testnet.ts
+```
+
+The current script exercises bootstrap, subscription setup, and a real demo market open / reduce-only market close round-trip.
+
+The script expects the following environment variables for Binance USD-M testnet:
+
+- `BINANCE_USDM_API_KEY`
+- `BINANCE_USDM_API_SECRET`
+- `BINANCE_USDM_SYMBOL`
+- `BINANCE_USDM_ORDER_SIZE`
+- `BINANCE_USDM_ORDER_PRICE`
+
+`BINANCE_USDM_ORDER_PRICE` is currently kept as a reference configuration field for notional planning and result logging; the verification orders themselves are submitted as market orders.
+
+## Verified Scope
+
+- Verified exchange: `binance`
+- Verified product: `USD-M`
+- Verified environment: `demo trading / testnet-style`
+- Verified date: `2026-03-31`
+- Verified runtime paths: `subscribeL1Book`, `fetchAccountBaseline`, `fetchOpenOrdersBaseline`, market `placeOrder`, reduce-only market `placeOrder`
+- Verified transports with direct evidence: `public WS (bookTicker)`, `private WS (runtime-level order confirmation + balance confirmation)`, `REST baseline`
+- Supplementary low-level evidence: direct `ccxt.pro.binanceusdm.watchOrders()` and `watchBalance()` both returned during the real demo open/close verification flow on `2026-03-31`
+- Deferred coverage: `amendOrder`, `cancelAllOrders`
+
+## Current Caveats
+
+- Binance `watchTicker()` is not suitable for L1 mapping on USD-M because it returns a 24h ticker payload without `bid` / `ask`; the adapter now uses `watchBidsAsks()` / `bookTicker`.
+- `fetchOpenOrders()` without `symbol` requires `warnOnFetchOpenOrdersWithoutSymbol = false` on the CCXT Binance USD-M exchange instance.
+- Under Bun + CCXT Pro, websocket handles can remain alive after verification. The CLI script now exits explicitly after emitting the result so the verification command terminates deterministically.
+- A simple `place/cancel` flow was insufficient to trigger `watchBalance()` on Binance demo during the 2026-03-31 investigation; the verification script now uses a real market open followed by a reduce-only market close so balance private-WS confirmation is part of the success gate.
+
+## Aster Exploration Notes
+
+The repository still contains the earlier Aster verification script skeleton that can be used for exploratory checks:
+
+```bash
+bun run scripts/verify-aster-live.ts
+```
+
+The Aster assets are retained for experimentation and validation reference but are not the current official release gate.

package/dist/adapters/ccxt/aster-ccxt-adapter.d.ts

@@ -0,0 +1,157 @@
+import type { AdapterAccountBaseline, ExchangeCapabilities, NormalizedAccountEvent, NormalizedMarketEvent, NormalizedOrderEvent } from "../types.js";
+interface CcxtTickerLike {
+    symbol: string;
+    bid: number | string | undefined;
+    bidVolume: number | string | undefined;
+    ask: number | string | undefined;
+    askVolume: number | string | undefined;
+    timestamp?: number;
+}
+interface CcxtMarketLike {
+    symbol: string;
+    base: string;
+    quote: string;
+    type: string;
+    precision: {
+        price: number;
+        amount: number;
+    };
+    active: boolean;
+}
+interface CcxtOrderLike {
+    id?: string;
+    clientOrderId?: string;
+    symbol?: string;
+    side?: string;
+    type?: string;
+    status?: string;
+    amount?: number | string;
+    filled?: number | string;
+    price?: number | string;
+    timestamp?: number;
+}
+interface CcxtBalanceLike {
+    free?: Record<string, number | string | undefined>;
+    used?: Record<string, number | string | undefined>;
+    total?: Record<string, number | string | undefined>;
+}
+interface CcxtExchangeLike {
+    watchTicker(symbol: string): Promise<CcxtTickerLike>;
+    fetchMarkets(): Promise<CcxtMarketLike[]>;
+    fetchBalance(params?: Record<string, unknown>): Promise<CcxtBalanceLike>;
+    fetchOpenOrders(symbol?: string, since?: number, limit?: number, params?: Record<string, unknown>): Promise<CcxtOrderLike[]>;
+    createOrder(symbol: string, type: string, side: "buy" | "sell", amount: number, price?: number, params?: Record<string, unknown>): Promise<CcxtOrderLike>;
+    cancelOrder(id?: string, symbol?: string, params?: Record<string, unknown>): Promise<CcxtOrderLike>;
+}
+export interface CreateCcxtAsterAdapterInput {
+    exchange: CcxtExchangeLike;
+}
+export declare class CcxtAsterAdapter {
+    #private;
+    readonly exchange = "aster";
+    readonly capabilities: ExchangeCapabilities;
+    constructor(input: CreateCcxtAsterAdapterInput);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    subscribeL1Book(input: {
+        exchange: string;
+        symbol: string;
+    }): Promise<void>;
+    subscribeFundingRate(): Promise<void>;
+    watchMarketEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedMarketEvent>;
+    setMarketEventSink(sink: ((event: NormalizedMarketEvent) => void) | undefined): void;
+    watchInternalErrors(): import("../../runtime/async-queue.js").AsyncQueue<Error>;
+    subscribeOrders(): Promise<void>;
+    watchOrderEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedOrderEvent>;
+    setOrderEventSink(sink: ((event: NormalizedOrderEvent) => void) | undefined): void;
+    watchAccountEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedAccountEvent>;
+    setAccountEventSink(sink: ((event: NormalizedAccountEvent) => void) | undefined): void;
+    mapTickerToL1(symbol: string): Promise<{
+        receivedAt: number;
+        exchangeTs?: number;
+        exchange: string;
+        symbol: string;
+        bidPrice: string;
+        bidSize: string;
+        askPrice: string;
+        askSize: string;
+    }>;
+    fetchMarketInfo(): Promise<{
+        exchange: string;
+        symbol: string;
+        baseAsset: string;
+        quoteAsset: string;
+        marketType: string;
+        pricePrecision: number;
+        amountPrecision: number;
+        active: boolean;
+    }[]>;
+    fetchAccountBaseline(accountId: string): Promise<AdapterAccountBaseline>;
+    fetchOpenOrdersBaseline(accountId: string): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        seq: number;
+        receivedAt: number;
+        updatedAt: number;
+        price?: string;
+        accountId: string;
+        exchange: string;
+        symbol: string;
+        side: "buy" | "sell";
+        type: string;
+        status: string;
+        amount: string;
+        filled: string;
+    }[]>;
+    placeOrder(input: {
+        accountId: string;
+        exchange: string;
+        symbol: string;
+        side: "buy" | "sell";
+        amount: string;
+        clientOrderId: string;
+        type: string;
+        price?: string;
+        reduceOnly?: boolean;
+    }): Promise<{
+        receivedAt: number;
+        orderId?: string;
+        clientOrderId: string;
+    }>;
+    amendOrder(input: {
+        accountId: string;
+        exchange: string;
+        clientOrderId?: string;
+        orderId?: string;
+        symbol?: string;
+        newPrice?: string;
+    }): Promise<{
+        receivedAt: number;
+        orderId?: string;
+        clientOrderId?: string;
+    }>;
+    cancelOrder(input: {
+        accountId: string;
+        exchange: string;
+        clientOrderId?: string;
+        orderId?: string;
+    }): Promise<{
+        receivedAt: number;
+        orderId?: string;
+        clientOrderId?: string;
+    }>;
+    cancelAllOrders(input: {
+        accountId: string;
+        exchange: string;
+    }): Promise<{
+        accountId: string;
+        exchange: string;
+        canceledCount: number;
+    }>;
+    getHealth(): {
+        exchange: string;
+        status: string;
+        wsConnected: boolean;
+    };
+}
+export {};

package/dist/adapters/ccxt/aster-ccxt-adapter.js

@@ -0,0 +1,272 @@
+import { createAsyncQueue } from "../../runtime/async-queue.js";
+export class CcxtAsterAdapter {
+    exchange = "aster";
+    capabilities = {
+        publicWs: true,
+        privateWs: true,
+        l1BookStream: true,
+        fundingRateStream: false,
+        accountStream: true,
+        orderStream: true,
+        fetchMarketInfo: true,
+        fetchBalances: true,
+        fetchPositions: false,
+        fetchRisk: false,
+        fetchOpenOrders: true,
+        fetchMyTrades: false,
+        fetchOrderById: false,
+    };
+    #exchange;
+    #started = false;
+    #marketQueue = createAsyncQueue({ maxBufferSize: 100 });
+    #marketEventSink;
+    #internalErrorQueue = createAsyncQueue({ maxBufferSize: 20 });
+    #orderQueue = createAsyncQueue({ maxBufferSize: 100 });
+    #orderEventSink;
+    #accountQueue = createAsyncQueue({ maxBufferSize: 100 });
+    #accountEventSink;
+    constructor(input) {
+        this.#exchange = input.exchange;
+    }
+    async start() {
+        this.#started = true;
+    }
+    async stop() {
+        this.#started = false;
+        this.#marketQueue.close();
+        this.#internalErrorQueue.close();
+        this.#orderQueue.close();
+        this.#accountQueue.close();
+    }
+    async subscribeL1Book(input) {
+        try {
+            const snapshot = await this.mapTickerToL1(input.symbol);
+            this.#emitMarketEvent({
+                type: "l1_book.updated",
+                exchange: snapshot.exchange,
+                symbol: snapshot.symbol,
+                bidPrice: snapshot.bidPrice,
+                bidSize: snapshot.bidSize,
+                askPrice: snapshot.askPrice,
+                askSize: snapshot.askSize,
+                ...(snapshot.exchangeTs === undefined ? {} : { exchangeTs: snapshot.exchangeTs }),
+                receivedAt: snapshot.receivedAt,
+            });
+        }
+        catch (error) {
+            this.#emitInternalError(asError(error));
+            throw error;
+        }
+    }
+    async subscribeFundingRate() { }
+    watchMarketEvents() {
+        return this.#marketQueue;
+    }
+    setMarketEventSink(sink) {
+        this.#marketEventSink = sink;
+    }
+    watchInternalErrors() {
+        return this.#internalErrorQueue;
+    }
+    async subscribeOrders() { }
+    watchOrderEvents() {
+        return this.#orderQueue;
+    }
+    setOrderEventSink(sink) {
+        this.#orderEventSink = sink;
+    }
+    watchAccountEvents() {
+        return this.#accountQueue;
+    }
+    setAccountEventSink(sink) {
+        this.#accountEventSink = sink;
+    }
+    async mapTickerToL1(symbol) {
+        const ticker = await this.#exchange.watchTicker(symbol);
+        if (ticker.bid === undefined ||
+            ticker.bidVolume === undefined ||
+            ticker.ask === undefined ||
+            ticker.askVolume === undefined) {
+            throw new Error("missing required ticker fields");
+        }
+        return {
+            exchange: this.exchange,
+            symbol: ticker.symbol,
+            bidPrice: String(ticker.bid),
+            bidSize: String(ticker.bidVolume),
+            askPrice: String(ticker.ask),
+            askSize: String(ticker.askVolume),
+            ...(ticker.timestamp === undefined ? {} : { exchangeTs: ticker.timestamp }),
+            receivedAt: Date.now(),
+        };
+    }
+    async fetchMarketInfo() {
+        const markets = await this.#exchange.fetchMarkets();
+        return markets.map((market) => {
+            return {
+                exchange: this.exchange,
+                symbol: market.symbol,
+                baseAsset: market.base,
+                quoteAsset: market.quote,
+                marketType: market.type,
+                pricePrecision: market.precision.price,
+                amountPrecision: market.precision.amount,
+                active: market.active,
+            };
+        });
+    }
+    async fetchAccountBaseline(accountId) {
+        const balance = await this.#exchange.fetchBalance();
+        const assets = new Set([
+            ...Object.keys(balance.free ?? {}),
+            ...Object.keys(balance.used ?? {}),
+            ...Object.keys(balance.total ?? {}),
+        ]);
+        const now = Date.now();
+        const balances = Object.fromEntries([...assets].map((asset) => {
+            return [
+                asset,
+                {
+                    accountId,
+                    exchange: this.exchange,
+                    asset,
+                    free: valueToString(balance.free?.[asset]),
+                    used: valueToString(balance.used?.[asset]),
+                    total: valueToString(balance.total?.[asset]),
+                    seq: 0,
+                    receivedAt: now,
+                    updatedAt: now,
+                },
+            ];
+        }));
+        return {
+            balances,
+            positions: [],
+        };
+    }
+    async fetchOpenOrdersBaseline(accountId) {
+        const orders = await this.#exchange.fetchOpenOrders();
+        const now = Date.now();
+        return orders.map((order) => {
+            const symbol = requiredString(order.symbol, "symbol");
+            const side = requiredOrderSide(order.side);
+            const type = requiredString(order.type, "type");
+            const status = requiredString(order.status, "status");
+            const amount = valueToRequiredString(order.amount, "amount");
+            const filled = valueToRequiredString(order.filled, "filled");
+            const updatedAt = order.timestamp ?? now;
+            return {
+                accountId,
+                exchange: this.exchange,
+                symbol,
+                side,
+                type,
+                status,
+                amount,
+                filled,
+                ...(order.price === undefined ? {} : { price: String(order.price) }),
+                seq: 0,
+                receivedAt: now,
+                updatedAt,
+                ...(order.id === undefined ? {} : { orderId: order.id }),
+                ...(order.clientOrderId === undefined ? {} : { clientOrderId: order.clientOrderId }),
+            };
+        });
+    }
+    async placeOrder(input) {
+        const amount = parseFiniteNumber(input.amount, "amount");
+        const price = input.price === undefined ? undefined : parseFiniteNumber(input.price, "price");
+        const order = await this.#exchange.createOrder(input.symbol, input.type, input.side, amount, price, {
+            clientOrderId: input.clientOrderId,
+        });
+        return {
+            ...(order.clientOrderId === undefined
+                ? { clientOrderId: input.clientOrderId }
+                : { clientOrderId: order.clientOrderId }),
+            ...(order.id === undefined ? {} : { orderId: order.id }),
+            receivedAt: Date.now(),
+        };
+    }
+    async amendOrder(input) {
+        return {
+            ...(input.clientOrderId === undefined ? {} : { clientOrderId: input.clientOrderId }),
+            ...(input.orderId === undefined ? {} : { orderId: input.orderId }),
+            receivedAt: Date.now(),
+        };
+    }
+    async cancelOrder(input) {
+        if (input.orderId === undefined && input.clientOrderId === undefined) {
+            return { receivedAt: Date.now() };
+        }
+        const order = await this.#exchange.cancelOrder(input.orderId, undefined, {
+            ...(input.clientOrderId === undefined ? {} : { clientOrderId: input.clientOrderId }),
+        });
+        return {
+            ...(order.clientOrderId === undefined
+                ? input.clientOrderId === undefined
+                    ? {}
+                    : { clientOrderId: input.clientOrderId }
+                : { clientOrderId: order.clientOrderId }),
+            ...(order.id === undefined ? {} : { orderId: order.id }),
+            receivedAt: Date.now(),
+        };
+    }
+    async cancelAllOrders(input) {
+        return {
+            accountId: input.accountId,
+            exchange: input.exchange,
+            canceledCount: 0,
+        };
+    }
+    getHealth() {
+        return {
+            exchange: this.exchange,
+            status: this.#started ? "healthy" : "idle",
+            wsConnected: this.#started,
+        };
+    }
+    #emitMarketEvent(event) {
+        if (this.#marketEventSink !== undefined) {
+            this.#marketEventSink(event);
+            return;
+        }
+        this.#marketQueue.push(event);
+    }
+    #emitInternalError(error) {
+        this.#internalErrorQueue.push(error);
+    }
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function requiredString(value, field) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new Error(`missing required order fields: ${field}`);
+    }
+    return value;
+}
+function requiredOrderSide(value) {
+    if (value !== "buy" && value !== "sell") {
+        throw new Error("missing required order fields: side");
+    }
+    return value;
+}
+function valueToRequiredString(value, field) {
+    if (value === undefined) {
+        throw new Error(`missing required order fields: ${field}`);
+    }
+    return String(value);
+}
+function valueToString(value) {
+    return value === undefined ? "0" : String(value);
+}
+function parseFiniteNumber(value, field) {
+    if (value.trim().length === 0) {
+        throw new Error(`invalid order ${field}`);
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`invalid order ${field}`);
+    }
+    return parsed;
+}

package/dist/adapters/ccxt/binance-usdm-ccxt-adapter.d.ts

@@ -0,0 +1,179 @@
+import type { AdapterAccountBaseline, ExchangeAdapter, ExchangeCapabilities, NormalizedAccountEvent, NormalizedMarketEvent, NormalizedOrderEvent } from "../types.js";
+interface CcxtTickerLike {
+    symbol: string;
+    bid?: number | string;
+    bidVolume?: number | string;
+    ask?: number | string;
+    askVolume?: number | string;
+    timestamp?: number;
+}
+type CcxtBidAskMap = Record<string, CcxtTickerLike | undefined>;
+interface CcxtMarketLike {
+    symbol: string;
+    base: string;
+    quote: string;
+    type: string;
+    precision: {
+        price: number;
+        amount: number;
+    };
+    active: boolean;
+}
+interface CcxtBalanceLike {
+    free?: Record<string, number | string | undefined>;
+    used?: Record<string, number | string | undefined>;
+    total?: Record<string, number | string | undefined>;
+    info?: {
+        totalWalletBalance?: number | string;
+    };
+}
+interface CcxtPositionLike {
+    symbol?: string;
+    side?: string;
+    contracts?: number | string;
+    amount?: number | string;
+    positionAmt?: number | string;
+    timestamp?: number;
+}
+interface CcxtOrderLike {
+    symbol?: string;
+    side?: string;
+    type?: string;
+    status?: string;
+    amount?: number | string;
+    filled?: number | string;
+    price?: number | string;
+    timestamp?: number;
+    id?: string;
+    clientOrderId?: string;
+}
+interface CcxtCreateOrderResult {
+    id?: string;
+    clientOrderId?: string;
+}
+interface CcxtExchangeLike {
+    watchBidsAsks(symbols?: string[]): Promise<CcxtBidAskMap>;
+    fetchMarkets(): Promise<CcxtMarketLike[]>;
+    fetchBalance(params?: Record<string, unknown>): Promise<CcxtBalanceLike>;
+    fetchPositions(symbols: string[], params?: Record<string, unknown>): Promise<CcxtPositionLike[]>;
+    fetchOpenOrders(symbol?: string, since?: number, limit?: number, params?: Record<string, unknown>): Promise<CcxtOrderLike[]>;
+    createOrder(symbol: string, type: string, side: "buy" | "sell", amount: number, price?: number, params?: Record<string, unknown>): Promise<CcxtCreateOrderResult>;
+    close?(): Promise<void>;
+}
+export interface CreateCcxtBinanceUsdMAdapterInput {
+    exchange: CcxtExchangeLike;
+}
+export declare class CcxtBinanceUsdMAdapter implements ExchangeAdapter {
+    #private;
+    readonly exchange = "binance";
+    readonly capabilities: ExchangeCapabilities;
+    constructor(input: CreateCcxtBinanceUsdMAdapterInput);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    subscribeL1Book(input: {
+        exchange: string;
+        symbol: string;
+    }): Promise<void>;
+    subscribeFundingRate(_input: {
+        exchange: string;
+        symbol: string;
+    }): Promise<void>;
+    watchMarketEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedMarketEvent>;
+    setMarketEventSink(sink: ((event: NormalizedMarketEvent) => void) | undefined): void;
+    watchInternalErrors(): import("../../runtime/async-queue.js").AsyncQueue<Error>;
+    subscribeOrders(_input: {
+        accountId: string;
+    }): Promise<void>;
+    watchOrderEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedOrderEvent>;
+    setOrderEventSink(sink: ((event: NormalizedOrderEvent) => void) | undefined): void;
+    watchAccountEvents(): import("../../runtime/async-queue.js").AsyncQueue<NormalizedAccountEvent>;
+    setAccountEventSink(sink: ((event: NormalizedAccountEvent) => void) | undefined): void;
+    mapTickerToL1(symbol: string): Promise<{
+        receivedAt: number;
+        exchangeTs?: number;
+        exchange: string;
+        symbol: string;
+        bidPrice: string;
+        bidSize: string;
+        askPrice: string;
+        askSize: string;
+    }>;
+    fetchMarketInfo(): Promise<{
+        exchange: string;
+        symbol: string;
+        baseAsset: string;
+        quoteAsset: string;
+        marketType: string;
+        pricePrecision: number;
+        amountPrecision: number;
+        active: boolean;
+    }[]>;
+    fetchOpenOrdersBaseline(accountId: string): Promise<{
+        clientOrderId?: string;
+        orderId?: string;
+        seq: number;
+        receivedAt: number;
+        updatedAt: number;
+        price?: string;
+        accountId: string;
+        exchange: string;
+        symbol: string;
+        side: "buy" | "sell";
+        type: string;
+        status: string;
+        amount: string;
+        filled: string;
+    }[]>;
+    fetchAccountBaseline(accountId: string): Promise<AdapterAccountBaseline>;
+    placeOrder(input: {
+        accountId: string;
+        exchange: string;
+        symbol: string;
+        side: "buy" | "sell";
+        amount: string;
+        clientOrderId: string;
+        type: string;
+        price?: string;
+        reduceOnly?: boolean;
+    }): Promise<{
+        receivedAt: number;
+        orderId?: string;
+        clientOrderId: string;
+    }>;
+    amendOrder(input: {
+        accountId: string;
+        exchange: string;
+        clientOrderId?: string;
+        orderId?: string;
+        symbol?: string;
+        newPrice?: string;
+    }): Promise<{
+        receivedAt: number;
+        orderId?: string;
+        clientOrderId?: string;
+    }>;
+    cancelOrder(input: {
+        accountId: string;
+        exchange: string;
+        clientOrderId?: string;
+        orderId?: string;
+    }): Promise<{
+        receivedAt: number;
+        orderId?: string;
+        clientOrderId?: string;
+    }>;
+    cancelAllOrders(_input: {
+        accountId: string;
+        exchange: string;
+    }): Promise<{
+        accountId: string;
+        exchange: string;
+        canceledCount: number;
+    }>;
+    getHealth(): {
+        exchange: string;
+        status: string;
+        wsConnected: boolean;
+    };
+}
+export {};