perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/ondo/adapter.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Ondo Perps adapter — native TradingV2 + legacy ExchangeAdapter shim
+ * (design §10.7, §10.10).
+ *
+ * Signer: HMAC API key only (OndoAgentMeta → ~/.perp/ondo-agents/<keyId>.json).
+ * There is no master-key signing path for trading; read-only adapters serve
+ * public endpoints only.
+ *
+ * Order entry:
+ *   - market orders: IOC LIMIT at the protection price
+ *     alignProtectionPrice(slippagePrice(mark, side, bps), quoteIncrement, side),
+ *     bps = the caller's resolveSlippage() value (design §13.2);
+ *   - TIF (design §13.3): GTC | IOC | ALO, where ALO = GTC + postOnly; FOK is
+ *     not offered (uniform CAPABILITY_UNSUPPORTED, never emulated); a limit order
+ *     without a TIF is GTC;
+ *   - limit orders without a caller clientOrderId get a generated one that
+ *     encodes post-only (`pcli-p-<hex>` / `pcli-n-<hex>`, see ondoClientOrderId)
+ *     because the API never reports postOnly back;
+ *   - TP/SL attached to the entry via takeProfit/stopLoss;
+ *   - stopMarket = position-level stop (POST /v1/perps/stop_order), reduce-only,
+ *     mark-triggered; stopLimit is not offered by the venue;
+ *   - amend = cancel, then place (design §13.10 #10, #11). `size` is the NEW OPEN
+ *     size. The replacement keeps side / reduceOnly / TIF; post-only comes from
+ *     the original's generated clientOrderId, or the caller's explicit TIF — an
+ *     order whose post-only flag is not decodable (placed elsewhere / caller id)
+ *     and no TIF given is refused before anything is cancelled. Fills that race
+ *     the cancel reduce the replacement: replace = size − (filledAtCancel −
+ *     filledAtRead); ≤ 0 (or below the step) → no replacement (reported). Cancel
+ *     outcome unknown → ORDER_PENDING (nothing placed); cancel ok + replacement
+ *     refused → ORDER_PARTIAL { cancelled, placed: null }.
+ *   - cancel-all cancels resting ("open") orders and untriggered stops (position-level
+ *     and entry-attached TP/SL) — see listWorkingOrders.
+ *   - a reduce-only limit order must be IOC (capabilities.reduceOnlyTif); a resting one is
+ *     refused before sending.
+ * Limit prices and TP/SL triggers must be on tick (INVALID_TICK); sizes are
+ * floored to the step (SIZE_TOO_SMALL when that reaches zero).
+ */
+import type { ExchangeAdapter, ExchangeBalance, ExchangeFundingPayment, ExchangeKline, ExchangeMarketInfo, ExchangeOrder, ExchangePosition, ExchangeTrade } from "../interface.js";
+import type { ResolvedSlippage } from "../slippage.js";
+import type { TradingV2 } from "../trading-v2.js";
+import type { VenueCreateContext, VenueDefinition } from "../venue.js";
+import type { AmendRequest, CancelResult, LeverageResult, Network, OrderRef, OrderRequest, OrderResult, VenueMarket } from "../venue-types.js";
+import { type BuilderFeeGate } from "../builder-fee.js";
+import { OndoClient } from "./client.js";
+interface OndoWithdrawal {
+    withdrawal_status: string;
+    withdrawal_id: string;
+    customer_withdrawal_id: string;
+    hash?: string;
+}
+export declare class OndoAdapter implements ExchangeAdapter, TradingV2 {
+    readonly name: "ondo";
+    readonly aliases: readonly ["ondo-perps"];
+    readonly venue: VenueDefinition;
+    readonly network: Network;
+    private readonly caps;
+    private readonly client;
+    private pairsCache;
+    /**
+     * Builder-fee gate (settings builder.ondo; Ondo has no approval step); null = not
+     * configured. Set by the venue definition's create — the adapter never reads settings.
+     */
+    builderFee: BuilderFeeGate | null;
+    /**
+     * GET /v1/perps/candles needs the account's API key (docs.ondoperps.xyz rest-spec.json:
+     * `security: [{"BearerAuth": []}, {"ApiKeyAuth": []}]` — no anonymous `{}` entry, unlike
+     * /v1/perps/depth). `market kline` therefore uses the credentialed adapter (klinesNeedAuth).
+     */
+    readonly klinesRequireAuth = true;
+    constructor(def: VenueDefinition, ctx: VenueCreateContext);
+    /** Raw REST client (same host + HMAC key) — shared with OndoSpotAdapter. */
+    get restClient(): OndoClient;
+    /** Account id from GET /v1/account — the `from.id`/`to.id` of withdrawals and spot↔perp transfers. */
+    accountId(): Promise<string>;
+    /** Withdrawal address book (GET /v1/wallet/address_book) — withdrawals go only to these addresses. */
+    addressBook(): Promise<string[]>;
+    private pairOf;
+    /**
+     * An order the venue returned as "pending" (not yet open / filled) is read back by id
+     * (GET /v1/perps/orders/{id}, bounded 5 × 500 ms) until the venue reports a final status;
+     * still pending → the result stays pending (never assumed open).
+     */
+    private settlePending;
+    private toOrderResult;
+    private toExchangeOrder;
+    private listOrders;
+    /**
+     * Resting orders plus untriggered stop orders. The documented `status` filter enum is open /
+     * canceled / fullyfilled; `untriggered` is a documented order status and the filter accepts it
+     * (live mainnet 2026-10-05) — every returned row's own status is still checked.
+     */
+    private listWorkingOrders;
+    private markPriceOf;
+    /**
+     * `builderCode: { code, feeRateBpsFractional }` for the next order, recorded on `exec`
+     * (builderFee + the reason a configured fee was not attached). Every order body carries it
+     * explicitly — position stops do not inherit it (Ondo integration guide).
+     */
+    private attachBuilderCode;
+    /** stopMarket → position-level stop (POST /v1/perps/stop_order). */
+    private placePositionStop;
+    getVenueMarkets(): Promise<VenueMarket[]>;
+    placeOrder(input: OrderRequest): Promise<OrderResult>;
+    private placeOrderOnVenue;
+    amendOrder(req: AmendRequest): Promise<OrderResult>;
+    cancelByRef(_symbol: string, ref: OrderRef): Promise<CancelResult>;
+    /** Lists resting orders and untriggered stops (listWorkingOrders), then cancels them via the batch endpoint so every result is exact. */
+    cancelAllV2(symbol: string | null): Promise<CancelResult>;
+    applyLeverage(symbol: string, leverage: number, marginMode: "cross" | "isolated" | null): Promise<LeverageResult>;
+    getOrderStatus(_symbol: string, ref: OrderRef): Promise<OrderResult>;
+    getMarkets(): Promise<ExchangeMarketInfo[]>;
+    getOrderbook(symbol: string): Promise<{
+        bids: [string, string][];
+        asks: [string, string][];
+    }>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
+    getFundingHistory(symbol: string, limit?: number): Promise<{
+        time: number;
+        rate: string;
+        price: string | null;
+    }[]>;
+    /** GET /v1/perps/candles — authenticated (see klinesRequireAuth). */
+    getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
+    getBalance(): Promise<ExchangeBalance>;
+    /**
+     * netQuantity is documented as the unsigned position size ("Size of the
+     * position in base currency", example "1.5489" on a short) with the side in
+     * `direction`. A signed value is still accepted: the magnitude is used and
+     * the sign must agree with `direction` (never dropped, never guessed).
+     */
+    getPositions(): Promise<ExchangePosition[]>;
+    getOpenOrders(): Promise<ExchangeOrder[]>;
+    getOrderHistory(limit?: number): Promise<ExchangeOrder[]>;
+    getTradeHistory(limit?: number): Promise<ExchangeTrade[]>;
+    /** `amount` is positive when the account received funding. */
+    getFundingPayments(limit?: number): Promise<ExchangeFundingPayment[]>;
+    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        reduceOnly: boolean;
+        slippage: ResolvedSlippage;
+    }): Promise<OrderResult>;
+    limitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
+        reduceOnly?: boolean;
+        tif?: string;
+    }): Promise<OrderResult>;
+    editOrder(symbol: string, orderId: string, price: string, size: string): Promise<OrderResult>;
+    cancelOrder(symbol: string, orderId: string): Promise<CancelResult>;
+    cancelAllOrders(symbol?: string): Promise<CancelResult>;
+    setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<LeverageResult>;
+    stopOrder(symbol: string, side: "buy" | "sell", size: string, triggerPrice: string, opts?: {
+        limitPrice?: string;
+        reduceOnly?: boolean;
+        triggerType?: "mark" | "last" | "mid";
+    }): Promise<OrderResult>;
+    /**
+     * Withdraw USDC from the perps (margin) wallet to an Ethereum address.
+     * Requires an API key with the `transfer` scope. The destination may need to
+     * be on the account's address book (venue error bad_withdrawal_address).
+     */
+    withdraw(amount: string, destination: string, opts?: {
+        assetId?: number;
+        routeType?: number;
+    }): Promise<OndoWithdrawal & {
+        withdrawalFeeUSD: string;
+    }>;
+}
+export {};