perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/lighter-spot.js

@@ -7,10 +7,11 @@
  * Composes with LighterAdapter for signing and API access.
  */
 import { TX_EVENT_FILL_SOURCE } from "./spot-interface.js";
-import { lighterWafChallenge } from "./lighter-public.js";
+import { LIGHTER_BOOK_ORDERS_LIMIT, lighterBook, lighterWafChallenge } from "./lighter-public.js";
 import { LIGHTER_TIF, lighterEventFilledBase, lighterEventOrderId, lighterGeneratedClientOrderIndex, lighterOrderIdOf, lighterOrderSignIndex, lighterPostSendTx, lighterRowOutcomeOf, lighterSelectAccount, lighterTakerFilledBase, lighterTxState, } from "./lighter.js";
 import { alignProtectionPrice, floorSize, formatComputedPrice, requireOnTick, slippagePrice, subDecimal, toUnitsExact } from "./precision.js";
 import { unsupported } from "./trading-v2.js";
+import { rateLimitedError } from "./rate-limiter.js";
 import { PerpError, orderNotSent, parsePositiveDecimal } from "../errors.js";
 /** The row match (market + send time) _placeOrder attached to its result; absent → null (no extra match). */
 function lighterRowMatchOf(result) {
@@ -28,6 +29,82 @@ function spotStatusOf(o) {
         return "partial";
     return o.status;
 }
+/**
+ * Spot balances of one Lighter-family account object (GET /account `assets`) — the one mapper
+ * behind the keyed spot adapter and the keyless `account balance --address`. `quote` is the
+ * venue collateral ("USDC" on Lighter, "USDG" on Lighter RH).
+ */
+export function lighterSpotBalanceRows(acct, venue, quote) {
+    const balances = [];
+    if (acct.assets !== undefined && !Array.isArray(acct.assets)) {
+        throw new PerpError("EXCHANGE_ERROR", `${venue} spot balances: account.assets is not an array`, { exchange: venue, raw: acct.assets });
+    }
+    const assets = (acct.assets ?? []);
+    // Docs (docs.lighter.xyz/trading/unified-trading-accounts): "Unified Trading Accounts (UTA)
+    // enables unified margin on Spot and Perpetuals USDC balances." vs Simple: "perpetual and spot
+    // balances are maintained separately." Mode = this same response's account_trading_mode
+    // ("Classic=0 and Unified=1", apidocs reference/account-1); an unknown mode fails the quote row.
+    const quoteShared = () => {
+        const mode = acct.account_trading_mode;
+        if (mode !== 0 && mode !== 1) {
+            throw new PerpError("EXCHANGE_ERROR", `${venue} spot balances: account_trading_mode is ${JSON.stringify(mode ?? null)} (expected 0 classic | 1 unified)`, {
+                exchange: venue,
+                remediation: `Retry; check the account with: perp -e ${venue} account info`,
+            });
+        }
+        return mode === 1;
+    };
+    const plainDecimal = (v, field) => {
+        if (typeof v !== "string" || !/^-?\d+(\.\d+)?$/.test(v)) {
+            throw new PerpError("EXCHANGE_ERROR", `${venue} spot balances: ${field} is ${JSON.stringify(v ?? null)} (expected a decimal string)`, {
+                exchange: venue,
+                remediation: `Retry; check the account with: perp -e ${venue} account info`,
+            });
+        }
+        return v;
+    };
+    for (const asset of assets) {
+        const bal = Number(asset.balance);
+        const locked = Number(asset.locked_balance);
+        if (!Number.isFinite(bal) || !Number.isFinite(locked)) {
+            throw new PerpError("EXCHANGE_ERROR", `${venue} spot balance for ${asset.symbol} is not a number (balance=${asset.balance}, locked=${asset.locked_balance})`, { exchange: venue, raw: asset });
+        }
+        if (asset.symbol === quote && quoteShared()) {
+            // Unified account: the quote is ONE balance for spot and perp, and the venue books it
+            // under the asset row's `margin_balance` with `balance` "0.000000" (GET /account,
+            // mainnet account 723334, 2026-10-05: assets[USDC] balance "0.000000", margin_balance
+            // "15.952247503314"; account available_balance "15.952247"). apidocs reference/account-1
+            // lists the asset fields `balance`, `locked_balance`, `margin_mode` ("enabled" |
+            // "disabled"), `margin_balance` and the account field `available_balance` without
+            // defining them further, so:
+            //   total     = balance + margin_balance  (the quote the account holds, exact sum);
+            //   available = account `available_balance` — the only "free" figure the venue reports
+            //               for the unified margin, i.e. what is not committed as perp margin and
+            //               therefore usable by a spot order. It is the venue's number, not
+            //               total − held (it moves with perp margin use and unrealized PnL);
+            //   held      = locked_balance (quote locked by resting spot orders).
+            // Named by the bare quote symbol: it is not a separate spot balance (`_SPOT`).
+            const total = subDecimal(plainDecimal(asset.balance, `${quote} balance`), subDecimal("0", plainDecimal(asset.margin_balance, `${quote} margin_balance`)));
+            if (Number(total) > 0) {
+                balances.push({ token: quote, total, available: plainDecimal(acct.available_balance, "available_balance"), held: asset.locked_balance, shared: true });
+            }
+            continue;
+        }
+        if (bal > 0) {
+            balances.push({
+                // The quote row carries the bare quote symbol ("USDC" / "USDG") on classic accounts too:
+                // `shared: false` is what says it is a separate spot balance, not a `_SPOT` suffix.
+                token: asset.symbol,
+                total: asset.balance,
+                available: String(bal - locked),
+                held: asset.locked_balance,
+                // Classic quote: a separate spot balance. Base assets are never perp margin here.
+                shared: false,
+            });
+        }
+    }
+    return balances;
+}
 export class LighterSpotAdapter {
     /** Venue id of the wrapped LighterAdapter ("lighter" | "lighter-rh"). */
     name;
@@ -159,26 +236,22 @@ export class LighterSpotAdapter {
             };
         });
     }
