perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/hyperliquid.js

@@ -9,9 +9,9 @@ import { rateLimitedError } from "./rate-limiter.js";
 import { fetchAndCache, withCache, TTL_ACCOUNT } from "../cache.js";
 import { approvalFromMax, builderGateOf, hlFeeTenthsBps, NO_BUILDER, requireFeeBps } from "./builder-fee.js";
 /**
- * Map a TIF input to HL's native value (design §13.3). Accepts the common names
+ * Map a TIF input to HL's native value. Accepts the common names
  * GTC/IOC/ALO and the native spellings case-insensitively. FOK is not offered by
- * HL (no FOK emulation, §13.3) → CAPABILITY_UNSUPPORTED; anything else likewise.
+ * HL (no FOK emulation) → CAPABILITY_UNSUPPORTED; anything else likewise.
  */
 export function hlTif(raw) {
     const t = raw.trim().toUpperCase();
@@ -31,7 +31,7 @@ export function hlSizeStep(szDecimals) {
     return szDecimals <= 0 ? "1" : `0.${"0".repeat(szDecimals - 1)}1`;
 }
 /**
- * Slippage-bounded IOC protection price (design §13.2, §13.10 #5).
+ * Slippage-bounded IOC protection price.
  *
  * `reference` × (1 ± bps/10000), then aligned TOWARD CROSSING (buy → up, sell →
  * down) on HL's price grid: at most 5 significant figures and at most
@@ -56,8 +56,8 @@ export function hlProtectionPrice(reference, side, bps, szDecimals, maxDecimals)
     return { protectionPrice, appliedBps };
 }
 /**
- * A USER-SUPPLIED limit / trigger / modify price checked against HL's price grid (design §10.10:
- * an off-grid limit price is refused, never rounded — rounding to nearest can move a buy price UP).
+ * A USER-SUPPLIED limit / trigger / modify price checked against HL's price grid:
+ * an off-grid limit price is refused, never rounded — rounding to nearest can move a buy price UP.
  * HL docs (trading/tick-and-lot-size): "Prices can have up to 5 significant figures, but no more
  * than MAX_DECIMALS - szDecimals decimal places where MAX_DECIMALS is 6 for perps and 8 for spot.
  * Integer prices are always allowed, regardless of the number of significant figures."
@@ -140,7 +140,7 @@ export async function assertHlAppliedBps(appliedBps, what) {
 }
 /**
  * Definite IOC outcome of a raw HL `order` response (shared contract with the
- * perp-order lane, design §13.10 #4). Reads `response.data.statuses[0]`:
+ * perp-order lane). Reads `response.data.statuses[0]`:
  * - `{ filled: { totalSz } }` with a plain decimal totalSz → that size, final;
  * - `{ error }` that is HL's IOC no-match cancel ("could not immediately match")
  *   → the venue explicitly cancelled the IOC with nothing filled → "0", final;
@@ -653,7 +653,7 @@ export class HyperliquidAdapter {
             // A dex-prefixed symbol must name THIS adapter's dex — never rewritten onto another dex.
             const [prefix, base] = sym.split(":");
             if (prefix.toLowerCase() !== this._dex.toLowerCase()) {
-                throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid symbol ${symbol} is on dex "${prefix.toLowerCase()}", not ${this._dex ? `this adapter's dex "${this._dex}"` : "the native perp dex"}`, {
+                throw new PerpError("SYMBOL_NOT_FOUND", `Hyperliquid symbol ${prefix.toLowerCase()}:${base} is on dex "${prefix.toLowerCase()}", not ${this._dex ? `this adapter's dex "${this._dex}"` : "the native perp dex"}`, {
                     exchange: "hyperliquid", remediation: `Select the dex: perp -e hyperliquid --dex ${prefix.toLowerCase()} ...`,
                 });
             }
@@ -726,7 +726,14 @@ export class HyperliquidAdapter {
             }
             return idx;
         }
-        throw new PerpError("SYMBOL_NOT_FOUND", `Unknown asset: ${symbol}`, { exchange: "hyperliquid" });
+        throw this._unknownSymbol(symbol, `Unknown asset: ${symbol}`);
+    }
+    /** SYMBOL_NOT_FOUND for a coin the venue does not list (on this adapter's dex), with the listing command. */
+    _unknownSymbol(symbol, message) {
+        return new PerpError("SYMBOL_NOT_FOUND", message ?? `Hyperliquid has no market ${symbol.toUpperCase()}${this._dex ? ` on dex "${this._dex}"` : ""}`, {
+            exchange: "hyperliquid",
+            remediation: `List markets: perp -e hyperliquid${this._dex ? ` --dex ${this._dex}` : ""} market list`,
+        });
     }
     async getMarkets() {
         if (this._marketsCache && Date.now() - this._marketsCacheTime < HyperliquidAdapter.CACHE_TTL)
@@ -785,32 +792,57 @@ export class HyperliquidAdapter {
                 this._assetMapReverse.set(i, sym);
             });
         }
