perp-cli 0.15.0 → 0.16.0

package/dist/exchanges/interface.d.ts

@@ -14,7 +14,9 @@ export interface ExchangeMarketInfo {
     /**
      * 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).
+     * (never "0" as a stand-in). One side where known (Lighter / Lighter RH: one side — inferred,
+     * not documented by the venue). The perp-ws `openInterest` is a different field with its own `unit` (Lighter:
+     * USD) — never compare the two without converting.
      */
     openInterest: string | null;
     /** null = the venue does not publish it (Aster: the public exchangeInfo carries no leverage) */
@@ -36,7 +38,31 @@ export interface ExchangeMarketInfo {
         lowerBound: number;
         maxLeverage: number;
     }> | null;
+    /**
+     * Listed but not tradable right now (VenueMarket.tradable: off-hours, reduce-only, halted, paused)
+     * → false. Delisted / disabled / inactive markets are not listed at all (each venue's eligibility
+     * rule). Absent = the venue publishes no tradability flag (its adapter lists live markets only).
+     */
+    tradable?: boolean;
+    /**
+     * Why a listed market is not tradable (with `tradable: false`), e.g. "nonUsdQuote", "offHours",
+     * "reduceOnly", "halted"; or the venue's own status. Absent / null = no reason published.
+     */
+    status?: string | null;
+    /**
+     * What `fundingRate` is, in the WS `rateKind` vocabulary: "accruing" (the current period so far),
+     * "predicted" (the rate expected at the next payment), "lastSettled" (the last payment). null =
+     * not verified for this venue's REST field. Absent on rows built before 0.15.1 conventions.
+     */
+    fundingRateKind?: FundingRateKind | null;
+    /**
+     * The venue's predicted rate for the running / next period, same unit as `fundingRate`
+     * (Pacifica next_funding_rate; Lighter market_stats current_funding_rate) — the perp-ws
+     * `predictedRate`. Absent = the venue publishes none on this path.
+     */
+    predictedFundingRate?: string | null;
 }
+export type FundingRateKind = "accruing" | "predicted" | "lastSettled";
 /**
  * Effective max leverage for an order of `notional` USD.
  *
@@ -103,12 +129,35 @@ export interface TapeSkipped {
     reason: string;
 }
 export declare function withTapeSkipped<T>(rows: T[], skipped: TapeSkipped | null): T[];
+/**
+ * Rows sorted by time (a copy), keeping every non-index property the adapter attached to the
+ * array (TAPE_SKIPPED and any other symbol / metadata key, with its descriptor) — a plain
+ * `[...rows].sort()` drops them.
+ */
+export declare function sortByTime<T extends {
+    time: number;
+}>(rows: readonly T[], order: "asc" | "desc"): T[];
 export declare function tapeSkippedOf(rows: readonly unknown[]): TapeSkipped | null;
 export interface ExchangeFundingPayment {
     time: number;
     symbol: string;
     payment: string;
 }