-    async getSpotOrderbook(symbol) {
+    async getSpotOrderbook(symbol, depth) {
         await this.init();
         const resolved = this.resolveSymbol(symbol);
         const marketId = this._spotMarketMap.get(resolved);
         if (marketId === undefined) {
-            throw new Error(`Unknown Lighter spot market: ${symbol}`);
-        }
-        try {
-            const res = await this._restGet("/orderBookOrders", {
-                market_id: String(marketId),
-                limit: "50",
+            throw new PerpError("SYMBOL_NOT_FOUND", `Unknown Lighter spot market: ${symbol}`, {
+                exchange: this.name, remediation: `Check the symbol: perp -e ${this.name} market spot-list`,
             });
-            return {
-                bids: (res.bids ?? []).map((l) => [l.price, l.remaining_base_amount ?? l.size ?? "0"]),
-                asks: (res.asks ?? []).map((l) => [l.price, l.remaining_base_amount ?? l.size ?? "0"]),
-            };
-        }
-        catch {
-            return { bids: [], asks: [] };
         }
+        // A failed read throws its typed error (429 / WAF / transport) — never an empty book, which
+        // callers (arb-auto, liquidity) would read as "no liquidity". Orders → price levels as on perps.
+        const res = await this._restGet("/orderBookOrders", {
+            market_id: String(marketId),
+            limit: String(LIGHTER_BOOK_ORDERS_LIMIT),
+        });
+        return lighterBook(this.name, res, resolved, depth);
     }
     /**
      * Spot token balances. Reads the account through the shared 15s `acct:` cache
@@ -218,80 +291,11 @@ export class LighterSpotAdapter {
                 remediation: `Check the ${this.name} account index / address (perp -e ${this.name} account info)`,
             });
         }
-        const balances = [];
-        const quote = this._quote;
-        if (acct.assets !== undefined && !Array.isArray(acct.assets)) {
-            throw new PerpError("EXCHANGE_ERROR", `${this.name} spot balances: account.assets is not an array`, { exchange: this.name, raw: acct.assets });
-        }
-        const assets = (acct.assets ?? []);
-        // Docs (docs.lighter.xyz/trading/unified-trading-accounts): "Unified Trading Accounts (UTA)
-        // enables unified margin on Spot and Perpetuals USDC balances." vs Simple: "perpetual and spot
-        // balances are maintained separately." Mode = this same response's account_trading_mode
-        // ("Classic=0 and Unified=1", apidocs reference/account-1); an unknown mode fails the quote row.
-        const quoteShared = () => {
-            const mode = acct.account_trading_mode;
-            if (mode !== 0 && mode !== 1) {
-                throw new PerpError("EXCHANGE_ERROR", `${this.name} spot balances: account_trading_mode is ${JSON.stringify(mode ?? null)} (expected 0 classic | 1 unified)`, {
-                    exchange: this.name,
-                    remediation: `Retry; check the account with: perp -e ${this.name} account info`,
-                });
-            }
-            return mode === 1;
-        };
-        const plainDecimal = (v, field) => {
-            if (typeof v !== "string" || !/^-?\d+(\.\d+)?$/.test(v)) {
-                throw new PerpError("EXCHANGE_ERROR", `${this.name} spot balances: ${field} is ${JSON.stringify(v ?? null)} (expected a decimal string)`, {
-                    exchange: this.name,
-                    remediation: `Retry; check the account with: perp -e ${this.name} account info`,
-                });
-            }
-            return v;
-        };
-        for (const asset of assets) {
-            const bal = Number(asset.balance);
-            const locked = Number(asset.locked_balance);
-            if (!Number.isFinite(bal) || !Number.isFinite(locked)) {
-                throw new PerpError("EXCHANGE_ERROR", `${this.name} spot balance for ${asset.symbol} is not a number (balance=${asset.balance}, locked=${asset.locked_balance})`, { exchange: this.name, raw: asset });
-            }
-            if (asset.symbol === quote && quoteShared()) {
-                // Unified account: the quote is ONE balance for spot and perp, and the venue books it
-                // under the asset row's `margin_balance` with `balance` "0.000000" (GET /account,
-                // mainnet account 723334, 2026-10-05: assets[USDC] balance "0.000000", margin_balance
-                // "15.952247503314"; account available_balance "15.952247"). apidocs reference/account-1
-                // lists the asset fields `balance`, `locked_balance`, `margin_mode` ("enabled" |
-                // "disabled"), `margin_balance` and the account field `available_balance` without
-                // defining them further, so:
-                //   total     = balance + margin_balance  (the quote the account holds, exact sum);
-                //   available = account `available_balance` — the only "free" figure the venue reports
-                //               for the unified margin, i.e. what is not committed as perp margin and
-                //               therefore usable by a spot order. It is the venue's number, not
-                //               total − held (it moves with perp margin use and unrealized PnL);
-                //   held      = locked_balance (quote locked by resting spot orders).
-                // Named by the bare quote symbol: it is not a separate spot balance (`_SPOT`).
-                const total = subDecimal(plainDecimal(asset.balance, `${quote} balance`), subDecimal("0", plainDecimal(asset.margin_balance, `${quote} margin_balance`)));
-                if (Number(total) > 0) {
-                    balances.push({ token: quote, total, available: plainDecimal(acct.available_balance, "available_balance"), held: asset.locked_balance, shared: true });
-                }
-                continue;
-            }
-            if (bal > 0) {
-                balances.push({
-                    // The quote row carries the bare quote symbol ("USDC" / "USDG") on classic accounts too:
-                    // `shared: false` is what says it is a separate spot balance, not a `_SPOT` suffix.
-                    token: asset.symbol,
-                    total: asset.balance,
-                    available: String(bal - locked),
-                    held: asset.locked_balance,
-                    // Classic quote: a separate spot balance. Base assets are never perp margin here.
-                    shared: false,
-                });
-            }
-        }
-        return balances;
+        return lighterSpotBalanceRows(acct, this.name, this._quote);
     }
     async spotMarketOrder(symbol, side, size, opts) {
         // Everything up to sendTx is pre-send: a failure there is a definite "not placed"
-        // (ORDER_REJECTED); sendTx transport failures are ORDER_PENDING (design §12.3).
+        // (ORDER_REJECTED); sendTx transport failures are ORDER_PENDING.
         let prep;
         try {
             prep = await this._prepareMarketOrder(symbol, side, size, opts.slippage.bps);
@@ -392,30 +396,32 @@ export class LighterSpotAdapter {
         const resolved = this.resolveSymbol(symbol);
         const marketId = this._spotMarketMap.get(resolved);
         if (marketId === undefined) {
-            throw new Error(`Unknown Lighter spot market: ${symbol}`);
+            throw new PerpError("SYMBOL_NOT_FOUND", `Unknown Lighter spot market: ${symbol}`, {
+                exchange: this.name, remediation: `Check the symbol: perp -e ${this.name} market spot-list`,
+            });
         }
         // Validate min order size
         const minSize = this._spotMinSize.get(resolved);
         const sizeNum = parseFloat(size);
         if (minSize && sizeNum < minSize.base) {
-            throw new Error(`Size ${size} below min_base_amount ${minSize.base} for ${resolved}`);
+            throw new PerpError("SIZE_TOO_SMALL", `Size ${size} below min_base_amount ${minSize.base} for ${resolved}`, { exchange: this.name });
         }
-        // Protection price = best opposite quote ± the resolved slippage bound (design §13.2)
+        // Protection price = best opposite quote ± the resolved slippage bound
         const ob = await this.getSpotOrderbook(resolved);
         let refPrice;
         if (side === "buy") {
             if (ob.asks.length === 0)
-                throw new Error(`No asks in ${resolved} spot orderbook`);
+                throw new PerpError("PRICE_STALE", `No asks in ${resolved} spot orderbook — no reference price`, { exchange: this.name });
             refPrice = Number(ob.asks[0][0]);
         }
         else {
             if (ob.bids.length === 0)
-                throw new Error(`No bids in ${resolved} spot orderbook`);
+                throw new PerpError("PRICE_STALE", `No bids in ${resolved} spot orderbook — no reference price`, { exchange: this.name });
             refPrice = Number(ob.bids[0][0]);
         }
         // Validate min quote amount (size × price ≥ min_quote)
         if (minSize && sizeNum * refPrice < minSize.quote) {
-            throw new Error(`Order value $${(sizeNum * refPrice).toFixed(2)} below min_quote_amount $${minSize.quote} for ${resolved}`);
+            throw new PerpError("SIZE_TOO_SMALL", `Order value $${(sizeNum * refPrice).toFixed(2)} below min_quote_amount $${minSize.quote} for ${resolved}`, { exchange: this.name });
         }
         const dec = this._getDecimals(resolved);
         // Tick conversion rounds toward crossing (buy → up, sell → down), never to nearest.
@@ -453,7 +459,7 @@ export class LighterSpotAdapter {
         const sizeStep = dec.size <= 0 ? "1" : `0.${"0".repeat(dec.size - 1)}1`;
         const tick = dec.price <= 0 ? "1" : `0.${"0".repeat(dec.price - 1)}1`;
         // Size floored to the size step (never rounded up); price must already be on tick
-        // (INVALID_TICK, never rounded — design §10.10).
+        // (INVALID_TICK, never rounded).
         const sentSize = floorSize(size, sizeStep);
         const sentPrice = requireOnTick(price, tick);
         // Venue minimums: refused, never bumped up to the minimum (the order would exceed the request).
@@ -505,7 +511,7 @@ export class LighterSpotAdapter {
         };
     }
     /**
-     * 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).
      */
     _limitTif(tif) {
@@ -656,7 +662,7 @@ export class LighterSpotAdapter {
     async transferUsdcToPerp(amount) {
         return this._selfTransfer(String(amount), 1, 0); // route: Spot(1) → Perp(0)
     }
-    /** 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). */
     async transferToSpot(amount, asset) {
         return this._selfTransfer(this._transferAmount(amount, asset), 0, 1);
     }
@@ -864,8 +870,7 @@ export class LighterSpotAdapter {
         return nonce;
     }
     /**
-     * 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
@@ -900,6 +905,9 @@ export class LighterSpotAdapter {
         const res = await fetch(url.toString());
         if (!res.ok) {
             const text = await res.text();
+            // apidocs.lighter.xyz/docs/rate-limits: a breached limit answers "HTTP 429" (as LighterAdapter.restGet).
+            if (res.status === 429)
+                throw rateLimitedError(this._lt.name, res.headers.get("retry-after"), text);
             const waf = lighterWafChallenge(this._lt.name, res.status, text);
             if (waf !== null)
                 throw waf;

package/dist/exchanges/lighter.d.ts

@@ -1,10 +1,11 @@
-import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline, FundingHistoryRow } from "./interface.js";
 import type { ResolvedSlippage } from "./slippage.js";
 import type { EvmSigner } from "../signer/index.js";
 import type { AgentMeta } from "../settings.js";
 import { PerpError } from "../errors.js";
 import type { Network, VenueNetworkConfig } from "./venue.js";
 import { LIGHTER_REFERENCE_PRICE_SOURCE } from "./venues/lighter-family.js";
+import { type LighterFundingStat } from "./lighter-public.js";
 import type { LighterVenueId } from "./venues/lighter-family.js";
 import { LighterWasmSigner } from "./lighter-signer.js";
 /** Lighter trigger orderType enum (matches WASM signer). */
@@ -34,7 +35,12 @@ export declare const LIGHTER_TIF: {
     readonly POST_ONLY: 2;
 };
 /**
- * CLI format rule for a Lighter client order id (§13.10 #9): the venue's
+ * One GET /api/v1/fundings row → a funding history row (fraction per 1 h, signed).
+ * `rate` is percent per hour, unsigned; `direction` "long" = longs pay (positive), "short" = shorts pay.
+ */
+export declare function lighterFundingRow(venue: string, f: unknown): FundingHistoryRow;
+/**
+ * CLI format rule for a Lighter client order id: the venue's
  * `clientOrderIndex` is numeric, so the id must be a plain decimal integer string
  * (digits only, no sign / leading zero / exponent) in 1 ≤ n ≤ 2^48 − 1.
  * Anything else → INVALID_PARAMS before anything is sent.
@@ -249,6 +255,19 @@ export declare function lighterRowCreatedMs(row: Record<string, unknown>): numbe
  * leverage = floor(10000 / bps), which returns the integer leverage that was set. margin_mode:
  * 0 cross, 1 isolated (the values updateLeverage signs). Anything else throws — never a guess.
  */
+/**
+ * Balance of one Lighter-family account object (GET /account) — the one implementation behind
+ * LighterAdapter.getBalance() and the keyless `account balance --address`. Equity includes the
+ * spot collateral asset (USDC on Lighter, USDG on Lighter RH; separate from perp collateral).
+ */
+export declare function lighterBalanceOf(acct: Record<string, unknown>, venue: string, collateralSymbol: string): ExchangeBalance;
+/**
+ * Open positions of one Lighter account (`GET /account` `accounts[].positions[]`): the venue lists
+ * every market the account ever traded or configured, so rows with `position` 0 are dropped. The
+ * ONE mapper of the keyed `getPositions` and the public-address read; `priceDecimalsOf` formats
+ * the computed mark (position_value / size) to the market's price decimals when known.
+ */
+export declare function lighterPositionRows(positions: unknown, venue: string, priceDecimalsOf: (symbol: string) => number | undefined): ExchangePosition[];
 export declare function lighterPositionSettings(p: Record<string, unknown>, venue: string): {
     leverage: number;
     marginMode: "cross" | "isolated";
@@ -270,13 +289,21 @@ export declare function lighterSelectAccount(accounts: Array<Record<string, unkn
  * window is unknown (SYMBOL_NOT_FOUND) until the entry expires.
  */
 export declare const LIGHTER_MARKET_LIST_TTL_MS: number;
+/** GET /api/v1/candles resolutions, live-verified 2026-10-19 on lighter + lighter-rh mainnet and lighter testnet (3m / 2h / 6h / 8h / 1w / 1M / 2m: code 20001 "invalid param"). */
+export declare const LIGHTER_CANDLE_INTERVALS: Readonly<Record<string, number>>;
+/** "Returns at most 500 candles per call" (apidocs.lighter.xyz/reference/candles). */
+export declare const LIGHTER_CANDLES_PER_CALL = 500;
+/** Max `limit` of GET /api/v1/recentTrades. */
+export declare const LIGHTER_RECENT_TRADES_MAX = 100;
+/** Requests one `market kline` may send (the venue allows 60 / minute on standard accounts). */
+export declare const LIGHTER_KLINE_MAX_PAGES = 10;
 export interface LighterAdapterOpts {
     apiKey?: string;
     accountIndex?: number;
     apiKeyIndex?: number;
 }
 export declare class LighterAdapter implements ExchangeAdapter {
-    /** GTC→GTT resting-order lifetime (28 days) for the execution record (§13.10 #14). */
+    /** GTC→GTT resting-order lifetime (28 days) for the execution record. */
     static readonly gttExpiryMs: number;
     /** Venue id ("lighter" | "lighter-rh"). */
     readonly name: LighterVenueId;
@@ -300,6 +327,8 @@ export declare class LighterAdapter implements ExchangeAdapter {
     private _address;
     private _marketMap;
     private _marketDecimals;
+    /** symbol → live (isLighterMarketLive). Inactive markets stay in _marketMap for reads and closes. */
+    private _marketLive;
     private _evmKey;
     private _apiKey;
     private _accountIndexInit;
@@ -434,6 +463,12 @@ export declare class LighterAdapter implements ExchangeAdapter {
      * the 60 / minute budget.
      */
     private _refreshMarketMap;
+    /**
+     * An order that can open or add exposure (not reduce-only) on a market that is not live
+     * (`status` inactive / `is_frozen`) is refused before signing. Reduce-only orders and closes are
+     * still sent, so a position on a market that went inactive can be closed.
+     */
+    private assertOpenable;
     getMarketIndex(symbol: string): number;
     /**
      * Lot step of a perp market from the loaded market list (size decimals of /orderBooks) —
@@ -468,7 +503,7 @@ export declare class LighterAdapter implements ExchangeAdapter {
      */
     private pollTx;
     /**
-     * Definite IOC outcome (§13.10 #4) from the executed tx: poll /tx by hash. A taker order the
+     * Definite IOC outcome from the executed tx: poll /tx by hash. A taker order the
      * venue reports "filled" (event_info `to.st` 3, `is` = sent) filled the whole order. Any other
      * status (the remainder was cancelled — the venue zeroes `rs`, so is − rs is NOT a fill) →
      * the venue's own `filled_base_amount` from accountOrders by client order index. Zero fill →
@@ -501,7 +536,7 @@ export declare class LighterAdapter implements ExchangeAdapter {
      */
     orderRowOutcome(clientOrderIndex: number, orderId: string | null, what: string, settled?: (out: LighterOrderOutcome, row: Record<string, unknown>) => boolean, match?: LighterRowMatch | null): Promise<LighterOrderOutcome | null>;
     /**
-     * Final outcome of a placed resting / post-only order (§13.10 #4 analogue for non-IOC): poll
+     * Final outcome of a placed resting / post-only order (analogue for non-IOC): poll
      * /tx (rejected → ORDER_REJECTED). Our order (`to`, matched by client order index) reported
      * "filled" in event_info → filled = is (the whole order). Any other status — open, or a
      * canceled-* whose remainder the venue zeroed (`rs` 0, so is − rs is NOT a fill) — or an
@@ -524,7 +559,13 @@ export declare class LighterAdapter implements ExchangeAdapter {
      * a size that floors to 0 → SIZE_TOO_SMALL.
      */
     private toTicks;
-    getMarkets(): Promise<ExchangeMarketInfo[]>;
+    /** Settled / predicted hourly funding per market_id (WS market_stats snapshot, shared with the public directory). */
+    protected fundingStats(): Promise<Map<number, LighterFundingStat>>;
+    /** Why the last listing's fundingRate is null (the settled-rate snapshot failed), else null. */
+    fundingWarning(): string | null;
+    getMarkets(opts?: {
+        funding?: boolean;
+    }): Promise<ExchangeMarketInfo[]>;
     private get accountCacheKey();
     /** The in-flight cached account read: parallel callers (getBalance + getPositions) share one request. */
     private _accountInFlight;
@@ -534,9 +575,11 @@ export declare class LighterAdapter implements ExchangeAdapter {
      * Book from GET /orderBookOrders?market_id=<id> on this venue's host (Lighter RH: its own host
      * and market ids, e.g. RH testnet TSLA = 112). Rule #2: an unknown symbol (SYMBOL_NOT_FOUND) or
      * a failed read throws — it is never reported as an empty book. An empty `bids`/`asks` is the
-     * venue's real answer (no liquidity).
+     * venue's real answer (no liquidity). The endpoint lists individual ORDERS (up to 250 per side,
+     * the documented max); they are aggregated into price levels (lighterBookLevels), as the WS
+     * `order_book` channel publishes them.
      */
-    getOrderbook(symbol: string): Promise<{
+    getOrderbook(symbol: string, depth?: number): Promise<{
         bids: [string, string][];
         asks: [string, string][];
     }>;
@@ -558,7 +601,7 @@ export declare class LighterAdapter implements ExchangeAdapter {
     /** Order / trade side from Lighter's `is_ask`; a missing / non-boolean value throws (never defaults to "buy"). */
     private sideOfIsAsk;
     /**
-     * Slippage-bounded IOC (§13.2): protection price = orderbook mid ± opts.slippage.bps,
+     * Slippage-bounded IOC: protection price = orderbook mid ± opts.slippage.bps,
      * tick-aligned toward crossing. The returned raw sendTx result carries `protection`
      * and, when the venue reported the fill, `iocOutcome` (see iocOutcomeOf).
      * `opts.clientOrderIndex` (optional) = caller's numeric client order id (lighterClientOrderIndex rule).
@@ -569,9 +612,9 @@ export declare class LighterAdapter implements ExchangeAdapter {
         clientOrderIndex?: number;
     }): Promise<unknown>;
     /**
-     * TIF mapping (§13.3): GTC/GTT → GTT (28-day expiry, gttExpiryMs), IOC → IOC,
+     * TIF mapping: GTC/GTT → GTT (28-day expiry, gttExpiryMs), IOC → IOC,
      * ALO / POST_ONLY → time-in-force 2 (POST_ONLY per apidocs trading.md and the official
-     * lighter-go signer; 28-day expiry like GTT — testnet confirmation pending, design §11).
+     * lighter-go signer; 28-day expiry like GTT — testnet confirmation pending).
      * FOK and any other value → CAPABILITY_UNSUPPORTED (never silently GTT).
      * `opts.clientOrderIndex` as in marketOrder.
      * IOC: the same definite outcome as marketOrder (awaitIocOutcome — zero fill →
@@ -640,7 +683,7 @@ export declare class LighterAdapter implements ExchangeAdapter {
     /**
      * Trigger order. Market trigger (no limitPrice): execution price bound = trigger price ±
      * `opts.slippage` bps (the caller's resolveSlippage() output — required; the adapter never
-     * reads settings, §13.10 #1), tick-aligned toward crossing (§13.10 #3), recorded in the
+     * reads settings), tick-aligned toward crossing, recorded in the
      * result as `protection`. Accepted risk: a fast move through the bound leaves the
      * triggered order unfilled.
      * TP vs SL: `opts.kind` given (TP/SL legs) → that type as given (a trigger already crossed
@@ -665,12 +708,27 @@ export declare class LighterAdapter implements ExchangeAdapter {
     private _withdrawRaw;
     editOrder(symbol: string, orderId: string, price: string, size: string): Promise<unknown>;
     setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<unknown>;
-    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
-    getFundingHistory(symbol: string, limit?: number): Promise<{
-        time: number;
-        rate: string;
-        price: string | null;
-    }[]>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
+    /**
+     * Settled funding prints: GET /api/v1/fundings (apidocs.lighter.xyz/reference/fundings;
+     * `count_back` rows from `start_timestamp`, max 750). Each row is one hourly settlement:
+     * `rate` is PERCENT per 1 h, unsigned, with `direction` "long" (longs pay → positive) or
+     * "short" (shorts pay → negative). Live 2026-10-19 BTC: rate "0.0012", value "0.99315" =
+     * mark 82,763 × 0.000012, i.e. value / mark = rate / 100. NOT the /funding-rates unit (8 h).
+     */
+    getFundingHistory(symbol: string, limit?: number): Promise<FundingHistoryRow[]>;
+    /**
+     * Candles opening in [startTime, endTime] (ms). GET /api/v1/candles answers the
+     * max(count_back, bars in the window) newest bars ending at `end_timestamp`, at most 500
+     * (live 2026-10-19, BTC 1h: a 96-bar window with count_back 1 / 96 → those 96 bars; with
+     * count_back 500 → 500 bars, 404 of them before start_timestamp; a future window → past bars).
+     * So count_back is the window's bar count (≤ 500), rows outside the window are dropped, and a
+     * longer window is paged backwards in 500-bar chunks by moving end_timestamp. `end_timestamp` is
+     * exclusive at second resolution (live: end = a bar's open excludes it, open + 1 s includes it),
+     * so end + 1 s is sent for an inclusive --end. Each answer's `r`
+     * must be the requested resolution. Intervals outside LIGHTER_CANDLE_INTERVALS and windows over
+     * LIGHTER_KLINE_MAX_PAGES pages are refused with INVALID_PARAMS before any request.
+     */
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
     /**
      * Account-wide history: ONE request per 100 rows, whatever the number of markets (the former
@@ -713,8 +771,9 @@ export declare class LighterAdapter implements ExchangeAdapter {
      */
     getFundingPayments(limit?: number): Promise<ExchangeFundingPayment[]>;
     /**
-     * Get funding rates for all markets.
-     * API: GET /api/v1/funding-rates
+     * GET /api/v1/funding-rates: the venue's PREDICTED rate × 8, a fraction per 8 h — not the venue
+     * basis (1 h; market rows carry the settled hourly rate, fundingStats). Not used for funding
+     * comparisons; normalize with 8 h if read.
      */
     getFundingRates(): Promise<Map<string, {
         rate: string;
@@ -779,7 +838,7 @@ export declare class LighterAdapter implements ExchangeAdapter {
     private nextClientOrderIndex;
     private ensureSigner;
     /**
-     * One WASM signer (one Go runtime) per `${venueId}:${network}` (design §10.5).
+     * One WASM signer (one Go runtime) per `${venueId}:${network}`.
      * lighter-go keys its clients by (accountIndex, apiKeyIndex) only and keeps a
      * package-global chainId for L1 messages, so two venues must never share a
      * runtime. Keyed by venue+network rather than chainId because Lighter testnet