perp-cli 0.12.15 → 0.14.0

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

@@ -0,0 +1,31 @@
+/**
+ * Ondo Perps API-key ("agent") registration (design §10.4).
+ *
+ * The HMAC key id + secret are created by the user in the Ondo Perps UI and
+ * entered via stdin by the CLI (never flags). The secret is persisted only in
+ * ~/.perp/ondo-agents/<keyId>.json (AES-256-GCM, 0600; SSOT Rule #3); settings
+ * keep the OndoAgentMeta pointer only.
+ */
+import type { OndoAgentMeta } from "../../settings.js";
+import type { Network } from "../venue-types.js";
+import { type OndoCredentials } from "./client.js";
+export declare const ONDO_AGENTS_DIR = "ondo-agents";
+export declare const ONDO_APPROVE_REMEDIATION = "perp wallet agent approve ondo";
+/** Read + decrypt the stored key for `keyId`. Throws KEY_NOT_FOUND / SIGNATURE_FAILED. */
+export declare function loadOndoCredentials(keyId: string): OndoCredentials;
+/**
+ * Verify an API key against the venue (authenticated GET /v1/account), reject
+ * accounts whose perps / API-key functionality is disabled, then store it (scopes unknown —
+ * see below). Nothing is written if any step fails.
+ */
+export declare function approveOndoAgent(opts: {
+    agentName: string;
+    keyId: string;
+    secret: string;
+    network: Network;
+}): Promise<OndoAgentMeta>;
+/**
+ * Delete the local keystore for `keyId`. Returns true if a file was removed.
+ * The key itself stays valid on the venue — revoke it in the Ondo Perps UI.
+ */
+export declare function revokeOndoAgentLocal(keyId: string): boolean;

package/dist/exchanges/ondo/agent.js