-        const result = universe.map((asset, i) => {
+        // Delisted assets (meta `isDelisted: true`; live 2026-10-14: 56 of 234 native perps, all with
+        // funding / dayNtlVlm / openInterest "0.0") are not markets: excluded from the listing and
+        // everything built on it. They stay in the asset map (_loadAssetMap), so an explicit symbol
+        // still resolves for orders / position reads.
+        const delisted = new Set();
+        const result = universe.flatMap((asset, i) => {
+            if (asset.isDelisted === true) {
+                delisted.add(String(asset.name));
+                return [];
+            }
             const ctx = (ctxs[i] ?? {});
             const sym = String(asset.name);
             const szDec = this._szDecimalsMap.get(sym) ?? (asset.szDecimals !== undefined ? Number(asset.szDecimals) : null);
-            return {
-                symbol: sym,
-                markPrice: String(ctx.markPx ?? mids[sym] ?? "0"),
-                indexPrice: ctx.oraclePx != null ? String(ctx.oraclePx) : null,
-                fundingRate: ctx.funding != null ? String(ctx.funding) : null,
-                volume24h: ctx.dayNtlVlm != null ? String(ctx.dayNtlVlm) : null,
-                openInterest: ctx.openInterest != null ? String(ctx.openInterest) : null,
-                maxLeverage: Number(asset.maxLeverage ?? 50),
-                sizeDecimals: szDec,
-                // HL has no separate lot-size field; the step is implied by szDecimals.
-                stepSize: null,
-                // HL funding is uniform (venue definition), not per-market.
-                fundingHours: null,
-                marginTiers: tierMap.get(Number(asset.marginTableId)) ?? null,
-            };
+            return [{
+                    symbol: sym,
+                    markPrice: String(ctx.markPx ?? mids[sym] ?? "0"),
+                    indexPrice: ctx.oraclePx != null ? String(ctx.oraclePx) : null,
+                    fundingRate: ctx.funding != null ? String(ctx.funding) : null,
+                    volume24h: ctx.dayNtlVlm != null ? String(ctx.dayNtlVlm) : null,
+                    openInterest: ctx.openInterest != null ? String(ctx.openInterest) : null,
+                    maxLeverage: Number(asset.maxLeverage ?? 50),
+                    sizeDecimals: szDec,
+                    // HL has no separate lot-size field; the step is implied by szDecimals.
+                    stepSize: null,
+                    // HL funding is uniform (venue definition), not per-market.
+                    fundingHours: null,
+                    marginTiers: tierMap.get(Number(asset.marginTableId)) ?? null,
+                }];
         });
+        this._delisted = delisted;
         this._marketsCache = result;
         this._marketsCacheTime = Date.now();
         return result;
     }
+    /** Display names of the delisted assets seen by the last getMarkets() (meta isDelisted). */
+    _delisted = new Set();
+    /**
+     * Why `symbol` is not in getMarkets(): it is delisted (message), or null when it is not a
+     * delisted asset. Read after getMarkets(). `market info` uses it to say "delisted" rather than
+     * "not found" — the asset map still resolves it for orders / positions / history.
+     */
+    delistedMessage(symbol) {
+        const resolved = this.resolveSymbol(symbol.toUpperCase());
+        if (!this._delisted.has(resolved))
+            return null;
+        return `${resolved.replace(/-PERP$/, "")} is delisted on Hyperliquid (positions / history still readable)`;
+    }
     async getOrderbook(symbol) {
         let levels;
+        // l2Book answers `null` for a coin the venue does not list (live 2026-10-14, coin "NOPE"):
+        // SYMBOL_NOT_FOUND, never an empty book (which reads as "no liquidity").
         if (this._dex) {
             // HIP-3 dex: full dex-prefixed coin (e.g. "US500" → "km:US500") + dex param
             const book = await this._infoPost({
@@ -818,11 +850,15 @@ export class HyperliquidAdapter {
                 coin: this._venueCoin(symbol),
                 dex: this._dex,
             });
-            levels = book?.levels ?? [[], []];
+            if (book === null)
+                throw this._unknownSymbol(symbol);
+            levels = book.levels ?? [[], []];
         }
         else {
             const book = await this._infoPost({ type: "l2Book", coin: this._venueCoin(symbol) });
-            levels = book?.levels ?? [[], []];
+            if (book === null)
+                throw this._unknownSymbol(symbol);
+            levels = book.levels ?? [[], []];
         }
         return {
             bids: (levels[0] ?? []).map((l) => [
@@ -1234,11 +1270,11 @@ export class HyperliquidAdapter {
         }
     }
     /**
-     * Market order = slippage-bounded IOC limit (design §13.2, §13.10 #1/#5) for
+     * Market order = slippage-bounded IOC limit for
      * native perps and HIP-3 dexes alike. Replaces the SDK's marketOpen/marketClose
      * (hidden built-in slippage) and the former HIP-3 5% constant.
      *
-     * Reference price (the single declared source, §13.10 #5): the l2Book mid
+     * Reference price (the single declared source): the l2Book mid
      * (best bid + best ask) / 2 of this coin — see referencePrice(). No runtime
      * substitute (mark, allMids, last trade): a missing side → PRICE_STALE before
      * anything is sent. Protection = reference ± opts.slippage.bps, aligned toward
@@ -1531,7 +1567,7 @@ export class HyperliquidAdapter {
         return hlAlignPriceToGrid(price, this.getSzDecimals(symbol), 6, side === "buy" ? "down" : "up");
     }
     async limitOrder(symbol, side, price, size, opts) {
-        // TIF aliases (§13.3): GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
+        // TIF aliases: GTC/IOC/ALO or native spellings; FOK → CAPABILITY_UNSUPPORTED.
         let action;
         const cloid = opts?.clientOrderId === undefined ? null : HyperliquidAdapter.requireCloid(opts.clientOrderId);
         try { // pre-send (see marketOrder)
@@ -1680,7 +1716,7 @@ export class HyperliquidAdapter {
     }
     // ── Interface methods ──
     /**
-     * Amend (design §13.4, §13.10 #10) via HL native batchModify. `size` = the NEW
+     * Amend via HL native batchModify. `size` = the NEW
      * open (unfilled) size — native-modify semantics, not the original total. The
      * order's own tif (Gtc/Alo) and reduceOnly are read from frontendOpenOrders
      * and preserved; nothing is hardcoded.
@@ -1770,8 +1806,13 @@ export class HyperliquidAdapter {
         });
     }
     async getRecentTrades(symbol, limit = 20) {
+        // recentTrades answers HTTP 500 "null" for an unlisted coin (live 2026-10-14), which would read
+        // as a retryable venue error: resolve the coin against the asset map first (SYMBOL_NOT_FOUND).
+        await this.getAssetIndex(symbol);
         const trades = await this._infoPost({ type: "recentTrades", coin: this._venueCoin(symbol) });
-        return (trades ?? [])
+        if (trades === null)
+            throw this._unknownSymbol(symbol);
+        return trades
             .slice(0, limit)
             .map((t) => ({
             time: Number(t.time ?? 0),
@@ -1779,10 +1820,11 @@ export class HyperliquidAdapter {
             side: String(t.side) === "B" ? "buy" : "sell",
             price: String(t.px ?? "0"),
             size: String(t.sz ?? ""),
-            fee: "0",
+            fee: null, // the public tape carries no fee
         }));
     }
     async getKlines(symbol, interval, startTime, endTime) {
+        await this.getAssetIndex(symbol); // unlisted coin: SYMBOL_NOT_FOUND (candleSnapshot answers HTTP 500 "null")
         const candles = await this._infoPost({
             type: "candleSnapshot",
             req: { coin: this._venueCoin(symbol), interval, startTime, endTime },
@@ -1793,7 +1835,10 @@ export class HyperliquidAdapter {
             high: String(c.h ?? "0"),
             low: String(c.l ?? "0"),
             close: String(c.c ?? "0"),
-            volume: String(c.v ?? ""),
+            // absent / non-numeric → null (never "")
+            volume: typeof c.v === "string" && c.v.trim() !== "" && Number.isFinite(Number(c.v)) ? c.v
+                : typeof c.v === "number" && Number.isFinite(c.v) ? String(c.v) : null,
+            quoteVolume: null, // candleSnapshot carries base volume only
             trades: Number(c.n ?? 0),
         }));
     }
@@ -1943,6 +1988,7 @@ export class HyperliquidAdapter {
         return !/[:@#/]/.test(coin);
     }
     async getFundingHistory(symbol, limit = 10) {
+        await this.getAssetIndex(symbol); // unlisted coin: SYMBOL_NOT_FOUND (fundingHistory answers HTTP 500)
         const now = Date.now();
         const history = await this._infoPost({ type: "fundingHistory", coin: this._venueCoin(symbol), startTime: now - 24 * 60 * 60 * 1000 });
         return (history ?? []).slice(-limit).map((h) => ({
@@ -1958,7 +2004,7 @@ export class HyperliquidAdapter {
      * Place a trigger order (stop loss / take profit).
      * Python SDK: order() with trigger type {"trigger": {triggerPx, isMarket, tpsl: "tp"|"sl"}}
      *
-     * Pricing (design §13.10 #3):
+     * Pricing:
      * - isMarket (default): HL native market trigger; `p` = trigger ± 10 % (the venue's documented
      *   market TP/SL slippage tolerance, HL_MARKET_TPSL_SLIPPAGE_BPS), aligned toward crossing.
      * - limit trigger with an explicit `limitPrice`: that price, rounded to HL's grid.
@@ -2385,27 +2431,6 @@ export class HyperliquidAdapter {
         }
         return res;
     }
-    /**
-     * Get funding history for a symbol.
-     */
-    async getFundingHistoryRaw(symbol, startTime, endTime) {
-        const baseUrl = this._testnet
-            ? "https://api.hyperliquid-testnet.xyz"
-            : "https://api.hyperliquid.xyz";
-        const body = {
-            type: "fundingHistory",
-            coin: symbol.toUpperCase(),
-            startTime,
-        };
-        if (endTime)
-            body.endTime = endTime;
-        const res = await fetch(`${baseUrl}/info`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(body),
-        });
-        return res.json();
-    }
     /**
      * Get user trade fills.
      */

package/dist/exchanges/index.d.ts

@@ -1,4 +1,4 @@
-export type { ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline, ExchangeAdapter, } from "./interface.js";
+export type { ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline, ExchangeAdapter, } from "./interface.js";
 export type { SpotMarketInfo, SpotBalance, SpotAdapter } from "./spot-interface.js";
 export { SPOT_PERP_TOKEN_MAP, PERP_TO_SPOT_MAP, MAX_PRICE_DEVIATION_PCT } from "./spot-interface.js";
 export * from "./capabilities.js";

package/dist/exchanges/index.js

@@ -9,7 +9,7 @@ export { LighterAdapter } from "./lighter.js";
 export { AsterAdapter } from "./aster.js";
 export { HyperliquidSpotAdapter } from "./hyperliquid-spot.js";
 export { LighterSpotAdapter } from "./lighter-spot.js";
-// Venue abstraction (docs/DESIGN-venue-abstraction.md §10)
+// Venue abstraction
 export { getVenue, listVenues, listVenuesWithRole, resolveVenueId, tryResolveVenueId, parseVenueRef, networkConfig, requireCapabilities, fundingBasisOf, settlementIntervalOf, isLegacyVenue, isVenueId, READ_ONLY_CREDENTIALS, } from "./venue.js";
 export { ensureVenuesRegistered, ALL_VENUES } from "./venues/index.js";
 export { isTradingV2, validateOrderRequest, validateLegacyTif } from "./trading-v2.js";

package/dist/exchanges/interface.d.ts

@@ -9,11 +9,16 @@ export interface ExchangeMarketInfo {
     /** null = venue does not publish an index/oracle price for this market */
     indexPrice: string | null;
     fundingRate: string | null;
-    /** null = venue does not publish 24h volume */
+    /** 24h volume in USD notional; null = venue does not publish 24h volume */
     volume24h: string | null;
-    /** null = venue does not publish open interest (never "0" as a stand-in) */
+    /**
+     * Open interest in BASE-asset units (contracts of the underlying, e.g. BTC) — every venue
+     * publishes it that way, so it is never a USD figure. null = venue does not publish it
+     * (never "0" as a stand-in).
+     */
     openInterest: string | null;
-    maxLeverage: number;
+    /** null = the venue does not publish it (Aster: the public exchangeInfo carries no leverage) */
+    maxLeverage: number | null;
     /** quantity precision (e.g. 0 = integers only, 2 = 0.01); null = unknown */
     sizeDecimals: number | null;
     /** lot step size (e.g. "1", "0.1", "0.001"); null = unknown */
@@ -38,7 +43,7 @@ export interface ExchangeMarketInfo {
  * A venue that publishes no tiers (`marginTiers === null`) has one flat cap,
  * `maxLeverage`, at every size — that is the venue's definition, not a fallback.
  */
-export declare function maxLeverageForNotional(market: ExchangeMarketInfo, notional: number): number;
+export declare function maxLeverageForNotional(market: ExchangeMarketInfo, notional: number): number | null;
 export interface ExchangePosition {
     symbol: string;
     side: "long" | "short";
@@ -78,6 +83,27 @@ export interface ExchangeTrade {
     size: string;
     fee: string;
 }
+/**
+ * A row of the PUBLIC trade tape (getRecentTrades). The tape carries no fee for the viewer —
+ * a fee exists only on the account's own fills (getTradeHistory) — so `fee` is always null
+ * here, never "0" as a stand-in.
+ */
+export interface ExchangePublicTrade extends Omit<ExchangeTrade, "fee"> {
+    fee: null;
+}
+/**
+ * Rows of a public tape the adapter left out because they carry a value the venue documents but
+ * does not declare exhaustive (e.g. a new Pacifica event_type) — never guessed into a direction.
+ * Attached to the returned array under this symbol key (not serialized); `market trades` reports
+ * it as `meta.skippedRows`. Absent = nothing skipped.
+ */
+export declare const TAPE_SKIPPED: unique symbol;
+export interface TapeSkipped {
+    count: number;
+    reason: string;
+}
+export declare function withTapeSkipped<T>(rows: T[], skipped: TapeSkipped | null): T[];
+export declare function tapeSkippedOf(rows: readonly unknown[]): TapeSkipped | null;
 export interface ExchangeFundingPayment {
     time: number;
     symbol: string;
@@ -89,10 +115,69 @@ export interface ExchangeKline {
     high: string;
     low: string;
     close: string;
-    volume: string;
+    /** Base-asset volume of the candle; null = venue does not publish it (never "0" as a stand-in) */
+    volume: string | null;
+    /** Quote (USD) notional volume of the candle; null = venue does not publish it */
+    quoteVolume: string | null;
     /** null = venue does not publish a trade count for the candle */
     trades: number | null;
 }
+/** One indicative quote of an RFQ venue's maker at a fixed size. */
+export interface RfqQuoteTier {
+    /** Venue tier id ("base" = the market's minimum order size). */
+    tier: string;
+    /** USD notional of the tier; null when the venue does not publish it (minimum order size). */
+    notionalUsd: string | null;
+    bid: string;
+    ask: string;
+}
+/** An RFQ venue's indicative maker quotes — NOT order-book levels (`market book` on such a venue). */
+export interface RfqQuotes {
+    kind: "rfqQuotes";
+    venue: string;
+    symbol: string;
+    ticker: string;
+    markPrice: string;
+    /** null = no quotes published right now (e.g. a closed market). */
+    updatedAt: string | null;
+    baseSpreadBps: string | null;
+    quotes: RfqQuoteTier[];
+    note: string;
+}
+/** Separate long / short rates of one daily swap funding payment (fractions). */
+export interface SwapFundingRates {
+    annualizedLong: string;
+    annualizedShort: string;
+    intervalLong: string;
+    intervalShort: string;
+}
+/** Current funding terms of one market, for a venue that publishes no funding history (`market funding`). */
+export interface CurrentFundingTerms {
+    kind: "currentFunding";
+    venue: string;
+    symbol: string;
+    ticker: string;
+    contractType: "perpetual" | "swap";
+    /** "predicted": the rate charged at nextFundingTime, recomputed during the window. */
+    rateKind: "predicted" | null;
+    /** Fraction per interval as published (perpetual); null for a swap or when unknown. */
+    intervalRate: string | null;
+    intervalHours: number | null;
+    /** intervalRate / intervalHours. */
+    hourlyRate: number | null;
+    /** hourlyRate × 24 × 365 × 100 (same normalization as arb scan). */
+    annualizedPct: number | null;
+    /** The venue's own annualized rate (fraction), for cross-checking. */
+    venueAnnualizedRate: string | null;
+    /** Unix ms; null when not published. */
+    nextFundingTime: number | null;
+    /** Swap only: long / short rates of the last applied and the upcoming payment. */
+    swap: {
+        last: SwapFundingRates | null;
+        next: SwapFundingRates | null;
+    } | null;
+    note: string;
+}
 export interface ExchangeAdapter {
     readonly name: string;
     readonly chain?: string;
@@ -105,13 +190,17 @@ export interface ExchangeAdapter {
         bids: [string, string][];
         asks: [string, string][];
     }>;
-    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
     getFundingHistory(symbol: string, limit?: number): Promise<{
         time: number;
         rate: string;
         price: string | null;
     }[]>;
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
+    /** RFQ venue (no order book): the maker's indicative quotes. Absent = the venue has an order book. */
+    getRfqQuotes?(symbol: string): Promise<RfqQuotes>;
+    /** Venue without a funding-history API: the current funding terms. Absent = use getFundingHistory. */
+    getFundingTerms?(symbol: string): Promise<CurrentFundingTerms>;
     getBalance(): Promise<ExchangeBalance>;
     getPositions(): Promise<ExchangePosition[]>;
     getOpenOrders(): Promise<ExchangeOrder[]>;
@@ -119,7 +208,7 @@ export interface ExchangeAdapter {
     getTradeHistory(limit?: number): Promise<ExchangeTrade[]>;
     getFundingPayments(limit?: number): Promise<ExchangeFundingPayment[]>;
     /**
-     * Market order = IOC within the resolved slippage bound (design §13.2). `opts` is
+     * Market order = IOC within the resolved slippage bound. `opts` is
      * required so every caller states reduceOnly and passes resolveSlippage() output.
      */
     marketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
@@ -141,7 +230,7 @@ export interface ExchangeAdapter {
      * `slippage` (resolveSlippage() output) bounds the execution price of a market
      * trigger on venues that send it as a protection-priced limit once triggered
      * (Lighter, Arcus: required there for a market trigger — adapters never read
-     * settings, design §13.10 #1); venue-native market triggers ignore it.
+     * settings); venue-native market triggers ignore it.
      * `kind` ("tp" | "sl") states the protective intent explicitly: venues with distinct
      * take-profit / stop-loss trigger types (Aster, Lighter) send that type as given — no
      * price-based classification — and a trigger already crossed is left for the venue to

package/dist/exchanges/interface.js

@@ -10,11 +10,28 @@ export function maxLeverageForNotional(market, notional) {
     }
     const tiers = market.marginTiers;
     if (tiers === null || tiers.length === 0)
-        return market.maxLeverage;
-    let effective = market.maxLeverage;
+        return market.maxLeverage; // null = not published
+    // No headline but published tiers: the first (lowest-notional) tier is the cap below every threshold.
+    let effective = market.maxLeverage ?? tiers[0].maxLeverage;
     for (const t of tiers) {
         if (notional >= t.lowerBound)
             effective = t.maxLeverage;
     }
     return effective;
 }
+/**
+ * Rows of a public tape the adapter left out because they carry a value the venue documents but
+ * does not declare exhaustive (e.g. a new Pacifica event_type) — never guessed into a direction.
+ * Attached to the returned array under this symbol key (not serialized); `market trades` reports
+ * it as `meta.skippedRows`. Absent = nothing skipped.
+ */
+export const TAPE_SKIPPED = Symbol.for("perp-cli.tapeSkipped");
+export function withTapeSkipped(rows, skipped) {
+    if (skipped !== null && skipped.count > 0)
+        Object.defineProperty(rows, TAPE_SKIPPED, { value: skipped, enumerable: false });
+    return rows;
+}
+export function tapeSkippedOf(rows) {
+    const v = rows[TAPE_SKIPPED];
+    return v === undefined ? null : v;
+}

package/dist/exchanges/ioc-outcome.d.ts

@@ -1,5 +1,5 @@
 /**
- * Venue-final IOC / market order outcome (design `docs/DESIGN-venue-abstraction.md` §13.10 #4).
+ * Venue-final IOC / market order outcome.
  *
  * An adapter whose market / IOC responses report the order's FINAL filled size (nothing
  * of the order can still execute) implements `iocOutcomeOf(raw)` on the RAW result its

package/dist/exchanges/ioc-outcome.js

@@ -1,5 +1,5 @@
 /**
- * Venue-final IOC / market order outcome (design `docs/DESIGN-venue-abstraction.md` §13.10 #4).
+ * Venue-final IOC / market order outcome.
  *
  * An adapter whose market / IOC responses report the order's FINAL filled size (nothing
  * of the order can still execute) implements `iocOutcomeOf(raw)` on the RAW result its

package/dist/exchanges/legacy-trading-v2.d.ts

@@ -1,6 +1,6 @@
 /**
  * TradingV2 for the four pre-existing venues (pacifica, hyperliquid, lighter /
- * lighter-rh, aster) — design §13.7, §13.10 #8.
+ * lighter-rh, aster).
  *
  * Composition, not modification: the legacy ExchangeAdapter methods keep returning
  * their raw venue responses (in-process contract for smart-order, perp-order,
@@ -17,7 +17,7 @@ import { type TradingV2 } from "./trading-v2.js";
 import { type Network, type OrderResult } from "./venue-types.js";
 export declare function tradingV2Of(adapter: ExchangeAdapter, network: Network): TradingV2;
 export declare function toTradingV2(adapter: ExchangeAdapter, network: Network): TradingV2;
-/** One reduce-only protective trigger (TP or SL) of a separateOrders venue (design §13.5). */
+/** One reduce-only protective trigger (TP or SL) of a separateOrders venue. */
 export interface TpSlLeg {
     symbol: string;
     /** Side that closes the protected position (sell closes a long). */

package/dist/exchanges/legacy-trading-v2.js

@@ -1,6 +1,6 @@
 /**
  * TradingV2 for the four pre-existing venues (pacifica, hyperliquid, lighter /
- * lighter-rh, aster) — design §13.7, §13.10 #8.
+ * lighter-rh, aster).
  *
  * Composition, not modification: the legacy ExchangeAdapter methods keep returning
  * their raw venue responses (in-process contract for smart-order, perp-order,
@@ -13,6 +13,7 @@
  */
 import { PerpError, orderOutcomeUnknown } from "../errors.js";
 import { isPacificaStopType, pacificaRefused } from "./pacifica.js";
+import { isPacificaRateLimited } from "../pacifica/rate-limit.js";
 import { iocLotTolerance, isIocOutcomeCapable } from "./ioc-outcome.js";
 import { isQueryOrderCapable } from "./capabilities.js";
 import { floorSize, lotStepOf } from "./precision.js";
@@ -621,7 +622,11 @@ class LegacyTradingV2 {
             if (this.family !== "pacifica" || !pacificaRefused(e))
                 throw e;
             raw = { error: e instanceof Error ? e.message : String(e) };
-            refusal = await this.adapter.cancelRefusalOutcome(ref.value, e);
+            // RATE_LIMITED with sent:false (local throttle or HTTP 429): this cancel was not executed —
+            // failed (nothing cancelled), no history read needed. Unknown-after-send never lands here.
+            refusal = isPacificaRateLimited(e)
+                ? { kind: "failed", error: `cancel of ${ref.value} not executed (rate limited, nothing sent / refused): ${e instanceof Error ? e.message : String(e)}` }
+                : await this.adapter.cancelRefusalOutcome(ref.value, e);
         }
         const out = (v, reason = "") => {
             if (v === "cancelled")

package/dist/exchanges/lighter-public.d.ts

@@ -1,5 +1,5 @@
 /**
- * Lighter-family public market data (`lighter`, `lighter-rh`) — design §10.6.
+ * Lighter-family public market data (`lighter`, `lighter-rh`).
  *
  * Sources (REST base from venues/lighter-family.ts, per venue + network):
  *   GET /api/v1/orderBookDetails  → perps in `order_book_details` (decimals, min
@@ -11,7 +11,7 @@
  *       venue's own; the RH host labels its own rows "lighter" too (live
  *       2026-09-30: 57 "lighter" rows = RH's 57 perps, matched by market_id).
  *
- * FUNDING: basis 8h per quoted rate, hourly settlement (design §10.1, Lighter
+ * FUNDING: basis 8h per quoted rate, hourly settlement (Lighter
  * and Lighter RH identical).
  *
  * ASSET CLASS: the API has no asset-class field (the undocumented

package/dist/exchanges/lighter-public.js

@@ -1,5 +1,5 @@
 /**
- * Lighter-family public market data (`lighter`, `lighter-rh`) — design §10.6.
+ * Lighter-family public market data (`lighter`, `lighter-rh`).
  *
  * Sources (REST base from venues/lighter-family.ts, per venue + network):
  *   GET /api/v1/orderBookDetails  → perps in `order_book_details` (decimals, min
@@ -11,7 +11,7 @@
  *       venue's own; the RH host labels its own rows "lighter" too (live
  *       2026-09-30: 57 "lighter" rows = RH's 57 perps, matched by market_id).
  *
- * FUNDING: basis 8h per quoted rate, hourly settlement (design §10.1, Lighter
+ * FUNDING: basis 8h per quoted rate, hourly settlement (Lighter
  * and Lighter RH identical).
  *
  * ASSET CLASS: the API has no asset-class field (the undocumented

package/dist/exchanges/lighter-signer.d.ts

@@ -22,7 +22,7 @@ export declare const LIGHTER_ALL_MARKETS = 255;
 /**
  * One Go runtime of the official signer. The Go `main` registers its functions on
  * globalThis and then blocks; they are captured synchronously right after `go.run()`
- * and the globals restored, so several runtimes (one per venue+network, design §10.5)
+ * and the globals restored, so several runtimes (one per venue+network)
  * never see each other's functions.
  */
 export declare class LighterWasmSigner {

package/dist/exchanges/lighter-signer.js

@@ -55,7 +55,7 @@ function nonceArg(v) {
 /**
  * One Go runtime of the official signer. The Go `main` registers its functions on
  * globalThis and then blocks; they are captured synchronously right after `go.run()`
- * and the globals restored, so several runtimes (one per venue+network, design §10.5)
+ * and the globals restored, so several runtimes (one per venue+network)
  * never see each other's functions.
  */
 export class LighterWasmSigner {

package/dist/exchanges/lighter-spot.d.ts

@@ -74,7 +74,7 @@ export declare class LighterSpotAdapter implements SpotAdapter {
         tif?: string;
     }): Promise<unknown>;
     /**
-     * TIF mapping, as perps (§13.3): GTC/GTT → GTT, IOC → IOC, ALO / POST_ONLY → post-only (2).
+     * TIF mapping, as perps: GTC/GTT → GTT, IOC → IOC, ALO / POST_ONLY → post-only (2).
      * FOK and anything else → CAPABILITY_UNSUPPORTED (never silently GTT).
      */
     private _limitTif;
@@ -107,7 +107,7 @@ export declare class LighterSpotAdapter implements SpotAdapter {
     transferUsdcToSpot(amount: number): Promise<unknown>;
     /** Transfer USDC from spot account back to perp account */
     transferUsdcToPerp(amount: number): Promise<unknown>;
-    /** SpotTransferCapable (§12.4 #4): only the venue collateral (USDC on Lighter, USDG on Lighter RH). */
+    /** SpotTransferCapable: only the venue collateral (USDC on Lighter, USDG on Lighter RH). */
     transferToSpot(amount: string, asset: string): Promise<unknown>;
     transferToPerp(amount: string, asset: string): Promise<unknown>;
     private _transferAmount;
@@ -139,8 +139,7 @@ export declare class LighterSpotAdapter implements SpotAdapter {
     private _nextClientOrderIndex;
     private _getNextNonce;
     /**
-     * POST /sendTx. `kind` "place" (order placement): failures are typed (design
-     * §12.3): before the request → ORDER_REJECTED; transport error, HTTP 5xx or an
+     * POST /sendTx. `kind` "place" (order placement): failures are typed: before the request → ORDER_REJECTED; transport error, HTTP 5xx or an
      * unreadable body after it → ORDER_PENDING (the tx may have been accepted — never
      * resubmit); an explicit non-200 code → ORDER_REJECTED. "order" (cancels) / "action"
      * (transfers): an explicit non-200 code → ORDER_REJECTED / ACTION_REJECTED