perp-cli 0.14.3 → 0.16.0

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,73 @@
+/**
+ * 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;
+/**
+ * CLI option name → Derive wire name: upper-cased, and a decimal point in the strike written as
+ * the venue's underscore (`PUMP-20261023-0.0045-C` → `PUMP-20261023-0_0045-C`).
+ */
+export declare function deriveInstrumentName(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>;
+}

package/dist/exchanges/derive/options.js

@@ -0,0 +1,379 @@
+/**
+ * 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 { PerpError } from "../../errors.js";
+import { OPTIONS_SCHEMA, } from "../options-interface.js";
+import { DERIVE_INSTRUMENT_NOT_FOUND, DERIVE_INVALID_PARAMS, DeriveClient, deriveRpcCode, deriveShapeError } from "./client.js";
+const VENUE = "derive";
+const PAGE_SIZE = 1000;
+function obj(v, what) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        throw deriveShapeError(`${what} is not an object`);
+    return v;
+}
+function str(o, key, what) {
+    const v = o[key];
+    if (typeof v !== "string")
+        throw deriveShapeError(`${what}.${key} is not a string`);
+    return v;
+}
+/** A decimal string (checked to parse as a finite number; returned verbatim). */
+function dec(o, key, what) {
+    const v = str(o, key, what);
+    if (v.trim() === "" || !Number.isFinite(Number(v)))
+        throw deriveShapeError(`${what}.${key} is not a decimal ("${v}")`);
+    return v;
+}
+function int(o, key, what) {
+    const v = o[key];
+    if (typeof v !== "number" || !Number.isInteger(v))
+        throw deriveShapeError(`${what}.${key} is not an integer`);
+    return v;
+}
+/** Derive's "0" placeholder → null; anything else verbatim. */
+function nonZero(v) {
+    return Number(v) === 0 ? null : v;
+}
+// ── dates ──
+/** ms epoch → UTC YYYY-MM-DD. */
+export function utcDate(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+/** User expiry, exactly "2026-12-25" or "20261225" (not mixed) → YYYY-MM-DD; anything else INVALID_PARAMS. */
+export function normalizeExpiry(input) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input.trim()) ?? /^(\d{4})(\d{2})(\d{2})$/.exec(input.trim());
+    const iso = m !== null ? `${m[1]}-${m[2]}-${m[3]}` : null;
+    if (iso === null || Number.isNaN(Date.parse(`${iso}T00:00:00Z`)) || utcDate(Date.parse(`${iso}T00:00:00Z`)) !== iso) {
+        throw new PerpError("INVALID_PARAMS", `Invalid expiry "${input}" — expected YYYY-MM-DD (UTC)`, {
+            remediation: `List expiries: perp -e ${VENUE} options expiries <UNDERLYING>`,
+        });
+    }
+    return iso;
+}
+/** User underlying → venue currency (upper case); INVALID_PARAMS for anything that is not a ticker. */
+export function normalizeUnderlying(input) {
+    const u = input.trim().toUpperCase();
+    if (!/^[A-Z0-9_]{1,20}$/.test(u)) {
+        throw new PerpError("INVALID_PARAMS", `Invalid underlying "${input}"`, {
+            remediation: `List underlyings: perp -e ${VENUE} options underlyings`,
+        });
+    }
+    return u;
+}
+/**
+ * CLI option name → Derive wire name: upper-cased, and a decimal point in the strike written as
+ * the venue's underscore (`PUMP-20261023-0.0045-C` → `PUMP-20261023-0_0045-C`).
+ */
+export function deriveInstrumentName(input) {
+    const parts = input.trim().toUpperCase().split("-");
+    if (parts.length === 4)
+        parts[2] = parts[2].replace(/\./g, "_");
+    return parts.join("-");
+}
+// ── parsing ──
+export function parseDeriveInstrument(raw) {
+    const o = obj(raw, "instrument");
+    const name = str(o, "instrument_name", "instrument");
+    const what = `instrument ${name}`;
+    if (str(o, "instrument_type", what) !== "option")
+        throw deriveShapeError(`${what} is not an option`);
+    const d = obj(o.option_details, `${what}.option_details`);
+    const t = str(d, "option_type", `${what}.option_details`);
+    if (t !== "C" && t !== "P")
+        throw deriveShapeError(`${what}.option_details.option_type "${t}" is not C / P`);
+    const expiryMs = int(d, "expiry", `${what}.option_details`) * 1000;
+    const isActive = o.is_active;
+    if (typeof isActive !== "boolean")
+        throw deriveShapeError(`${what}.is_active is not a boolean`);
+    return {
+        name,
+        underlying: str(o, "base_currency", what),
+        quoteCurrency: str(o, "quote_currency", what),
+        kind: t === "C" ? "call" : "put",
+        strike: dec(d, "strike", `${what}.option_details`),
+        expiryMs,
+        expiry: utcDate(expiryMs),
+        isActive,
+        activationMs: int(o, "scheduled_activation", what) * 1000,
+    };
+}
+/** A ticker_slim snapshot (get_ticker / get_tickers value) of `inst` → OptionQuote. */
+export function parseDeriveOptionTicker(raw, inst) {
+    const what = `ticker ${inst.name}`;
+    const t = obj(raw, what);
+    const bidPx = dec(t, "b", what), bidSz = dec(t, "B", what);
+    const askPx = dec(t, "a", what), askSz = dec(t, "A", what);
+    const bid = Number(bidPx) === 0 ? null : { price: bidPx, size: bidSz };
+    const ask = Number(askPx) === 0 ? null : { price: askPx, size: askSz };
+    const s = obj(t.stats, `${what}.stats`);
+    const trades = int(s, "n", `${what}.stats`);
+    const pr = t.option_pricing;
+    let p = null;
+    if (pr !== null && pr !== undefined)
+        p = obj(pr, `${what}.option_pricing`);
+    const pw = `${what}.option_pricing`;
+    return {
+        schema: OPTIONS_SCHEMA,
+        venue: VENUE,
+        instrument: inst.name,
+        underlying: inst.underlying,
+        quoteCurrency: inst.quoteCurrency,
+        kind: inst.kind,
+        strike: inst.strike,
+        expiry: inst.expiry,
+        expiryMs: inst.expiryMs,
+        bid,
+        ask,
+        mark: dec(t, "M", what),
+        index: dec(t, "I", what),
+        forward: p === null ? null : dec(p, "f", pw),
+        discountFactor: p === null ? null : dec(p, "df", pw),
+        iv: {
+            mark: p === null ? null : nonZero(dec(p, "i", pw)),
+            bid: p === null || bid === null ? null : nonZero(dec(p, "bi", pw)),
+            ask: p === null || ask === null ? null : nonZero(dec(p, "ai", pw)),
+        },
+        greeks: p === null ? null : {
+            delta: dec(p, "d", pw), gamma: dec(p, "g", pw), theta: dec(p, "t", pw), vega: dec(p, "v", pw), rho: dec(p, "r", pw),
+        },
+        openInterest: dec(s, "oi", `${what}.stats`),
+        stats24h: {
+            contracts: dec(s, "c", `${what}.stats`),
+            notional: dec(s, "v", `${what}.stats`),
+            premium: dec(s, "pr", `${what}.stats`),
+            trades,
+            high: trades === 0 ? null : dec(s, "h", `${what}.stats`),
+            low: trades === 0 ? null : dec(s, "l", `${what}.stats`),
+        },
+        timestampMs: int(t, "t", what),
+    };
+}
+/** Distinct active expiries of `instruments`, soonest first. */
+export function expiriesOf(instruments) {
+    const by = new Map();
+    for (const i of instruments) {
+        if (!i.isActive)
+            continue;
+        const e = by.get(i.expiryMs) ?? { strikes: new Set(), n: 0 };
+        e.strikes.add(i.strike);
+        e.n++;
+        by.set(i.expiryMs, e);
+    }
+    return [...by.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .map(([ms, e]) => ({ expiry: utcDate(ms), expiryMs: ms, strikes: e.strikes.size, instruments: e.n }));
+}
+/** The `n` strikes closest to `price` (ties → lower strike), returned ascending. */
+export function strikesAround(strikes, price, n) {
+    const p = Number(price);
+    const nearest = [...strikes].sort((a, b) => (Math.abs(Number(a) - p) - Math.abs(Number(b) - p)) || (Number(a) - Number(b)));
+    return nearest.slice(0, n).sort((a, b) => Number(a) - Number(b));
+}
+/**
+ * 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 function buildChain(underlying, expiry, selection, instruments, tickersRaw, strikesAroundAtm) {
+    const tickers = obj(tickersRaw, "get_tickers result.tickers");
+    const rowsByStrike = new Map();
+    const missingTickers = [];
+    let latest = null;
+    for (const inst of instruments) {
+        const row = rowsByStrike.get(inst.strike) ?? { strike: inst.strike, call: null, put: null };
+        rowsByStrike.set(inst.strike, row);
+        if (!(inst.name in tickers)) {
+            missingTickers.push(inst.name);
+            continue;
+        }
+        const q = parseDeriveOptionTicker(tickers[inst.name], inst);
+        row[inst.kind] = q;
+        if (latest === null || q.timestampMs > latest.timestampMs)
+            latest = q;
+    }
+    const strikes = [...rowsByStrike.keys()];
+    let atm = null;
+    if (latest !== null) {
+        const reference = latest.forward !== null ? "forward" : "index";
+        const price = latest.forward !== null ? latest.forward : latest.index;
+        atm = { strike: strikesAround(strikes, price, 1)[0], reference, price };
+    }
+    let keep = strikes;
+    if (strikesAroundAtm !== null) {
+        if (atm === null) {
+            throw new PerpError("EXCHANGE_ERROR", `Derive returned no ticker for ${underlying} ${expiry.expiry}; the ATM strike for --strikes is unknown`, {
+                exchange: VENUE, remediation: `Run without --strikes to see the listed strikes`,
+            });
+        }
+        keep = strikesAround(strikes, atm.price, strikesAroundAtm);
+    }
+    const rows = keep
+        .sort((a, b) => Number(a) - Number(b))
+        .map(k => rowsByStrike.get(k));
+    return {
+        schema: OPTIONS_SCHEMA,
+        venue: VENUE,
+        underlying,
+        expiry: expiry.expiry,
+        expiryMs: expiry.expiryMs,
+        expirySelection: selection,
+        index: latest === null ? null : latest.index,
+        forward: latest === null ? null : latest.forward,
+        atm,
+        strikesListed: strikes.length,
+        rows,
+        missingTickers: missingTickers.sort(),
+    };
+}
+// ── venue ──
+function noOptions(underlying) {
+    return new PerpError("SYMBOL_NOT_FOUND", `Derive has no ${underlying} options`, {
+        exchange: VENUE, remediation: `List underlyings: perp -e ${VENUE} options underlyings`,
+    });
+}
+export class DeriveOptionsVenue {
+    client;
+    id = VENUE;
+    displayName = "Derive";
+    constructor(client) {
+        this.client = client;
+    }
+    static forNetwork(network) {
+        return new DeriveOptionsVenue(new DeriveClient(network));
+    }
+    async listUnderlyings() {
+        const raw = await this.client.call("get_all_currencies", {});
+        if (!Array.isArray(raw))
+            throw deriveShapeError("get_all_currencies result is not a list");
+        const underlyings = raw
+            .map((c, i) => obj(c, `currency #${i}`))
+            .filter(c => c.option !== null && c.option !== undefined)
+            .map(c => {
+            const what = `currency ${String(c.currency)}`;
+            return { underlying: str(c, "currency", what), spotPrice: c.spot_price === null ? null : dec(c, "spot_price", what) };
+        })
+            .sort((a, b) => a.underlying.localeCompare(b.underlying));
+        return { schema: OPTIONS_SCHEMA, venue: VENUE, underlyings };
+    }
+    /** Every non-expired option instrument of `underlying` (all pages). 12001 → SYMBOL_NOT_FOUND. */
+    async instruments(underlying) {
+        const out = [];
+        for (let page = 1, pages = 1; page <= pages; page++) {
+            let res;
+            try {
+                res = await this.client.call("get_all_instruments", {
+                    instrument_type: "option", currency: underlying, expired: false, page_size: PAGE_SIZE, page,
+                });
+            }
+            catch (e) {
+                if (deriveRpcCode(e) === DERIVE_INSTRUMENT_NOT_FOUND)
+                    throw noOptions(underlying);
+                throw e;
+            }
+            const r = obj(res, "get_all_instruments result");
+            if (!Array.isArray(r.instruments))
+                throw deriveShapeError("get_all_instruments result.instruments is not a list");
+            pages = int(obj(r.pagination, "get_all_instruments result.pagination"), "num_pages", "pagination");
+            for (const i of r.instruments)
+                out.push(parseDeriveInstrument(i));
+        }
+        return out;
+    }
+    async listExpiries(underlyingInput) {
+        const underlying = normalizeUnderlying(underlyingInput);
+        const expiries = expiriesOf(await this.instruments(underlying));
+        if (expiries.length === 0)
+            throw noOptions(underlying);
+        return { schema: OPTIONS_SCHEMA, venue: VENUE, underlying, expiries };
+    }
+    async getChain(q) {
+        const underlying = normalizeUnderlying(q.underlying);
+        const wanted = q.expiry === null ? null : normalizeExpiry(q.expiry);
+        if (q.strikesAroundAtm !== null && (!Number.isInteger(q.strikesAroundAtm) || q.strikesAroundAtm < 1)) {
+            throw new PerpError("INVALID_PARAMS", `--strikes must be a positive integer (got ${q.strikesAroundAtm})`, {
+                remediation: "Pass a positive integer, e.g. --strikes 10",
+            });
+        }
+        const all = await this.instruments(underlying);
+        const expiries = expiriesOf(all);
+        if (expiries.length === 0)
+            throw noOptions(underlying);
+        const expiry = wanted === null ? expiries[0] : expiries.find(e => e.expiry === wanted);
+        if (expiry === undefined) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `Derive has no active ${underlying} option expiry ${wanted}`, {
+                exchange: VENUE,
+                remediation: `Active expiries: ${expiries.map(e => e.expiry).join(", ")} (perp -e ${VENUE} options expiries ${underlying})`,
+            });
+        }
+        const listed = all.filter(i => i.isActive && i.expiryMs === expiry.expiryMs);
+        const res = obj(await this.client.call("get_tickers", {
+            instrument_type: "option", currency: underlying, expiry_date: expiry.expiry.replace(/-/g, ""),
+        }), "get_tickers result");
+        return buildChain(underlying, expiry, wanted === null ? "nearest" : "requested", listed, res.tickers, q.strikesAroundAtm);
+    }
+    async getQuote(instrumentInput) {
+        const name = deriveInstrumentName(instrumentInput);
+        // Both reads are needed (instrument facts + live ticker); issued together, judged instrument first.
+        const [instR, tickR] = await Promise.allSettled([
+            this.client.call("get_instrument", { instrument_name: name }),
+            this.client.call("get_ticker", { instrument_name: name }),
+        ]);
+        if (instR.status === "rejected") {
+            if (deriveRpcCode(instR.reason) === DERIVE_INSTRUMENT_NOT_FOUND) {
+                throw new PerpError("SYMBOL_NOT_FOUND", `Derive has no instrument ${name}`, {
+                    exchange: VENUE, remediation: `Find option names: perp -e ${VENUE} options chain <UNDERLYING>`,
+                });
+            }
+            throw instR.reason;
+        }
+        const o = obj(instR.value, "get_instrument result");
+        if (o.instrument_type !== "option") {
+            throw new PerpError("INVALID_PARAMS", `${name} is a Derive ${String(o.instrument_type)}, not an option`, {
+                exchange: VENUE, remediation: `Find option names: perp -e ${VENUE} options chain <UNDERLYING>`,
+            });
+        }
+        const inst = parseDeriveInstrument(o);
+        if (!inst.isActive && inst.expiryMs <= Date.now()) {
+            // Expired (live: ETH-20261019-2400-C, is_active false after expiry, option_details.settlement_price set).
+            const sp = o.option_details?.settlement_price;
+            const settled = typeof sp === "string" && sp !== "" ? `, settled at ${sp}` : " (settlement price not published yet)";
+            throw new PerpError("SYMBOL_NOT_FOUND", `Derive option ${name} expired at ${new Date(inst.expiryMs).toISOString()}${settled}`, {
+                exchange: VENUE, expired: true, settlementPrice: typeof sp === "string" && sp !== "" ? sp : null,
+                remediation: `Active expiries: perp -e ${VENUE} options expiries ${inst.underlying}`,
+            });
+        }
+        if (!inst.isActive) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `Derive option ${name} is listed but not active (activation ${new Date(inst.activationMs).toISOString()})`, {
+                exchange: VENUE, remediation: `Active expiries: perp -e ${VENUE} options expiries ${inst.underlying}`,
+            });
+        }
+        if (tickR.status === "rejected") {
+            // An active instrument with no ticker (-32602 "Ticker not found for instrument", live): an
+            // activation / expiry race on Derive's side — transient, never the user's INVALID_PARAMS.
+            if (deriveRpcCode(tickR.reason) === DERIVE_INVALID_PARAMS) {
+                throw new PerpError("EXCHANGE_ERROR", `Derive has no live ticker for active option ${name} (${tickR.reason instanceof Error ? tickR.reason.message : String(tickR.reason)})`, {
+                    exchange: VENUE, rpcCode: DERIVE_INVALID_PARAMS,
+                    remediation: `The option may be activating or expiring right now; retry in a moment, or list live instruments: perp -e ${VENUE} options chain ${inst.underlying} --expiry ${inst.expiry}`,
+                });
+            }
+            throw tickR.reason;
+        }
+        return parseDeriveOptionTicker(tickR.value, inst);
+    }
+}