@@ -0,0 +1,101 @@
+/**
+ * Ondo Perps API-key ("agent") registration (design §10.4).
+ *
+ * The HMAC key id + secret are created by the user in the Ondo Perps UI and
+ * entered via stdin by the CLI (never flags). The secret is persisted only in
+ * ~/.perp/ondo-agents/<keyId>.json (AES-256-GCM, 0600; SSOT Rule #3); settings
+ * keep the OndoAgentMeta pointer only.
+ */
+import { deleteVenueSecret, loadVenueSecret, saveVenueSecret } from "../../agent-wallet/venue-keystore.js";
+import { PerpError } from "../../errors.js";
+import { networkConfig } from "../venue.js";
+import { ondoVenue } from "../venues/ondo.js";
+import { OndoClient } from "./client.js";
+export const ONDO_AGENTS_DIR = "ondo-agents";
+export const ONDO_APPROVE_REMEDIATION = "perp wallet agent approve ondo";
+const KEY_ID_RE = /^ondoKeyId_[A-Za-z0-9_-]+$/;
+const SECRET_RE = /^ondoApiSecret_\S+$/;
+function assertCredentialFormat(keyId, secret) {
+    if (!KEY_ID_RE.test(keyId)) {
+        throw new PerpError("INVALID_PARAMS", `Ondo key id must look like "ondoKeyId_…" (got "${keyId.slice(0, 16)}…")`, {
+            remediation: "Copy the key id exactly as shown in Ondo Perps → API Keys, including the ondoKeyId_ prefix",
+        });
+    }
+    if (!SECRET_RE.test(secret)) {
+        throw new PerpError("INVALID_PARAMS", `Ondo API secret must start with "ondoApiSecret_"`, {
+            remediation: "Copy the secret exactly as shown when the key was created, including the ondoApiSecret_ prefix",
+        });
+    }
+}
+/** Read + decrypt the stored key for `keyId`. Throws KEY_NOT_FOUND / SIGNATURE_FAILED. */
+export function loadOndoCredentials(keyId) {
+    const plaintext = loadVenueSecret(ONDO_AGENTS_DIR, keyId, "", ONDO_APPROVE_REMEDIATION);
+    let parsed;
+    try {
+        parsed = JSON.parse(plaintext);
+    }
+    catch (e) {
+        throw new PerpError("SIGNATURE_FAILED", `Ondo keystore for ${keyId} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, {
+            remediation: ONDO_APPROVE_REMEDIATION,
+        });
+    }
+    const r = parsed;
+    if (!r || typeof r.keyId !== "string" || typeof r.secret !== "string") {
+        throw new PerpError("SIGNATURE_FAILED", `Ondo keystore for ${keyId} is missing keyId/secret`, { remediation: ONDO_APPROVE_REMEDIATION });
+    }
+    if (r.keyId !== keyId) {
+        throw new PerpError("SIGNATURE_FAILED", `Ondo keystore for ${keyId} holds a different key id (${r.keyId})`, {
+            remediation: ONDO_APPROVE_REMEDIATION,
+        });
+    }
+    return { keyId: r.keyId, secret: r.secret };
+}
+/**
+ * Verify an API key against the venue (authenticated GET /v1/account), reject
+ * accounts whose perps / API-key functionality is disabled, then store it (scopes unknown —
+ * see below). Nothing is written if any step fails.
+ */
+export async function approveOndoAgent(opts) {
+    const keyId = opts.keyId.trim();
+    const secret = opts.secret.trim();
+    assertCredentialFormat(keyId, secret);
+    const client = new OndoClient({
+        restUrl: networkConfig(ondoVenue, opts.network).restUrl,
+        network: opts.network,
+        rateLimit: ondoVenue.rateLimit,
+        credentials: { keyId, secret },
+    });
+    const account = await client.get("/v1/account", null);
+    if (account.accountState !== "open") {
+        throw new PerpError("APPROVE_FAILED", `Ondo Perps account ${account.accountID} is ${account.accountState}`, {
+            remediation: "Resolve the account state in the Ondo Perps UI, then retry",
+        });
+    }
+    const disabled = account.disabledFunctionality;
+    if (disabled !== undefined && (disabled.disablePerps === true || disabled.disableAPIKeys === true)) {
+        const what = [disabled.disablePerps === true ? "perps" : null, disabled.disableAPIKeys === true ? "API keys" : null].filter(Boolean).join(" and ");
+        throw new PerpError("APPROVE_FAILED", `Ondo Perps account ${account.accountID} has ${what} disabled`, {
+            remediation: "Check the account's status in the Ondo Perps UI (region / compliance restrictions), then retry",
+        });
+    }
+    // Scopes are not readable with the key itself: GET /v1/api_keys answers API-key auth with 403
+    // key_not_allowed_for_action (live mainnet 2026-10-05, although the OpenAPI spec lists ApiKeyAuth
+    // for it). They are recorded as unknown; a missing scope surfaces on the first call that needs it.
+    const keystorePath = saveVenueSecret(ONDO_AGENTS_DIR, keyId, JSON.stringify({ keyId, secret }), "");
+    return {
+        kind: "ondo",
+        agentName: opts.agentName,
+        keyId,
+        keystorePath,
+        scopes: null,
+        network: opts.network,
+        approvedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Delete the local keystore for `keyId`. Returns true if a file was removed.
+ * The key itself stays valid on the venue — revoke it in the Ondo Perps UI.
+ */
+export function revokeOndoAgentLocal(keyId) {
+    return deleteVenueSecret(ONDO_AGENTS_DIR, keyId);
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Ondo Perps raw REST client (design §9.2: raw fetch + node:crypto HMAC, no SDK).
+ *
+ * Auth (live-verified, scratchpad/sdk-findings.md §2 — the OpenAPI spec's
+ * `X-API-KEY-ID` header name is wrong):
+ *   ONDO-KEY-ID    key id including the "ondoKeyId_" prefix
+ *   ONDO-TIMESTAMP ms since epoch. Docs (api-reference/api_key_authentication): "this may be
+ *                  at most 10 seconds behind or 1 second ahead of server time."
+ *   ONDO-SIGN      hex(HMAC-SHA256(secret incl. "ondoApiSecret_" prefix,
+ *                      timestamp + METHOD + path?query + body))
+ *   The signed `path?query` is byte-identical to the request target sent on
+ *   the wire (URLSearchParams-encoded), matching the docs' "requestPath: full
+ *   path and query parameters of the URL" / Go `req.URL.RequestURI()`.
+ *
+ * Envelope: `{ success, result, error?, error_code?, pageInfo? }`. `pageInfo`
+ * is a sibling of `result` on paginated endpoints.
+ *
+ * Every request first acquires the venue rate-limit bucket (1 req/s default).
+ * No retries, no fallbacks (SSOT Rule #2): HTTP 429 → RATE_LIMITED, any other
+ * failure → PerpError carrying the venue error code.
+ */
+import type { RateLimitPolicy } from "../venue.js";
+import type { Network } from "../venue-types.js";
+export interface OndoCredentials {
+    keyId: string;
+    secret: string;
+}
+export interface OndoClientOptions {
+    restUrl: string;
+    network: Network;
+    rateLimit: RateLimitPolicy;
+    /** null → public endpoints only. */
+    credentials: OndoCredentials | null;
+}
+export type OndoQuery = Record<string, string | number | boolean | null>;
+export interface OndoPage<T> {
+    result: T;
+    nextCursor: string | null;
+}
+/** Per-request timeout (fetch + body read). */
+export declare const ONDO_REQUEST_TIMEOUT_MS = 15000;
+export declare class OndoClient {
+    private readonly opts;
+    private readonly restUrl;
+    private readonly rateKey;
+    constructor(opts: OndoClientOptions);
+    get hasCredentials(): boolean;
+    publicGet<T>(path: string, query: OndoQuery | null): Promise<T>;
+    publicGetPage<T>(path: string, query: OndoQuery | null): Promise<OndoPage<T>>;
+    get<T>(path: string, query: OndoQuery | null): Promise<T>;
+    getPage<T>(path: string, query: OndoQuery | null): Promise<OndoPage<T>>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string, query: OndoQuery | null): Promise<T>;
+    /** Endpoints that answer with a bare GenericResponse (no `result`), e.g. POST /v1/perps/leverage. */
+    postNoResult(path: string, body: unknown): Promise<void>;
+    /** Endpoints that answer with a bare GenericResponse (no `result`), e.g. DELETE /v1/perps/orders. */
+    deleteNoResult(path: string, query: OndoQuery | null): Promise<void>;
+    private sign;
+    private request;
+}

package/dist/exchanges/ondo/client.js

@@ -0,0 +1,297 @@
+/**
+ * Ondo Perps raw REST client (design §9.2: raw fetch + node:crypto HMAC, no SDK).
+ *
+ * Auth (live-verified, scratchpad/sdk-findings.md §2 — the OpenAPI spec's
+ * `X-API-KEY-ID` header name is wrong):
+ *   ONDO-KEY-ID    key id including the "ondoKeyId_" prefix
+ *   ONDO-TIMESTAMP ms since epoch. Docs (api-reference/api_key_authentication): "this may be
+ *                  at most 10 seconds behind or 1 second ahead of server time."
+ *   ONDO-SIGN      hex(HMAC-SHA256(secret incl. "ondoApiSecret_" prefix,
+ *                      timestamp + METHOD + path?query + body))
+ *   The signed `path?query` is byte-identical to the request target sent on
+ *   the wire (URLSearchParams-encoded), matching the docs' "requestPath: full
+ *   path and query parameters of the URL" / Go `req.URL.RequestURI()`.
+ *
+ * Envelope: `{ success, result, error?, error_code?, pageInfo? }`. `pageInfo`
+ * is a sibling of `result` on paginated endpoints.
+ *
+ * Every request first acquires the venue rate-limit bucket (1 req/s default).
+ * No retries, no fallbacks (SSOT Rule #2): HTTP 429 → RATE_LIMITED, any other
+ * failure → PerpError carrying the venue error code.
+ */
+import { createHmac } from "node:crypto";
+import { PerpError, orderOutcomeUnknown } from "../../errors.js";
+import { acquireRate, rateLimitedError } from "../rate-limiter.js";
+/** Venue error code → CLI error code. Codes not listed map to EXCHANGE_ERROR. */
+const ERROR_CODE_MAP = {
+    // margin / balance
+    insufficient_margin: "MARGIN_INSUFFICIENT",
+    account_in_liquidation: "MARGIN_INSUFFICIENT",
+    insufficient_funds: "INSUFFICIENT_BALANCE",
+    withdrawal_error_insufficient_balance: "INSUFFICIENT_BALANCE",
+    // not found
+    order_not_found: "ORDER_NOT_FOUND",
+    twap_order_not_found: "ORDER_NOT_FOUND",
+    invalid_symbol: "SYMBOL_NOT_FOUND",
+    invalid_market: "SYMBOL_NOT_FOUND",
+    // auth
+    api_key_not_found: "KEY_NOT_FOUND",
+    auth_missing: "NO_SIGNER_AVAILABLE",
+    auth_invalid: "SIGNATURE_FAILED",
+    auth_expired: "SIGNATURE_FAILED",
+    signature_mismatch: "SIGNATURE_FAILED",
+    failed_to_decode_hex_signature: "SIGNATURE_FAILED",
+    failed_to_parse_timestamp: "SIGNATURE_FAILED",
+    timestamp_too_far: "SIGNATURE_FAILED",
+    key_doesnt_have_scope: "POLICY_DENIED",
+    ip_not_permitted: "POLICY_DENIED",
+    // rate limit
+    too_many_requests: "RATE_LIMITED",
+    // price / size precision
+    order_invalid_price: "INVALID_TICK",
+    stop_order_trigger_price_invalid_increment: "INVALID_TICK",
+    order_invalid_size: "INVALID_PARAMS",
+    // invalid parameters
+    bad_query_param: "INVALID_PARAMS",
+    invalid_cursor: "INVALID_PARAMS",
+    invalid_leverage: "INVALID_PARAMS",
+    invalid_market_order_fields: "INVALID_PARAMS",
+    invalid_order_type: "INVALID_PARAMS",
+    invalid_stop_order: "INVALID_PARAMS",
+    invalid_time_in_force: "INVALID_PARAMS",
+    invalid_network: "INVALID_PARAMS",
+    invalid_withdrawal_network: "INVALID_PARAMS",
+    withdrawal_invalid_amount: "INVALID_PARAMS",
+    withdrawal_amount_too_small: "SIZE_TOO_SMALL",
+    withdrawal_missing_customer_withdrawal_id: "INVALID_PARAMS",
+    withdrawal_address_not_found: "INVALID_PARAMS",
+    internal_withdrawal_address: "INVALID_PARAMS",
+    withdrawal_not_found: "INVALID_PARAMS",
+    // OpenAPI name; `transfer_amount_too_precise` kept as the earlier observed alias.
+    transfer_amount_precision_overflow: "INVALID_PARAMS",
+    transfer_amount_too_precise: "INVALID_PARAMS",
+    bad_withdrawal_address: "INVALID_PARAMS",
+    clientOrderID_chars_invalid: "INVALID_PARAMS",
+    clientOrderID_length_invalid: "INVALID_PARAMS",
+    order_negative_price: "INVALID_PARAMS",
+    order_negative_size: "INVALID_PARAMS",
+    order_price_outside_min_max_bounds: "INVALID_PARAMS",
+    order_price_outside_safe_bounds: "INVALID_PARAMS",
+    post_only_has_match: "INVALID_PARAMS",
+    reduce_only_flipping_position: "INVALID_PARAMS",
+    reduce_only_increasing_position: "INVALID_PARAMS",
+    reduce_only_invalid_tif: "INVALID_PARAMS",
+    reduce_only_no_open_position: "POSITION_NOT_FOUND",
+    stop_order_crosses_mark_price: "INVALID_PARAMS",
+    stop_order_crosses_order_price: "INVALID_PARAMS",
+    stop_order_trigger_price_exceeds_max: "INVALID_PARAMS",
+    stop_order_trigger_price_negative: "INVALID_PARAMS",
+    order_already_canceled: "INVALID_PARAMS",
+    order_already_fully_filled: "INVALID_PARAMS",
+    order_not_in_cancelable_state: "INVALID_PARAMS",
+    batch_order_empty: "INVALID_PARAMS",
+    batch_order_too_many_orders: "INVALID_PARAMS",
+    batch_cancel_empty: "INVALID_PARAMS",
+    batch_cancel_too_many_orders: "INVALID_PARAMS",
+    withdrawal_duplicate_customer_withdrawal_id: "DUPLICATE_ORDER",
+    clientOrderID_collision: "DUPLICATE_ORDER",
+    // market state
+    mark_price_not_available: "PRICE_STALE",
+    insufficient_liquidity: "ORDER_REJECTED",
+    market_orders_disabled: "CAPABILITY_UNSUPPORTED",
+    trading_disabled: "CAPABILITY_UNSUPPORTED",
+    feature_disabled: "CAPABILITY_UNSUPPORTED",
+    // transient venue-side withdrawal failures
+    withdrawal_try_later: "EXCHANGE_ERROR",
+    withdrawal_system_error: "EXCHANGE_ERROR",
+    withdrawal_failed: "EXCHANGE_ERROR",
+    // risk / limits
+    too_many_open_orders: "RISK_VIOLATION",
+    withdrawal_limit_exceeded: "RISK_VIOLATION",
+    order_matches_against_self: "RISK_VIOLATION",
+    net_position_too_large: "SIZE_TOO_LARGE",
+};
+/** Venue-code-specific remediation; wins over the per-ErrorCode REMEDIATION. */
+const VENUE_REMEDIATION = {
+    bad_withdrawal_address: "Withdrawals go only to addresses in your Ondo Perps address book — add it in the Ondo Perps UI (Withdraw → address book) and wait out any cooldown",
+    withdrawal_address_not_found: "Withdrawals go only to addresses in your Ondo Perps address book — add it in the Ondo Perps UI (Withdraw → address book) and wait out any cooldown",
+    internal_withdrawal_address: "That address belongs to an Ondo Perps account — use an external address from your address book",
+    invalid_withdrawal_network: "Use a network the address book entry supports (avalanche | ethereum | solana)",
+    withdrawal_amount_too_small: "Increase the amount above the venue minimum (the withdrawal fee is shown by: perp account -e ondo)",
+    withdrawal_try_later: "The venue asked to retry later; check withdrawal history before resubmitting",
+    transfer_amount_precision_overflow: "Round the amount to the asset's precision (USDC: 6 decimals)",
+    transfer_amount_too_precise: "Round the amount to the asset's precision (USDC: 6 decimals)",
+    clientOrderID_collision: "Use a new client order id (it must be unique per account)",
+    clientOrderID_chars_invalid: "Client order ids may use letters, digits, '-' and '_' only",
+    clientOrderID_length_invalid: "Shorten the client order id",
+    net_position_too_large: "Reduce the size: the resulting net position exceeds the market's limit",
+    insufficient_liquidity: "Not enough resting liquidity — use a smaller size or a limit order",
+    market_orders_disabled: "Market orders are disabled on this market — place a limit order",
+    trading_disabled: "Trading is disabled on this market right now — check the market status (perp market list -e ondo)",
+    feature_disabled: "This feature is disabled for the account — check the Ondo Perps UI",
+    mark_price_not_available: "Mark price is unavailable — retry shortly",
+};
+const REMEDIATION = {
+    KEY_NOT_FOUND: "Re-register the Ondo API key: perp wallet agent approve ondo",
+    NO_SIGNER_AVAILABLE: "Register an Ondo API key: perp wallet agent approve ondo",
+    SIGNATURE_FAILED: "Check the system clock (the timestamp may be at most 10 s behind or 1 s ahead of server time) and re-register the key: perp wallet agent approve ondo",
+    POLICY_DENIED: "Grant the key the required scope (trade / transfer) or whitelist this IP in the Ondo Perps UI, then re-approve",
+    MARGIN_INSUFFICIENT: "Reduce size/leverage or deposit more collateral",
+    INSUFFICIENT_BALANCE: "Deposit more USDC or reduce the amount",
+    SYMBOL_NOT_FOUND: "List markets with: perp market list -e ondo",
+    INVALID_TICK: "Align price/size with the market tick and step (perp market list -e ondo)",
+};
+/** Per-request timeout (fetch + body read). */
+export const ONDO_REQUEST_TIMEOUT_MS = 15_000;
+export class OndoClient {
+    opts;
+    restUrl;
+    rateKey;
+    constructor(opts) {
+        this.opts = opts;
+        this.restUrl = opts.restUrl.replace(/\/+$/, "");
+        this.rateKey = `ondo:${opts.network}`;
+    }
+    get hasCredentials() {
+        return this.opts.credentials !== null;
+    }
+    // ── Public ──
+    async publicGet(path, query) {
+        return (await this.request("GET", path, query, null, false, true)).result;
+    }
+    async publicGetPage(path, query) {
+        return this.request("GET", path, query, null, false, true);
+    }
+    // ── Authenticated ──
+    async get(path, query) {
+        return (await this.request("GET", path, query, null, true, true)).result;
+    }
+    async getPage(path, query) {
+        return this.request("GET", path, query, null, true, true);
+    }
+    async post(path, body) {
+        return (await this.request("POST", path, null, body, true, true)).result;
+    }
+    async delete(path, query) {
+        return (await this.request("DELETE", path, query, null, true, true)).result;
+    }
+    /** Endpoints that answer with a bare GenericResponse (no `result`), e.g. POST /v1/perps/leverage. */
+    async postNoResult(path, body) {
+        await this.request("POST", path, null, body, true, false);
+    }
+    /** Endpoints that answer with a bare GenericResponse (no `result`), e.g. DELETE /v1/perps/orders. */
+    async deleteNoResult(path, query) {
+        await this.request("DELETE", path, query, null, true, false);
+    }
+    // ── Core ──
+    sign(creds, timestamp, method, pathWithQuery, body) {
+        return createHmac("sha256", creds.secret).update(timestamp + method + pathWithQuery + body).digest("hex");
+    }
+    async request(method, path, query, body, auth, expectResult) {
+        let pathWithQuery = path;
+        if (query) {
+            const qs = new URLSearchParams();
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== null)
+                    qs.append(k, String(v));
+            }
+            const s = qs.toString();
+            if (s)
+                pathWithQuery = `${path}?${s}`;
+        }
+        const bodyStr = body === null ? "" : JSON.stringify(body);
+        // Rate-limit wait happens BEFORE the timestamp is taken so a queued request
+        // never goes out with a stale ONDO-TIMESTAMP (at most 10 s behind / 1 s ahead).
+        await acquireRate(this.rateKey, this.opts.rateLimit, path);
+        const headers = { Accept: "application/json" };
+        if (bodyStr)
+            headers["Content-Type"] = "application/json";
+        if (auth) {
+            const creds = this.opts.credentials;
+            if (!creds) {
+                throw new PerpError("NO_SIGNER_AVAILABLE", `Ondo Perps: ${method} ${path} requires an API key`, {
+                    remediation: "Register an Ondo API key: perp wallet agent approve ondo",
+                });
+            }
+            const ts = Date.now().toString();
+            headers["ONDO-KEY-ID"] = creds.keyId;
+            headers["ONDO-TIMESTAMP"] = ts;
+            headers["ONDO-SIGN"] = this.sign(creds, ts, method, pathWithQuery, bodyStr);
+        }
+        // Timeout covers the whole exchange (headers + body). A GET failure is definite
+        // (nothing changed); a POST failure may have reached the venue → outcome unknown
+        // (ORDER_PENDING, never resubmit — design §12.3).
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), ONDO_REQUEST_TIMEOUT_MS);
+        let res;
+        let text;
+        try {
+            res = await fetch(`${this.restUrl}${pathWithQuery}`, {
+                method,
+                headers,
+                ...(bodyStr ? { body: bodyStr } : {}),
+                signal: controller.signal,
+            });
+            text = await res.text();
+        }
+        catch (e) {
+            const aborted = controller.signal.aborted;
+            const reason = aborted ? `timed out after ${ONDO_REQUEST_TIMEOUT_MS}ms` : `failed: ${e instanceof Error ? e.message : String(e)}`;
+            if (method !== "GET") {
+                throw orderOutcomeUnknown("ondo", `${method} ${path}`, new Error(`request ${reason}`), `Do NOT resubmit — the request may have been applied. Check open orders, positions and balances on ondo`);
+            }
+            throw new PerpError(aborted ? "TIMEOUT" : "EXCHANGE_UNREACHABLE", `Ondo Perps: ${method} ${path} ${reason}`, {
+                exchange: "ondo",
+                remediation: `Check network connectivity to ${this.restUrl}`,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res.status === 429) {
+            throw rateLimitedError("ondo", res.headers.get("retry-after"), text);
+        }
+        // A write (POST / DELETE) answered 5xx, or 2xx with an unreadable body, may have been applied.
+        const pending = (why) => orderOutcomeUnknown("ondo", `${method} ${path}`, new Error(why), "Do NOT resubmit — the request may have been applied. Check open orders, positions and balances on ondo");
+        if (method !== "GET" && res.status >= 500)
+            throw pending(`HTTP ${res.status}: ${text.slice(0, 200)}`);
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            if (method !== "GET" && res.ok)
+                throw pending(`unreadable response (HTTP ${res.status})`);
+            throw new PerpError("EXCHANGE_ERROR", `Ondo Perps: ${method} ${path} returned non-JSON (HTTP ${res.status})`, {
+                httpStatus: res.status,
+                body: text.slice(0, 500),
+            });
+        }
+        if (!res.ok || parsed.success !== true) {
+            throw ondoError(method, path, res.status, parsed);
+        }
+        if (!expectResult)
+            return { result: undefined, nextCursor: null };
+        if (!("result" in parsed)) {
+            throw new PerpError("EXCHANGE_ERROR", `Ondo Perps: ${method} ${path} response has no result`, {
+                httpStatus: res.status,
+                body: text.slice(0, 500),
+            });
+        }
+        const next = parsed.pageInfo?.nextCursor;
+        return { result: parsed.result, nextCursor: typeof next === "string" && next !== "" ? next : null };
+    }
+}
+function ondoError(method, path, httpStatus, env) {
+    const venueCode = typeof env.error_code === "string" ? env.error_code : null;
+    const venueMsg = typeof env.error === "string" ? env.error : "unknown error";
+    let code = venueCode !== null && venueCode in ERROR_CODE_MAP ? ERROR_CODE_MAP[venueCode] : "EXCHANGE_ERROR";
+    if (code === "EXCHANGE_ERROR" && venueCode === "not_found" && (path.startsWith("/v1/perps/orders") || path.startsWith("/v1/spot/orders")))
+        code = "ORDER_NOT_FOUND";
+    const remediation = (venueCode !== null ? VENUE_REMEDIATION[venueCode] : undefined) ?? REMEDIATION[code];
+    return new PerpError(code, `Ondo Perps: ${venueMsg}${venueCode ? ` (${venueCode})` : ""} [${method} ${path}, HTTP ${httpStatus}]`, {
+        venueCode,
+        httpStatus,
+        ...(remediation !== undefined ? { remediation } : {}),
+    });
+}

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

@@ -0,0 +1,122 @@
+/**
+ * Ondo Perps funding (mainnet only) + withdrawal address book.
+ *
+ * Deposit = a plain ERC-20 transfer of USDC to the account's own funding address
+ * (docs.ondoperps.xyz/funding-ondo-perps, api-reference/integration_guide "Deposit USDC").
+ *   - The address comes from POST /v1/wallet/deposit_address/list {coins:["USDC"]}: the FIRST
+ *     listed row for (USDC, chosen network, wallet "margin"), whose depositDestination.id must be
+ *     this account's id (GET /v1/account accountID) — anything else is refused.
+ *   - POST /v1/provision_address creates ANOTHER address on every call, so it is called only when
+ *     the list has no address for that network.
+ *   - USDC token addresses / chain ids / RPCs are pinned in the venue definition
+ *     (venues/ondo.ts ONDO_DEPOSIT_CHAINS); decimals are read on-chain.
+ *   - With a probe amount the transfer is two-step: probe → wait until GET /v1/wallet/deposits
+ *     shows it confirmed → remainder. A probe that is not credited within the window stops the
+ *     flow (ORDER_PENDING with the probe tx hash); the remainder is NOT sent.
+ *
+ * Address book: withdrawals go only to addresses on the account's address book. An address is
+ * added by signing a SIWE challenge with the account's wallet
+ * (POST /v1/auth/erc-4361/address_book/get_challenge → personal_sign → …/complete_challenge).
+ */
+import { PerpError } from "../../errors.js";
+import { type TxSigner } from "../../evm-master-tx.js";
+import type { Network } from "../venue-types.js";
+import { type OndoDepositChain } from "../venues/ondo.js";
+/** The slice of OndoClient these flows use (authenticated calls). */
+export interface OndoFundsClient {
+    get<T>(path: string, query: null): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    postNoResult(path: string, body: unknown): Promise<void>;
+}
+export declare const ONDO_DEPOSIT_CREDIT_TIMEOUT_MS = 600000;
+export declare const ONDO_DEPOSIT_CREDIT_POLL_MS = 10000;
+export interface PollTiming {
+    timeoutMs: number;
+    pollMs: number;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+/** Funding by on-chain transfer exists on mainnet only (the sandbox is funded with demo funds). */
+export declare function requireOndoDepositNetwork(net: Network): void;
+export declare function ondoDepositChain(raw: string): OndoDepositChain;
+/**
+ * The first listed USDC funding address of `network` for the margin wallet. Returns null when the
+ * list has none for that network (the caller may then provision one). Refuses when the first
+ * listed address does not belong to `accountId`.
+ */
+export declare function selectOndoDepositAddress(rows: unknown, network: OndoDepositChain, accountId: string): string | null;
+export interface OndoFundingAddress {
+    accountId: string;
+    address: string;
+    provisioned: boolean;
+}
+/** Resolve (or, only when none exists, provision) the account's USDC funding address on `network`. */
+export declare function resolveOndoDepositAddress(client: OndoFundsClient, network: OndoDepositChain): Promise<OndoFundingAddress>;
+export interface OndoDepositPlan {
+    network: Network;
+    chain: OndoDepositChain;
+    chainId: number;
+    chainLabel: string;
+    rpcUrl: string;
+    token: string;
+    /** Read on-chain (decimals()). */
+    decimals: number;
+    amount: string;
+    amountRaw: bigint;
+    /** null = single transfer. */
+    probe: string | null;
+    probeRaw: bigint | null;
+    depositor: string;
+    depositAddress: string;
+    accountId: string;
+    tokenBalance: bigint;
+}
+/** Read-only checks on the pinned chain. Throws before anything is signed. */
+export declare function planOndoDeposit(p: {
+    network: Network;
+    chain: OndoDepositChain;
+    amount: string;
+    probe: string | null;
+    depositor: string;
+    funding: OndoFundingAddress;
+}): Promise<OndoDepositPlan>;
+/**
+ * Wait until GET /v1/wallet/deposits lists this transaction as `confirmed`. Not listed / pending /
+ * unreadable until the deadline → ORDER_PENDING with the tx hash (the transfer itself is mined).
+ */
+export declare function awaitOndoDepositCredit(readDeposits: () => Promise<unknown>, txHash: string, what: string, timing: PollTiming): Promise<void>;
+export interface OndoDepositResult {
+    transfers: Array<{
+        step: "probe" | "deposit";
+        txHash: string;
+        amount: string;
+    }>;
+    depositAddress: string;
+}
+/**
+ * Send the USDC transfer(s). With a probe: probe → credited → remainder → credited; the
+ * remainder is never sent while the probe is uncredited (the ORDER_PENDING carries `sent`).
+ */
+export declare function executeOndoDeposit(plan: OndoDepositPlan, sign: TxSigner, readDeposits: () => Promise<unknown>, timing: PollTiming): Promise<OndoDepositResult>;
+/** Withdrawal addresses on the account's address book (GET /v1/wallet/address_book). */
+export declare function ondoAddressBook(client: OndoFundsClient): Promise<string[]>;
+/** Refusal for a withdraw destination that is not on the address book (nothing was sent). */
+export declare function ondoAddressNotOnBook(destination: string, book: readonly string[]): PerpError;
+/** A challenge the master key will sign must be about this address book entry — never an arbitrary message. */
+export declare function assertOndoAddressBookChallenge(message: string, wallet: string, withdrawalAddress: string, restUrl: string): void;
+export interface OndoAddressBookAddResult {
+    address: string;
+    alreadyListed: boolean;
+    listed: boolean;
+    challengeId: string | null;
+}
+/**
+ * Add the signing wallet's own address to the address book: get_challenge → personal_sign
+ * (EIP-191) with the wallet → complete_challenge. Challenge chainId "1" (enum: 1 | 43114).
+ */
+export declare function addOndoAddressBookEntry(client: OndoFundsClient, p: {
+    wallet: string;
+    restUrl: string;
+    label: string | null;
+    signMessage: (message: string) => Promise<string>;
+}): Promise<OndoAddressBookAddResult>;