perp-cli 0.14.3 → 0.15.0

package/dist/exchanges/aster.js

@@ -18,6 +18,7 @@
  * Docs: https://docs.asterdex.com/product/aster-perpetuals/api/api-documentation
  * Base: https://fapi.asterdex.com
  */
+import { nonEmptyOrListed } from "./unknown-symbol.js";
 import { accountCacheEpoch } from "../cache.js";
 import { isExpired } from "../agent-wallet/expiry.js";
 import { classifyError, DEFINITE_ORDER_FAILURE_CODES, isTransportFailure, orderNotSent, orderOutcomeUnknown, PerpError, sendFailure } from "../errors.js";
@@ -30,7 +31,7 @@ import { approvalFromMax, bpsToRate, builderGateOf, NO_BUILDER, rateToBps, requi
 import { ASTER_CLIENT_ID_RE, ASTER_FUNDS_CHAINS, asterVenue } from "./venues/aster.js";
 import { assertAsterWithdrawAmount, assertAsterWithdrawSignature, parseAsterWithdrawLimits, requireAsterFundsNetwork, } from "./aster-funds.js";
 import { nextAsterNonce } from "./aster-nonce.js";
-/** Common TIF (§13.3) → Aster perp timeInForce. Live exchangeInfo lists GTC/IOC/GTX/HIDDEN — no FOK. */
+/** Common TIF → Aster perp timeInForce. Live exchangeInfo lists GTC/IOC/GTX/HIDDEN — no FOK. */
 function asterTif(raw) {
     const t = raw.toUpperCase();
     if (t === "GTC" || t === "IOC" || t === "GTX")
@@ -72,6 +73,16 @@ export function asterIocOutcome(raw) {
     const filledSize = plainQty(r.executedQty);
     return filledSize === null ? null : { filledSize, final: true };
 }
+/** The numeric `code` of an Aster error body ({"code":-1121,"msg":"Invalid symbol."}); null when absent. */
+function asterErrorCode(body) {
+    try {
+        const j = JSON.parse(body);
+        return typeof j.code === "number" ? j.code : null;
+    }
+    catch {
+        return null; // not JSON (e.g. an HTML error page): no venue code
+    }
+}
 /**
  * Order-placement refusals by documented venue code (asterdex/api-docs V3 futures "Error
  * Codes"; "Codes are universal,but messages can vary"). [PerpError code, docs name, remediation].
@@ -283,7 +294,7 @@ export class AsterAdapter {
             return null;
         }
     }
-    // ── Spot host access (design §12, used by AsterSpotAdapter) ──
+    // ── Spot host access (used by AsterSpotAdapter) ──
     /**
      * Aster spot REST host. Spot shares the perp EIP-712 Domain B signing
      * (chainId 1666 mainnet / 714 testnet) and the per-agent nonce space.
@@ -466,7 +477,7 @@ export class AsterAdapter {
             this._ingestPriceFilters(info.symbols);
         }
         if (!this._priceFilters.has(apiSymbol)) {
-            throw new PerpError("SYMBOL_NOT_FOUND", `Aster market ${apiSymbol} not found in exchangeInfo`, { exchange: "aster" });
+            throw new PerpError("SYMBOL_NOT_FOUND", `Aster market ${apiSymbol} not found in exchangeInfo`, { exchange: "aster", remediation: "List markets: perp -e aster market list" });
         }
         const f = this._priceFilters.get(apiSymbol);
         if (!f) {
@@ -475,7 +486,7 @@ export class AsterAdapter {
         return f;
     }
     /**
-     * Declared protection-price reference (§13.10 #5): the venue mark price from
+     * Declared protection-price reference: the venue mark price from
      * GET /fapi/v3/premiumIndex — the same price PERCENT_PRICE is evaluated against.
      * No runtime substitute (no mid / last fallback): unavailable → PRICE_STALE.
      */
@@ -555,7 +566,7 @@ export class AsterAdapter {
             side: t.isBuyerMaker ? "sell" : "buy",
             price: String(t.price ?? "0"),
             size: String(t.qty ?? "0"),
-            fee: "0",
+            fee: null, // the public tape carries no fee
         }));
     }
     async getFundingHistory(symbol, limit = 10) {
@@ -566,7 +577,8 @@ export class AsterAdapter {
         if (!Array.isArray(data)) {
             throw new PerpError("EXCHANGE_ERROR", `Aster fundingRate history is not a list (${JSON.stringify(data).slice(0, 120)})`, { exchange: "aster" });
         }
-        return data.map((d) => {
+        // `200 []` for an unlisted symbol (live 2026-10-14): checked against the market directory.
+        return nonEmptyOrListed(this, symbol, data.map((d) => {
             const time = Number(d.fundingTime);
             if (d.fundingTime === undefined || d.fundingTime === null || !Number.isFinite(time) || time <= 0) {
                 throw new PerpError("EXCHANGE_ERROR", `Aster fundingRate row without a numeric fundingTime: ${JSON.stringify(d).slice(0, 160)}`, { exchange: "aster" });
@@ -576,7 +588,7 @@ export class AsterAdapter {
                 rate: venueRateField(d.fundingRate, "fundingRate fundingRate", "aster"),
                 price: d.markPrice ? String(d.markPrice) : null,
             };
-        });
+        }), this._fromApi(this._toApi(symbol)));
     }
     /**
      * Candles over [startTime, endTime]. GET /fapi/v3/klines returns at most 1500 bars per request
@@ -607,10 +619,11 @@ export class AsterAdapter {
             for (const k of data) {
                 const time = Number(k[0]);
                 const trades = Number(k[8]);
-                if (!Number.isFinite(time) || !Number.isFinite(trades)) {
-                    throw new PerpError("EXCHANGE_ERROR", `Aster kline row without open time / trade count: ${JSON.stringify(k).slice(0, 120)}`, { exchange: "aster" });
+                const numeric = (v) => (typeof v === "string" || typeof v === "number") && String(v).trim() !== "" && Number.isFinite(Number(v));
+                if (!Number.isFinite(time) || !Number.isFinite(trades) || !numeric(k[5]) || !numeric(k[7])) {
+                    throw new PerpError("EXCHANGE_ERROR", `Aster kline row without open time / volume / quote volume / trade count: ${JSON.stringify(k).slice(0, 120)}`, { exchange: "aster" });
                 }
-                out.push({ time, open: String(k[1]), high: String(k[2]), low: String(k[3]), close: String(k[4]), volume: String(k[5]), trades });
+                out.push({ time, open: String(k[1]), high: String(k[2]), low: String(k[3]), close: String(k[4]), volume: String(k[5]), quoteVolume: String(k[7]), trades });
             }
             if (data.length < ASTER_KLINE_PAGE)
                 break;
@@ -975,7 +988,7 @@ export class AsterAdapter {
     }
     // ── Trading ──
     async marketOrder(symbol, side, size, opts) {
-        // Design §13.2 / §13.10 #6: never native MARKET (no price cap) — an IOC LIMIT at the
+        // Never native MARKET (no price cap) — an IOC LIMIT at the
         // protection price (mark ± opts.slippage.bps, tick-aligned toward crossing, inside
         // PRICE_FILTER / PERCENT_PRICE). newOrderRespType=RESULT makes the response carry the
         // final IOC status (FILLED / EXPIRED) and executedQty.
@@ -1072,7 +1085,7 @@ export class AsterAdapter {
         const clientOrderId = opts?.clientOrderId === undefined ? null : requireAsterClientOrderId(opts.clientOrderId);
         let params;
         try {
-            // Common TIF names (§13.3): GTC / IOC / ALO→GTX (GTX accepted as alias); FOK unsupported.
+            // Common TIF names: GTC / IOC / ALO→GTX (GTX accepted as alias); FOK unsupported.
             const tif = asterTif(opts?.tif ?? "GTC");
             // Price must already be on PRICE_FILTER.tickSize — validated, never rounded (INVALID_TICK).
             const px = requireOnTick(price, (await this._symbolPriceFilters(apiSymbol)).tickSize);
@@ -1104,7 +1117,7 @@ export class AsterAdapter {
     /**
      * Native modify (PUT /fapi/v3/order, V3 futures docs "Modify Order"): LIMIT orders
      * only; TIF (incl. GTX) and reduceOnly stay on the order. `size` is the NEW UNFILLED
-     * quantity (§13.10 #10); the venue's `quantity` is the order total, so
+     * quantity; the venue's `quantity` is the order total, so
      * quantity = size + executedQty (read just before). A fill landing between the read
      * and the PUT can only shrink the remainder, never over-size it. A venue rejection
      * leaves the original order untouched (docs).
@@ -1757,6 +1770,11 @@ export class AsterAdapter {
         if (!res.ok) {
             const text = await res.text();
             const clean = text.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 120);
+            // -1121 BAD_SYMBOL ("Invalid symbol.", live on /fapi/v3/depth for an unlisted symbol): the
+            // symbol does not exist — SYMBOL_NOT_FOUND, not an UNKNOWN 500.
+            if (asterErrorCode(text) === -1121) {
+                throw new PerpError("SYMBOL_NOT_FOUND", `Aster: ${clean} [${method} ${path}]`, { exchange: "aster", remediation: "List markets: perp -e aster market list" });
+            }
             throw new Error(`${method} ${path} failed (${res.status}): ${clean}`);
         }
         return res.json();

package/dist/exchanges/builder-fee.d.ts

@@ -21,7 +21,7 @@
  *     `builder: { b: <address>, f: <tenths of a bp> }`; max 0.1% perps / 1% spot; status
  *     info `{ type: "maxBuilderFee", user, builder }`. HIP-3 dexes are not covered by the
  *     docs → never attached there.
- * - pacifica     https://pacifica.gitbook.io/docs/programs/builder-program.md
+ * - pacifica     https://docs.pacifica.fi/programs/builder-program.md
  *     approve_builder_code { builder_code, max_fee_rate } signed by the account; per-order
  *     `builder_code` on create_market / create / stop/create / positions/tpsl. TWAP
  *     (create_twap_order) does not document builder_code → never sent there.

package/dist/exchanges/builder-fee.js

@@ -21,7 +21,7 @@
  *     `builder: { b: <address>, f: <tenths of a bp> }`; max 0.1% perps / 1% spot; status
  *     info `{ type: "maxBuilderFee", user, builder }`. HIP-3 dexes are not covered by the
  *     docs → never attached there.
- * - pacifica     https://pacifica.gitbook.io/docs/programs/builder-program.md
+ * - pacifica     https://docs.pacifica.fi/programs/builder-program.md
  *     approve_builder_code { builder_code, max_fee_rate } signed by the account; per-order
  *     `builder_code` on create_market / create / stop/create / positions/tpsl. TWAP
  *     (create_twap_order) does not document builder_code → never sent there.
@@ -49,6 +49,7 @@
  */
 import { PerpError, classifyError, isDefiniteOrderFailure, isTransportFailure, isUnknownOutcomeServerError } from "../errors.js";
 import { isVenueId } from "./venue-types.js";
+import { VARIATIONAL_READ_ONLY_REMEDIATION } from "./venues/variational.js";
 export const BUILDER_FEE_CAPABILITIES = {
     hyperliquid: {
         approval: "master", identity: "address", perpCapBps: 10, spotCapBps: 100, hip3: false, testnet: true,
@@ -56,7 +57,7 @@ export const BUILDER_FEE_CAPABILITIES = {
     },
     pacifica: {
         approval: "master", identity: "code", perpCapBps: 10, spotCapBps: null, hip3: null, testnet: true,
-        feeStepBps: 0.01, feeKind: "max", docs: "https://pacifica.gitbook.io/docs/programs/builder-program.md",
+        feeStepBps: 0.01, feeKind: "max", docs: "https://docs.pacifica.fi/programs/builder-program.md",
     },
     aster: {
         approval: "master", identity: "address", perpCapBps: 10, spotCapBps: null, hip3: null, testnet: false,
@@ -73,11 +74,21 @@ export const BUILDER_FEE_CAPABILITIES = {
     lighter: null,
     "lighter-rh": null,
     arcus: null,
+    risex: null,
+    txflow: null,
+    variational: null,
+    grvt: null,
+    extended: null,
 };
 /** Why a venue has no builder-fee support (shown in CAPABILITY_UNSUPPORTED). */
 export const BUILDER_FEE_UNSUPPORTED = {
     lighter: "not yet implemented in perp-cli — the official lighter-go signer can sign ApproveIntegrator and the per-order integrator fields, but perp-cli sends them as 0 (https://apidocs.lighter.xyz/docs/partner-integration)",
     "lighter-rh": "not yet implemented in perp-cli — Lighter RH uses the same official lighter-go signer; partner-attribution fields are sent as 0 (https://apidocs.rh.lighter.xyz/docs/partner-attribution.md)",
+    risex: "not implemented yet in perp-cli (RISEx builder codes are planned; note the venue's \"bps\" field is parts-per-million)",
+    txflow: "TxFlow is integrated through an unofficial read-only API (market data only)",
+    variational: VARIATIONAL_READ_ONLY_REMEDIATION,
+    grvt: "GRVT is read-only (market data) in this version; trading is planned for a later release",
+    extended: "Extended is available for market data only in this version (trading is planned for a later release)",
     arcus: "Arcus has no perps builder fee; its integrator fee applies to the spot router only and needs a partner key from Arcus (https://docs.arcus.xyz/concepts/spot-router)",
 };
 export function builderFeeUnsupported(venue) {

package/dist/exchanges/canonical-symbols.d.ts

@@ -1,7 +1,6 @@
 /**
  * Cross-venue canonical symbols — the single mapping source used to decide
- * that two markets on different venues are the same underlying
- * (design §4 L4, §10.9).
+ * that two markets on different venues are the same underlying.
  *
  * Rules by asset class:
  * - crypto:  ticker identity after the adapter strips its quote suffix, plus

package/dist/exchanges/canonical-symbols.js

@@ -1,7 +1,6 @@
 /**
  * Cross-venue canonical symbols — the single mapping source used to decide
- * that two markets on different venues are the same underlying
- * (design §4 L4, §10.9).
+ * that two markets on different venues are the same underlying.
  *
  * Rules by asset class:
  * - crypto:  ticker identity after the adapter strips its quote suffix, plus
@@ -47,19 +46,44 @@ export const EXPLICIT_CANONICAL = {
     "hl:xyz|SILVER": "SILVER",
     "qfex|GOLD": "GOLD",
     "qfex|SILVER": "SILVER",
+    "risex|XAU": "GOLD",
+    "risex|XAG": "SILVER",
+    "txflow|XAU": "GOLD",
+    "txflow|XAG": "SILVER",
+    "variational|XAU": "GOLD",
+    "variational|XAG": "SILVER",
+    "grvt|XAU": "GOLD",
+    "grvt|XAG": "SILVER",
+    "extended|XAU": "GOLD",
+    "extended|XAG": "SILVER",
     // Crude oil (WTI)
     "ondo|WTI": "CRUDE_OIL_WTI",
     "hl:xyz|CL": "CRUDE_OIL_WTI",
     "hl:flx|OIL": "CRUDE_OIL_WTI",
     // QFEX CL blends expiring futures; roll-week gaps are caught by the cross-venue price filter.
     "qfex|CL": "CRUDE_OIL_WTI",
+    "risex|CL": "CRUDE_OIL_WTI",
+    // Brent crude
+    "risex|BZ": "CRUDE_OIL_BRENT",
+    "txflow|BZ": "CRUDE_OIL_BRENT",
+    "txflow|CL": "CRUDE_OIL_WTI",
+    "variational|BZ": "CRUDE_OIL_BRENT",
+    "variational|CL": "CRUDE_OIL_WTI",
+    "grvt|BZ": "CRUDE_OIL_BRENT",
+    "grvt|CL": "CRUDE_OIL_WTI",
+    "extended|WTI": "CRUDE_OIL_WTI",
+    "extended|XBR": "CRUDE_OIL_BRENT",
     // US equity indices
     "ondo|US500": "SPX",
     "ondo|US100": "NDX",
     "qfex|US500": "SPX",
     "qfex|US100": "NDX",
+    // Extended SPX500m / TECH100m: S&P 500 / Nasdaq-100 index perps (uiName SPX-USD / NDX-USD).
+    "extended|SPX500M": "SPX",
+    "extended|TECH100M": "NDX",
     // FX
     "ondo|USDJPY": "USDJPY",
+    "extended|USDJPY": "USDJPY",
 };
 /** Pairs verified to be DIFFERENT products despite similar names. Never match. */
 export const NEVER_MATCH = new Set([

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

@@ -0,0 +1,37 @@
+/**
+ * Derive (derive.xyz, formerly Lyra) v3 public JSON-RPC over HTTP — official API, no auth.
+ *
+ *  - `POST <base>/public/<method>` with the params object as the body → `{id, result}` or
+ *    `{id, error: {code, message, data}}` (docs.derive.xyz/error-codes.md; live 2026-10-18).
+ *  - Errors are all PerpErrors, each with a remediation: transport failure → EXCHANGE_UNREACHABLE;
+ *    HTTP 429 or RPC -32000..-32099 → RATE_LIMITED (retry hint from the RPC `data` "Retry after {ms} ms",
+ *    else the `retry-after` header); any other RPC error → EXCHANGE_ERROR. A JSON-RPC -32602 is a
+ *    Derive-side rejection too: user input is validated before any request, so it is never reported as
+ *    the user's INVALID_PARAMS. Every RPC error carries `details.rpcCode` / `rpcData` so callers can
+ *    classify the venue code (12001 instrument_not_found → SYMBOL_NOT_FOUND is done by the caller,
+ *    which knows what was asked).
+ *  - Public budget (docs rate-limits.md, mainnet reference): 5 TPS per IP, FIXED 5 s window of 25
+ *    points, 1 point per request. The local bucket (burst 5, 4/s) allows at most 5 + 4·5 = 25 in any 5 s.
+ */
+import { PerpError } from "../../errors.js";
+import type { RateLimitPolicy } from "../venue.js";
+import type { Network } from "../venue-types.js";
+export declare const DERIVE_REST_URLS: Readonly<Record<Network, string>>;
+export declare const DERIVE_HTTP_TIMEOUT_MS = 15000;
+export declare const DERIVE_RATE_LIMIT: RateLimitPolicy;
+/** Derive application code for an unknown instrument / currency (`instrument_not_found`). */
+export declare const DERIVE_INSTRUMENT_NOT_FOUND = 12001;
+/** JSON-RPC invalid params — Derive also uses it for "Ticker not found for instrument" (live 2026-10-18). */
+export declare const DERIVE_INVALID_PARAMS = -32602;
+/** Shape drift: an explicit EXCHANGE_ERROR, never a guessed value. */
+export declare function deriveShapeError(what: string): PerpError;
+/** The RPC error code a Derive call failed with, or null (not an RPC error). */
+export declare function deriveRpcCode(e: unknown): number | null;
+export declare class DeriveClient {
+    readonly network: Network;
+    private readonly baseUrl;
+    private readonly rateLimit;
+    constructor(network: Network, baseUrl?: string, rateLimit?: RateLimitPolicy);
+    /** `public/<method>`; resolves with `result`, every failure is a PerpError. */
+    call<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+}

package/dist/exchanges/derive/client.js

@@ -0,0 +1,135 @@
+/**
+ * Derive (derive.xyz, formerly Lyra) v3 public JSON-RPC over HTTP — official API, no auth.
+ *
+ *  - `POST <base>/public/<method>` with the params object as the body → `{id, result}` or
+ *    `{id, error: {code, message, data}}` (docs.derive.xyz/error-codes.md; live 2026-10-18).
+ *  - Errors are all PerpErrors, each with a remediation: transport failure → EXCHANGE_UNREACHABLE;
+ *    HTTP 429 or RPC -32000..-32099 → RATE_LIMITED (retry hint from the RPC `data` "Retry after {ms} ms",
+ *    else the `retry-after` header); any other RPC error → EXCHANGE_ERROR. A JSON-RPC -32602 is a
+ *    Derive-side rejection too: user input is validated before any request, so it is never reported as
+ *    the user's INVALID_PARAMS. Every RPC error carries `details.rpcCode` / `rpcData` so callers can
+ *    classify the venue code (12001 instrument_not_found → SYMBOL_NOT_FOUND is done by the caller,
+ *    which knows what was asked).
+ *  - Public budget (docs rate-limits.md, mainnet reference): 5 TPS per IP, FIXED 5 s window of 25
+ *    points, 1 point per request. The local bucket (burst 5, 4/s) allows at most 5 + 4·5 = 25 in any 5 s.
+ */
+import { PerpError, extractErrorMessage } from "../../errors.js";
+import { acquireRate, rateLimitedError } from "../rate-limiter.js";
+export const DERIVE_REST_URLS = {
+    mainnet: "https://api.derive.xyz/v3",
+    testnet: "https://testnet.api.derive.xyz/v3",
+};
+export const DERIVE_HTTP_TIMEOUT_MS = 15_000;
+export const DERIVE_RATE_LIMIT = { capacity: 5, refillPerSec: 4, weights: null };
+/** Derive application code for an unknown instrument / currency (`instrument_not_found`). */
+export const DERIVE_INSTRUMENT_NOT_FOUND = 12001;
+/** JSON-RPC invalid params — Derive also uses it for "Ticker not found for instrument" (live 2026-10-18). */
+export const DERIVE_INVALID_PARAMS = -32602;
+const UNREACHABLE_REMEDIATION = "Check the network / api.derive.xyz status and retry";
+const RATE_LIMIT_REMEDIATION = "Derive's public budget is 5 requests/s per IP (25 per 5 s window); wait and retry";
+/** Shape drift: an explicit EXCHANGE_ERROR, never a guessed value. */
+export function deriveShapeError(what) {
+    return new PerpError("EXCHANGE_ERROR", `Derive API returned an unexpected shape: ${what}`, {
+        exchange: "derive",
+        remediation: "Derive's v3 API response changed; perp-cli needs an update to read it",
+    });
+}
+/** The RPC error code a Derive call failed with, or null (not an RPC error). */
+export function deriveRpcCode(e) {
+    if (!(e instanceof PerpError))
+        return null;
+    const code = e.structured.details?.rpcCode;
+    return typeof code === "number" ? code : null;
+}
+export class DeriveClient {
+    network;
+    baseUrl;
+    rateLimit;
+    constructor(network, baseUrl = DERIVE_REST_URLS[network], rateLimit = DERIVE_RATE_LIMIT) {
+        this.network = network;
+        this.baseUrl = baseUrl;
+        this.rateLimit = rateLimit;
+    }
+    /** `public/<method>`; resolves with `result`, every failure is a PerpError. */
+    async call(method, params) {
+        await acquireRate(`derive:${this.baseUrl}`, this.rateLimit, method);
+        const what = `Derive public/${method}`;
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}/public/${method}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(params),
+                signal: AbortSignal.timeout(DERIVE_HTTP_TIMEOUT_MS),
+            });
+        }
+        catch (e) {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `${what}: ${extractErrorMessage(e)}`, { exchange: "derive", remediation: UNREACHABLE_REMEDIATION });
+        }
+        const text = await res.text().catch((e) => {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `${what}: response body unreadable (${extractErrorMessage(e)})`, {
+                exchange: "derive", remediation: UNREACHABLE_REMEDIATION,
+            });
+        });
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = undefined;
+        }
+        const rpcError = body !== null && typeof body === "object" ? body.error : undefined;
+        const hasRpcError = rpcError !== undefined && rpcError !== null;
+        if (res.status === 429) {
+            // The RPC body's "Retry after N ms" is preferred; the retry-after header only when the body has none.
+            const fromRpc = hasRpcError ? retryAfterMsOf(rpcError) : null;
+            if (fromRpc !== null)
+                throw rateLimited(`${what}: HTTP 429`, fromRpc, rpcCodeOf(rpcError));
+            throw rateLimitedError("derive", res.headers.get("retry-after"), text);
+        }
+        if (hasRpcError)
+            throw rpcErrorOf(what, rpcError);
+        if (!res.ok) {
+            throw new PerpError("EXCHANGE_ERROR", `${what}: HTTP ${res.status} ${text.slice(0, 200)}`, {
+                exchange: "derive", status: res.status, remediation: "Derive answered with an HTTP error; check api.derive.xyz status and retry",
+            });
+        }
+        if (body === undefined)
+            throw deriveShapeError(`${method} returned a non-JSON body`);
+        if (body === null || typeof body !== "object" || !("result" in body))
+            throw deriveShapeError(`${method} returned no result`);
+        return body.result;
+    }
+}
+function rpcErrorOf(what, err) {
+    if (err === null || typeof err !== "object")
+        return deriveShapeError(`${what}: error is not an object`);
+    const { code, message, data } = err;
+    if (typeof code !== "number" || typeof message !== "string")
+        return deriveShapeError(`${what}: error without code / message`);
+    const detail = typeof data === "string" && data !== "" && data !== message ? `${message} (${data})` : message;
+    if (code <= -32000 && code >= -32099)
+        return rateLimited(`${what}: ${detail}`, retryAfterMsOf(err), code);
+    return new PerpError("EXCHANGE_ERROR", `${what}: request rejected by Derive: ${detail} [code ${code}]`, {
+        exchange: "derive", rpcCode: code, rpcData: typeof data === "string" ? data : null,
+        remediation: "Retry later; if it persists, Derive's API changed and perp-cli needs an update",
+    });
+}
+function rateLimited(message, retryAfterMs, rpcCode) {
+    return new PerpError("RATE_LIMITED", message, {
+        exchange: "derive",
+        ...(rpcCode !== null ? { rpcCode } : {}),
+        ...(retryAfterMs !== null ? { retryAfterMs } : {}),
+        remediation: RATE_LIMIT_REMEDIATION,
+    });
+}
+function rpcCodeOf(err) {
+    const code = err !== null && typeof err === "object" ? err.code : undefined;
+    return typeof code === "number" ? code : null;
+}
+/** "Retry after {ms} ms" from an RPC error's `data`, or null. */
+function retryAfterMsOf(err) {
+    const data = err !== null && typeof err === "object" ? err.data : undefined;
+    const m = typeof data === "string" ? /Retry after (\d+) ?ms/i.exec(data) : null;
+    return m !== null ? Number(m[1]) : null;
+}

package/dist/exchanges/derive/options.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Derive options — read-only `OptionsVenue` over the v3 public API (official, no auth).
+ *
+ * Reads (docs.derive.xyz/openapi.json, shapes checked live 2026-10-18):
+ *  - `get_all_currencies` → currencies with an `option` asset (underlyings).
+ *  - `get_all_instruments {instrument_type:"option", currency, expired:false, page_size:1000, page}`
+ *    → instruments; `option_details {expiry (unix s), strike, option_type "C"|"P"}`. Paginated
+ *    (`pagination.num_pages`, page_size ≤ 1000). `is_active:false` = listed for a future activation
+ *    (`scheduled_activation`), not tradable and with no ticker — left out of expiries / chains.
+ *    An unknown currency is RPC 12001.
+ *  - `get_tickers {instrument_type:"option", currency, expiry_date:"YYYYMMDD"}` → `{tickers: {name: TickerSlim}}`;
+ *    expiry_date is required for options. ONE call per chain (never one per instrument).
+ *  - `get_instrument` + `get_ticker` for a single quote (unknown instrument = RPC 12001).
+ *
+ * Ticker encoding (live): an empty book side is price "0" / size "0" → `null` side; an IV the
+ * pricer could not compute (no quote, or a quote below intrinsic) is "0" → `null`; 24 h high / low
+ * are "0" when there were no trades → `null`. Greeks are passed through verbatim (a delta of 0 is real).
+ */
+import type { Network } from "../venue-types.js";
+import { type OptionChain, type OptionChainQuery, type OptionExpiries, type OptionExpiry, type OptionKind, type OptionQuote, type OptionsVenue, type OptionUnderlyings } from "../options-interface.js";
+import { DeriveClient } from "./client.js";
+/** One option instrument, as perp-cli uses it. */
+export interface DeriveOptionInstrument {
+    name: string;
+    underlying: string;
+    quoteCurrency: string;
+    kind: OptionKind;
+    strike: string;
+    expiryMs: number;
+    /** UTC YYYY-MM-DD of the expiry. */
+    expiry: string;
+    isActive: boolean;
+    /** ms epoch of `scheduled_activation`. */
+    activationMs: number;
+}
+/** ms epoch → UTC YYYY-MM-DD. */
+export declare function utcDate(ms: number): string;
+/** User expiry, exactly "2026-12-25" or "20261225" (not mixed) → YYYY-MM-DD; anything else INVALID_PARAMS. */
+export declare function normalizeExpiry(input: string): string;
+/** User underlying → venue currency (upper case); INVALID_PARAMS for anything that is not a ticker. */
+export declare function normalizeUnderlying(input: string): string;
+export declare function parseDeriveInstrument(raw: unknown): DeriveOptionInstrument;
+/** A ticker_slim snapshot (get_ticker / get_tickers value) of `inst` → OptionQuote. */
+export declare function parseDeriveOptionTicker(raw: unknown, inst: DeriveOptionInstrument): OptionQuote;
+/** Distinct active expiries of `instruments`, soonest first. */
+export declare function expiriesOf(instruments: readonly DeriveOptionInstrument[]): OptionExpiry[];
+/** The `n` strikes closest to `price` (ties → lower strike), returned ascending. */
+export declare function strikesAround(strikes: readonly string[], price: string, n: number): string[];
+/**
+ * Chain for one expiry from its instruments and the `get_tickers` map. Rows come from the listed
+ * instruments; a listed instrument without a ticker leaves its side null and is named in
+ * `missingTickers`. Index / forward are those of the newest ticker (largest `t`) — one ticker's values,
+ * not an average over the expiry.
+ */
+export declare function buildChain(underlying: string, expiry: OptionExpiry, selection: OptionChain["expirySelection"], instruments: readonly DeriveOptionInstrument[], tickersRaw: unknown, strikesAroundAtm: number | null): OptionChain;
+export declare class DeriveOptionsVenue implements OptionsVenue {
+    private readonly client;
+    readonly id = "derive";
+    readonly displayName = "Derive";
+    constructor(client: DeriveClient);
+    static forNetwork(network: Network): DeriveOptionsVenue;
+    listUnderlyings(): Promise<OptionUnderlyings>;
+    /** Every non-expired option instrument of `underlying` (all pages). 12001 → SYMBOL_NOT_FOUND. */
+    instruments(underlying: string): Promise<DeriveOptionInstrument[]>;
+    listExpiries(underlyingInput: string): Promise<OptionExpiries>;
+    getChain(q: OptionChainQuery): Promise<OptionChain>;
+    getQuote(instrumentInput: string): Promise<OptionQuote>;
+}