perp-cli 0.14.2 → 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].
@@ -159,6 +170,10 @@ export function requireAsterClientOrderId(id) {
  * that the read refuses (EXCHANGE_ERROR) rather than returning a partial history.
  */
 export const ASTER_INCOME_MAX_PAGES = 60;
+/** GET /fapi/v3/klines maximum rows per request (docs: limit max 1500). */
+const ASTER_KLINE_PAGE = 1500;
+/** Page cap for one range (150 000 bars). */
+const ASTER_KLINE_MAX_PAGES = 100;
 export class AsterAdapter {
     name = "aster";
     chain = "bnb";
@@ -279,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.
@@ -375,41 +390,54 @@ export class AsterAdapter {
             // math depends on.
             this._loadFundingInfo(),
         ]);
+        if (!Array.isArray(info?.symbols)) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster exchangeInfo has no symbol list (${JSON.stringify(info).slice(0, 120)})`, { exchange: "aster" });
+        }
+        if (!Array.isArray(tickers)) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster 24h ticker is not a list (${JSON.stringify(tickers).slice(0, 120)})`, { exchange: "aster" });
+        }
         const tickerMap = new Map();
-        for (const t of tickers ?? []) {
+        for (const t of tickers) {
             tickerMap.set(String(t.symbol), t);
         }
-        let premiumMap = new Map();
-        try {
-            const premiums = await this._publicGet("/fapi/v3/premiumIndex");
-            premiumMap = new Map(premiums.map(p => [String(p.symbol), p]));
-        }
-        catch { /* non-critical */ }
-        this._ingestPriceFilters(info?.symbols ?? []);
-        const tradingSymbols = (info?.symbols ?? [])
-            .filter((s) => String(s.contractType) === "PERPETUAL" && String(s.status) === "TRADING");
-        const result = tradingSymbols.map((s) => {
+        // The mark price comes from premiumIndex only: a failed read throws (never a "0" / last-trade
+        // stand-in), and a symbol missing from it is left out of the list below.
+        const premiums = await this._publicGet("/fapi/v3/premiumIndex");
+        if (!Array.isArray(premiums)) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster premiumIndex is not a list (${JSON.stringify(premiums).slice(0, 120)})`, { exchange: "aster" });
+        }
+        const premiumMap = new Map(premiums.map(p => [String(p.symbol), p]));
+        this._ingestPriceFilters(info.symbols);
+        // USDT-quoted perps only: the CLI symbol mapping (ETH ↔ ETHUSDT) cannot address the USD1 / U
+        // quoted markets (live 2026-10-13: 22 USD1 + 2 U), so listing them would offer untradeable rows.
+        const tradingSymbols = info.symbols
+            .filter((s) => String(s.contractType) === "PERPETUAL" && String(s.status) === "TRADING" && String(s.quoteAsset) === "USDT");
+        const result = tradingSymbols.flatMap((s) => {
             const sym = String(s.symbol);
             const ticker = tickerMap.get(sym);
             const premium = premiumMap.get(sym);
-            const maxLev = Number(s.maxLeverage ?? 50);
+            const mark = Number(premium?.markPrice);
+            if (premium === undefined || !(mark > 0))
+                return []; // no published mark price → not listed at 0
+            // Public exchangeInfo carries no leverage (the bracket endpoint is signed) → unknown.
+            const maxLev = null;
             const lotFilter = s.filters
                 ?.find(f => f.filterType === "LOT_SIZE");
             const fundingHours = this._fundingHoursCache.get(this._fromApi(sym));
-            return {
-                symbol: this._fromApi(sym),
-                markPrice: String(premium?.markPrice ?? ticker?.lastPrice ?? "0"),
-                indexPrice: premium?.indexPrice != null ? String(premium.indexPrice) : null,
-                fundingRate: premium?.lastFundingRate != null ? String(premium.lastFundingRate) : null,
-                volume24h: ticker?.quoteVolume != null ? String(ticker.quoteVolume) : null,
-                // /fapi/v3/exchangeInfo and ticker/24hr carry no open interest.
-                openInterest: null,
-                maxLeverage: maxLev,
-                sizeDecimals: s.quantityPrecision != null ? Number(s.quantityPrecision) : null,
-                stepSize: lotFilter?.stepSize != null ? String(lotFilter.stepSize) : null,
-                fundingHours: fundingHours ?? null,
-                marginTiers: null,
-            };
+            return [{
+                    symbol: this._fromApi(sym),
+                    markPrice: String(premium.markPrice),
+                    indexPrice: premium?.indexPrice != null ? String(premium.indexPrice) : null,
+                    fundingRate: premium?.lastFundingRate != null ? String(premium.lastFundingRate) : null,
+                    volume24h: ticker?.quoteVolume != null ? String(ticker.quoteVolume) : null,
+                    // /fapi/v3/exchangeInfo and ticker/24hr carry no open interest.
+                    openInterest: null,
+                    maxLeverage: maxLev,
+                    sizeDecimals: s.quantityPrecision != null ? Number(s.quantityPrecision) : null,
+                    stepSize: lotFilter?.stepSize != null ? String(lotFilter.stepSize) : null,
+                    fundingHours: fundingHours ?? null,
+                    marginTiers: null,
+                }];
         });
         this._marketsCache = result;
         this._marketsCacheTime = Date.now();
@@ -449,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) {
@@ -458,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.
      */
@@ -538,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) {
@@ -546,29 +574,66 @@ export class AsterAdapter {
             symbol: this._toApi(symbol),
             limit: String(limit),
         });
-        return (data ?? []).map((d) => ({
-            time: Number(d.fundingTime ?? 0),
-            rate: venueRateField(d.fundingRate, "fundingRate fundingRate", "aster"),
-            price: d.markPrice ? String(d.markPrice) : null,
-        }));
+        if (!Array.isArray(data)) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster fundingRate history is not a list (${JSON.stringify(data).slice(0, 120)})`, { exchange: "aster" });
+        }
+        // `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" });
+            }
+            return {
+                time,
+                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
+     * (1501 → -1130), so the range is read in pages that start after the last bar returned — a long
+     * range is never cut to the first page. More than ASTER_KLINE_MAX_PAGES pages → INVALID_PARAMS.
+     */
     async getKlines(symbol, interval, startTime, endTime) {
-        const data = await this._publicGet("/fapi/v3/klines", {
-            symbol: this._toApi(symbol),
-            interval,
-            startTime: String(startTime),
-            endTime: String(endTime),
-            limit: "500",
-        });
-        return (data ?? []).map((k) => ({
-            time: Number(k[0]),
-            open: String(k[1]),
-            high: String(k[2]),
-            low: String(k[3]),
-            close: String(k[4]),
-            volume: String(k[5]),
-            trades: Number(k[8] ?? 0),
-        }));
+        if (!(startTime <= endTime)) {
+            throw new PerpError("INVALID_PARAMS", `Aster klines: start ${startTime} is after end ${endTime}`, {
+                remediation: "Pass a --start that is before --end",
+            });
+        }
+        const out = [];
+        let from = startTime;
+        for (let page = 0; from <= endTime; page++) {
+            if (page >= ASTER_KLINE_MAX_PAGES) {
+                throw new PerpError("INVALID_PARAMS", `Aster: ${interval} candles over this range need more than ${ASTER_KLINE_MAX_PAGES} requests`, {
+                    remediation: "Narrow --start / --end or use a longer interval",
+                });
+            }
+            const data = await this._publicGet("/fapi/v3/klines", {
+                symbol: this._toApi(symbol), interval,
+                startTime: String(from), endTime: String(endTime), limit: String(ASTER_KLINE_PAGE),
+            });
+            if (!Array.isArray(data)) {
+                throw new PerpError("EXCHANGE_ERROR", `Aster klines is not a list (${JSON.stringify(data).slice(0, 120)})`, { exchange: "aster" });
+            }
+            for (const k of data) {
+                const time = Number(k[0]);
+                const trades = Number(k[8]);
+                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]), quoteVolume: String(k[7]), trades });
+            }
+            if (data.length < ASTER_KLINE_PAGE)
+                break;
+            const next = Number(data[data.length - 1][0]) + 1;
+            if (next <= from) {
+                throw new PerpError("EXCHANGE_ERROR", `Aster klines page did not advance past ${from}`, { exchange: "aster" });
+            }
+            from = next;
+        }
+        return out;
     }
     // ── Account ──
     async getBalance() {
@@ -923,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.
@@ -1020,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);
@@ -1052,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).
@@ -1705,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;
+}