+/**
+ * One row of `market funding` (getFundingHistory). `rate` is a fraction per `intervalHours`
+ * (the hours one printed rate covers; null = unknown for that market), positive = longs pay.
+ * `rateKind` "lastSettled" = a rate the venue applied at `time`; null = the venue does not say.
+ */
+export interface FundingHistoryRow {
+    time: number;
+    /** null = the venue published no rate for that print (e.g. the market was closed). Never "0" as a stand-in. */
+    rate: string | null;
+    price: string | null;
+    intervalHours: number | null;
+    rateKind: "lastSettled" | null;
+    /** true = the underlying market was closed for this print (no funding accrued); absent = not reported. */
+    marketClosed?: boolean;
+}
 export interface ExchangeKline {
     time: number;
     open: string;
@@ -122,6 +171,13 @@ export interface ExchangeKline {
     /** null = venue does not publish a trade count for the candle */
     trades: number | null;
 }
+/**
+ * Guard for a candle row that states its own interval (HL / TxFlow / Pacifica `i`, RISEx
+ * `interval`): a row of another interval than requested is never returned as the requested one
+ * (RISEx answers unsupported intervals with 1m bars). `rowInterval` undefined = the row carries
+ * no interval field (nothing to check).
+ */
+export declare function assertCandleInterval(venue: string, requested: string, rowInterval: unknown, remediation?: string): void;
 /** 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). */
@@ -185,17 +241,17 @@ export interface ExchangeAdapter {
     /** True if perp and spot share the same balance (e.g., Hyperliquid). False if separate accounts (e.g., Lighter). */
     readonly isUnifiedAccount?: boolean;
     init?(): Promise<void>;
-    getMarkets(): Promise<ExchangeMarketInfo[]>;
-    getOrderbook(symbol: string): Promise<{
+    /** `opts.funding: false` = marks / precision only (Lighter skips its funding snapshot read). */
+    getMarkets(opts?: {
+        funding?: boolean;
+    }): Promise<ExchangeMarketInfo[]>;
+    /** `depth` (levels per side) sizes the request on venues that take it; callers cut the answer to it. */
+    getOrderbook(symbol: string, depth?: number): Promise<{
         bids: [string, string][];
         asks: [string, string][];
     }>;
     getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
-    getFundingHistory(symbol: string, limit?: number): Promise<{
-        time: number;
-        rate: string;
-        price: string | null;
-    }[]>;
+    getFundingHistory(symbol: string, limit?: number): Promise<FundingHistoryRow[]>;
     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>;

package/dist/exchanges/interface.js

@@ -1,3 +1,4 @@
+import { PerpError } from "../errors.js";
 /**
  * Effective max leverage for an order of `notional` USD.
  *
@@ -31,7 +32,37 @@ export function withTapeSkipped(rows, skipped) {
         Object.defineProperty(rows, TAPE_SKIPPED, { value: skipped, enumerable: false });
     return rows;
 }
+/**
+ * Rows sorted by time (a copy), keeping every non-index property the adapter attached to the
+ * array (TAPE_SKIPPED and any other symbol / metadata key, with its descriptor) — a plain
+ * `[...rows].sort()` drops them.
+ */
+export function sortByTime(rows, order) {
+    const out = [...rows].sort((a, b) => (order === "asc" ? a.time - b.time : b.time - a.time));
+    for (const key of Reflect.ownKeys(rows)) {
+        if (key === "length" || (typeof key === "string" && /^\d+$/.test(key)))
+            continue;
+        const d = Object.getOwnPropertyDescriptor(rows, key);
+        if (d !== undefined)
+            Object.defineProperty(out, key, d);
+    }
+    return out;
+}
 export function tapeSkippedOf(rows) {
     const v = rows[TAPE_SKIPPED];
     return v === undefined ? null : v;
 }
+/**
+ * Guard for a candle row that states its own interval (HL / TxFlow / Pacifica `i`, RISEx
+ * `interval`): a row of another interval than requested is never returned as the requested one
+ * (RISEx answers unsupported intervals with 1m bars). `rowInterval` undefined = the row carries
+ * no interval field (nothing to check).
+ */
+export function assertCandleInterval(venue, requested, rowInterval, remediation) {
+    if (rowInterval === undefined || rowInterval === requested)
+        return;
+    throw new PerpError("EXCHANGE_ERROR", `${venue} candles: requested ${requested} candles, got a row labelled ${JSON.stringify(rowInterval)}`, {
+        exchange: venue,
+        remediation: remediation ?? `Use an interval ${venue} serves (see perp -e ${venue} market kline --help)`,
+    });
+}

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

@@ -6,29 +6,29 @@
  *       amounts, status, mark/index price, IMF, OI, volume). It carries every
  *       field /orderBooks has, so /orderBooks is not fetched (one fewer call
  *       under the 60 req/min standard limit).
- *   GET /api/v1/funding-rates     → MULTI-EXCHANGE aggregate (binance/bybit/
- *       hyperliquid/lighter). Only rows with exchange === "lighter" are the
- *       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).
+ *   WS market_stats/all (first frame) → per market `funding_rate` (LAST SETTLED, percent per
+ *       1 h; = the newest GET /fundings print) and `current_funding_rate` (predicted). REST
+ *       /funding-rates is the predicted rate × 8 and is not read here (fetchLighterFundingStats).
  *
- * FUNDING: basis 8h per quoted rate, hourly settlement (Lighter
- * and Lighter RH identical).
+ * FUNDING: market / funding rows carry the settled rate per 1 h (hourly settlement; Lighter and
+ * Lighter RH identical).
  *
  * ASSET CLASS: the API has no asset-class field (the undocumented
  * `strategy_index` groups markets on Lighter main but is 0 for every RH market),
  * so classification is an explicit per-venue table built from live listings on
  * 2026-09-30:
- *   - lighter-rh: every listed perp is in RH_CLASS. An unlisted symbol is
- *     excluded with a warning until it is classified (RH lists mostly equities,
- *     so no class can be assumed).
+ *   - lighter-rh: every listed perp is in LIGHTER_RH_CLASS (src/ws/unclassified.ts). An unlisted symbol is
+ *     "unclassified" (listed, canonical null) until it is classified (RH lists
+ *     mostly equities, so no class can be assumed).
  *   - lighter: crypto-centric venue. LIGHTER_NON_CRYPTO lists every non-crypto
  *     perp; any other symbol is crypto by this venue's definition.
- *     LIGHTER_AMBIGUOUS tickers are excluded with a warning so they cannot
- *     produce a false cross-venue match.
+ *     UNCLASSIFIED_TICKERS.lighter (src/ws/unclassified.ts) are "unclassified" (listed, canonical null) so
+ *     they cannot produce a false cross-venue match.
  *
  * OPEN INTEREST: `open_interest` in base units (same value legacy getMarkets reports).
  */
 import { PerpError } from "../errors.js";
+import type { Network } from "./venue-types.js";
 import type { VenuePublicData } from "./venue.js";
 import type { LighterVenueId } from "./venues/lighter-family.js";
 /**
@@ -40,4 +40,59 @@ import type { LighterVenueId } from "./venues/lighter-family.js";
  * The API's own answers are JSON, so a JSON 405 / 403 is not a challenge.
  */
 export declare function lighterWafChallenge(venue: string, status: number, body: string): PerpError | null;
+/** `limit` of GET /api/v1/orderBookOrders: the documented maximum (apidocs.lighter.xyz/reference/orderbookorders, 1..250). */
+export declare const LIGHTER_BOOK_ORDERS_LIMIT = 250;
+/**
+ * One side of GET /api/v1/orderBookOrders (individual resting ORDERS, best price first) → price
+ * levels: `remaining_base_amount` summed per price, in the venue's order — the shape of the WS
+ * `order_book/{id}` channel (levels). A side of exactly `limit` orders may have more orders at its
+ * last price beyond the page, so that (possibly partial) level is dropped. A row without a price /
+ * remaining amount is a payload error (never skipped, never "0").
+ */
+export declare function lighterBookLevels(venue: string, rows: unknown, what: string, limit?: number): [string, string][];
+/**
+ * A GET /orderBookOrders answer → price levels per side, cut to `depth`. A side whose page is full
+ * (LIGHTER_BOOK_ORDERS_LIMIT orders, the endpoint max) but aggregates to fewer than `depth` levels
+ * cannot be paged: INVALID_PARAMS naming the 250-order cap, never a silently shallower book.
+ */
+export declare function lighterBook(venue: string, res: {
+    asks?: unknown;
+    bids?: unknown;
+}, what: string, depth?: number): {
+    bids: [string, string][];
+    asks: [string, string][];
+};
+/**
+ * Every account of an L1 (EVM) address — `GET /account?by=l1_address&value=` (public). One
+ * address can own several accounts (sub-accounts). An address without a Lighter account answers
+ * HTTP 400 `{"code":21100,"message":"account not found"}` (live 2026-10-19) → null, not an error.
+ */
+export declare function fetchLighterAccountsByL1(venue: LighterVenueId, net: Network, address: string): Promise<Array<Record<string, unknown>> | null>;
+/** Perp price decimals by symbol (upper case) — `GET /orderBooks` `supported_price_decimals`, as the adapter's market map. */
+export declare function fetchLighterPriceDecimals(venue: LighterVenueId, net: Network): Promise<Map<string, number>>;
+/** One market's funding from the WS `market_stats/all` snapshot, fractions per 1 h. */
+export interface LighterFundingStat {
+    /** Last settled hourly rate (market_stats funding_rate; = the newest GET /fundings print). */
+    rate: string | null;
+    /** Predicted rate of the running hour (market_stats current_funding_rate). */
+    predictedRate: string | null;
+}
+/** Drop the shared market_stats snapshots and remembered failures (tests; a network switch). */
+export declare function clearLighterFundingStatsCache(): void;
+/**
+ * Why the settled rate of `venue` / `net` is unavailable right now (the remembered failure of the
+ * last snapshot read), null when it was read or not tried. Callers put it in `meta.warnings`
+ * (CLI --json, MCP) next to the rows whose fundingRate is null.
+ */
+export declare function lighterFundingStatsWarning(venue: LighterVenueId, net: Network): string | null;
+/**
+ * Settled + predicted hourly funding of every market, keyed by market_id: the SNAPSHOT frame
+ * (`subscribed/market_stats`, channel `market_stats:all` — later `update/…` frames carry only the
+ * markets that changed) of the WS `market_stats/all` channel, the source of the perp-ws `rate` /
+ * `predictedRate`. REST has no bulk settled source: /funding-rates is the PREDICTED rate × 8 (live
+ * 2026-10-19: ETH 0.0009 % /h predicted → 0.000072; settled 0.0012 % /h), and /fundings is one
+ * market per request. One snapshot per venue / network is shared STATS_TTL_MS; a failure is
+ * remembered STATS_FAILURE_TTL_MS (lighterFundingStatsWarning).
+ */
+export declare function fetchLighterFundingStats(venue: LighterVenueId, net: Network): Promise<Map<number, LighterFundingStat>>;
 export declare function lighterPublicData(venue: LighterVenueId): VenuePublicData;