perp-cli 0.15.0 → 0.16.0

package/dist/positions-by-address.js

@@ -0,0 +1,46 @@
+/**
+ * `perp account positions --address` and MCP get_positions_by_address: one read path over the
+ * registry (VenuePublicData.fetchPositionsByAddress). Keyless; nothing is signed.
+ */
+import { PerpError } from "./errors.js";
+import { fetchPositionsByAddress, getVenue, listPublicPositionVenues } from "./exchanges/venue.js";
+import { bareSymbolOf } from "./commands/market.js";
+/** Rows of `symbol` (plain asset; HIP-3 "xyz:GOLD" also matches "GOLD"; "BTC-PERP" matches "BTC"). */
+export function filterPositionsBySymbol(rows, symbol) {
+    if (symbol === undefined)
+        return rows;
+    const want = bareSymbolOf(symbol).toUpperCase();
+    return rows.filter(r => {
+        const s = r.symbol.toUpperCase();
+        return s === want || bareSymbolOf(r.symbol).toUpperCase() === want || s.split(":").pop() === want;
+    });
+}
+function warningsOf(venue, errors) {
+    return Object.entries(errors).map(([src, e]) => `${venue} ${src} unavailable (${e.code}: ${e.message}) — its positions are missing from this answer`);
+}
+export async function readPositionsByAddress(venue, net, address, opts = {}) {
+    const id = getVenue(venue).id;
+    const r = await fetchPositionsByAddress(id, net, address, { accountIndex: opts.accountIndex });
+    return { venue: id, positions: filterPositionsBySymbol(r.positions, opts.symbol), errors: r.errors, notes: r.notes, warnings: warningsOf(id, r.errors) };
+}
+/** Every venue that reads positions by address; a venue that fails (address format included) is an `errors` entry. */
+export async function readPositionsByAddressAll(net, address, opts = {}) {
+    const venues = listPublicPositionVenues().map(v => v.id);
+    const out = { venues: {}, errors: {}, notes: {}, warnings: [] };
+    const settled = await Promise.allSettled(venues.map(v => readPositionsByAddress(v, net, address, opts.accountIndex !== undefined && v !== "lighter" && v !== "lighter-rh" ? { symbol: opts.symbol } : opts)));
+    settled.forEach((res, i) => {
+        const v = venues[i];
+        if (res.status === "rejected") {
+            const e = res.reason;
+            out.errors[v] = e instanceof PerpError ? { code: e.structured.code, message: e.structured.message } : { code: "EXCHANGE_ERROR", message: e instanceof Error ? e.message : String(e) };
+            return;
+        }
+        out.venues[v] = res.value.positions;
+        for (const [src, e] of Object.entries(res.value.errors))
+            out.errors[`${v}:${src}`] = e;
+        if (res.value.notes.length > 0)
+            out.notes[v] = res.value.notes;
+        out.warnings.push(...res.value.warnings);
+    });
+    return out;
+}

package/dist/strategies/funding-arb.js

@@ -1,13 +1,15 @@
 import { assertCanClosePositions } from "../exchanges/trading-v2.js";
 import { MAX_PRICE_DEVIATION_PCT } from "../exchanges/index.js";
-import { symbolMatch, logSettledRejections } from "../utils.js";
+import { symbolMatch } from "../utils.js";
 import { logExecution } from "../execution-log.js";
 import { updateJobState } from "../jobs.js";
 import { invalidateCache } from "../cache.js";
 import { fetchBalancesWithFailures, computeRebalancePlan, hasEnoughBalance, marketLeverageOf, requiredArbMargin } from "../rebalance.js";
 import { checkArbLiquidity } from "../liquidity.js";
-import { computeAnnualSpread } from "../funding.js";
-import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, } from "../shared-api.js";
+import { computeAnnualSpread, getFundingHours } from "../funding.js";
+import { fetchVenuesRates } from "../funding/rates.js";
+import { getVenue } from "../exchanges/venue.js";
+import { sharedApiNetwork } from "../api/public/urls.js";
 import { computeMatchedSize } from "../arb-sizing.js";
 import { closePerpPairVerified, openPerpPairVerified } from "../commands/arb-auto.js";
 import { closePerpVerified, isOutcomeUnknown } from "../bot/perp-order.js";
@@ -21,54 +23,17 @@ async function sizeDecimalsOf(adapter, symbol) {
     return m === undefined ? null : m.sizeDecimals;
 }
 async function fetchAllRates() {
-    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
-    // alive when one DEX errors out, while rejection reasons get logged to
-    // stderr (explicit failure, never silent).
-    const [pacRates, hlRates, ltRates] = await Promise.allSettled([
-        fetchPacificaPrices().then(assets => assets.map(p => ({
-            exchange: "pacifica", symbol: p.symbol, fundingRate: p.funding, markPrice: p.mark,
-        }))),
-        fetchHyperliquidMeta().then(assets => assets.map(a => ({
-            exchange: "hyperliquid", symbol: a.symbol, fundingRate: a.funding, markPrice: a.markPx,
-        }))),
-        (async () => {
-            const [details, funding] = await Promise.all([
-                fetchLighterOrderBookDetails(),
-                fetchLighterFundingRates(),
-            ]);
-            const priceMap = new Map(details.map(d => [d.marketId, d.lastTradePrice]));
-            const symMap = new Map(details.map(d => [d.marketId, d.symbol]));
-            const out = [];
-            for (const fr of funding) {
-                const symbol = fr.symbol || symMap.get(fr.marketId) || "";
-                if (!symbol)
-                    continue;
-                // Prefer fr.markPrice; fall back to orderBook last-trade as documented
-                // price source preference (NOT an error fallback).
-                const directMark = fr.markPrice;
-                const fallbackMark = priceMap.get(fr.marketId);
-                let markPrice;
-                if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
-                    markPrice = directMark;
-                }
-                else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
-                    markPrice = fallbackMark;
-                }
-                // SSOT rule #2: skip rows whose mark price cannot be resolved at all
-                // — never publish a 0 mark price downstream.
-                if (markPrice === undefined)
-                    continue;
-                out.push({ exchange: "lighter", symbol, fundingRate: fr.rate, markPrice });
-            }
-            return out;
-        })(),
-    ]);
-    logSettledRejections([pacRates, hlRates, ltRates], ["pacifica", "hyperliquid", "lighter"], "funding-arb");
-    return [
-        ...(pacRates.status === "fulfilled" ? pacRates.value : []),
-        ...(hlRates.status === "fulfilled" ? hlRates.value : []),
-        ...(ltRates.status === "fulfilled" ? ltRates.value : []),
-    ];
+    // The SAME rate rows as `arb scan --rates` (fetchVenuesRates): one per venue and canonical
+    // symbol (unclassified / ambiguous tickers have no canonical and never pair). Each venue is
+    // independent; a failed one is reported on stderr (explicit, never silent).
+    const venues = ["pacifica", "hyperliquid", "lighter"].map(id => getVenue(id));
+    const { rates: fetched, exchangeErrors } = await fetchVenuesRates(venues, sharedApiNetwork(), false);
+    // Never a leg on an unverified rate (row label; the venue filter already drops them).
+    const rates = fetched.filter(r => r.fundingVerified);
+    for (const [ex, msg] of Object.entries(exchangeErrors))
+        process.stderr.write(`[funding-arb] ${ex}: funding rates unavailable — ${msg}\n`);
+    // computeAnnualSpread / toHourlyRate normalize with the venue's basis: keep each rate in it.
+    return rates.map(r => ({ exchange: r.exchange, symbol: r.canonical, venueSymbol: r.symbol, fundingRate: r.hourlyRate * getFundingHours(r.exchange), markPrice: r.markPrice }));
 }
 // annualize: use computeAnnualSpread from funding.ts for cross-exchange comparison
 /**
@@ -111,8 +76,12 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                 const rates = await fetchAllRates();
                 // Group by symbol
                 const rateMap = new Map();
+                // --symbols selects an asset by its canonical key or any venue's own symbol (kPEPE selects
+                // the whole 1000PEPE group, Lighter's leg included).
+                const want = new Set((params.symbols ?? []).map(s => s.toUpperCase()));
+                const wanted = new Set(rates.filter(r => want.has(r.symbol.toUpperCase()) || want.has(r.venueSymbol.toUpperCase())).map(r => r.symbol));
                 for (const r of rates) {
-                    if (params.symbols?.length && !params.symbols.includes(r.symbol))
+                    if (want.size > 0 && !wanted.has(r.symbol))
                         continue;
                     if (!rateMap.has(r.symbol))
                         rateMap.set(r.symbol, []);
@@ -233,6 +202,8 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                         if (annualSpread >= params.minSpread) {
                             const longEx = lowest.exchange;
                             const shortEx = highest.exchange;
+                            const longSym = lowest.venueSymbol;
+                            const shortSym = highest.venueSymbol;
                             log(`[ARB] ENTRY signal: ${symbol} spread ${annualSpread.toFixed(1)}% — long ${longEx} (${(lowest.fundingRate * 100).toFixed(4)}%) / short ${shortEx} (${(highest.fundingRate * 100).toFixed(4)}%)`);
                             if (params.autoExecute) {
                                 const longAdapter = adapters.get(longEx);
@@ -243,7 +214,7 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                 }
                                 // Check orderbook liquidity & adjust size
                                 const requestedUsd = params.sizeUsd ?? Number(params.size) * highest.markPrice;
-                                const liq = await checkArbLiquidity(longAdapter, shortAdapter, symbol, requestedUsd, 0.5, log);
+                                const liq = await checkArbLiquidity(longAdapter, shortAdapter, longSym, requestedUsd, 0.5, log, shortSym);
                                 if (!liq.viable)
                                     continue;
                                 // Compute matched size (same for both legs) at each venue's published size precision —
@@ -251,7 +222,7 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                 let longDec;
                                 let shortDec;
                                 try {
-                                    [longDec, shortDec] = await Promise.all([sizeDecimalsOf(longAdapter, symbol), sizeDecimalsOf(shortAdapter, symbol)]);
+                                    [longDec, shortDec] = await Promise.all([sizeDecimalsOf(longAdapter, longSym), sizeDecimalsOf(shortAdapter, shortSym)]);
                                 }
                                 catch (e) {
                                     log(`[ARB] Skip ${symbol}: could not read the market size precision (${e instanceof Error ? e.message : String(e)})`);
@@ -272,7 +243,7 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                     let longLev;
                                     let shortLev;
                                     try {
-                                        [longLev, shortLev] = await Promise.all([marketLeverageOf(longAdapter, symbol), marketLeverageOf(shortAdapter, symbol)]);
+                                        [longLev, shortLev] = await Promise.all([marketLeverageOf(longAdapter, longSym), marketLeverageOf(shortAdapter, shortSym)]);
                                     }
                                     catch (e) {
                                         log(`[ARB] Skip ${symbol}: could not read the market leverage (${e instanceof Error ? e.message : String(e)})`);
@@ -288,8 +259,8 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                 log(`[ARB] Opening: ${matched.size} ${symbol} — long ${longEx} then short ${shortEx}, each verified ($${matched.notional.toFixed(0)}/leg, slippage ~${liq.longSlippage.toFixed(2)}%/${liq.shortSlippage.toFixed(2)}%)...`);
                                 const openPair = (size) => openPerpPairVerified({
                                     source: SOURCE, sym: symbol,
-                                    longAdapter, longExch: longEx, longSym: symbol,
-                                    shortAdapter, shortExch: shortEx, shortSym: symbol,
+                                    longAdapter, longExch: longEx, longSym,
+                                    shortAdapter, shortExch: shortEx, shortSym,
                                     size, smart: false, log, shortLotRetry: true,
                                 });
                                 let res = await openPair(matched.size);
@@ -323,6 +294,8 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                     entrySpread: annualSpread,
                                     openedAt: Date.now(),
                                     entryPrices: { long: lowest.markPrice, short: highest.markPrice },
+                                    longSymbol: longSym,
+                                    shortSymbol: shortSym,
                                 });
                                 // Entry record: `arb status` / `arb close` confirm this pair from it (arbPairProvenance).
                                 logExecution({
@@ -403,8 +376,8 @@ async function closeArbPosition(pos, adapters, log) {
     let shortSize;
     try {
         [longSize, shortSize] = await Promise.all([
-            venueLegSize(longAdapter, pos.symbol, "long").then(cap),
-            venueLegSize(shortAdapter, pos.symbol, "short").then(cap),
+            venueLegSize(longAdapter, pos.longSymbol, "long").then(cap),
+            venueLegSize(shortAdapter, pos.shortSymbol, "short").then(cap),
         ]);
     }
     catch (err) {
@@ -418,8 +391,8 @@ async function closeArbPosition(pos, adapters, log) {
     if (longSize !== null && shortSize !== null) {
         const res = await closePerpPairVerified({
             source: SOURCE, sym: pos.symbol,
-            longAdapter, longExch: pos.longExchange, longSym: pos.symbol, longSize,
-            shortAdapter, shortExch: pos.shortExchange, shortSym: pos.symbol, shortSize,
+            longAdapter, longExch: pos.longExchange, longSym: pos.longSymbol, longSize,
+            shortAdapter, shortExch: pos.shortExchange, shortSym: pos.shortSymbol, shortSize,
             smart: false, log,
         });
         if (res.status === "closed") {
@@ -448,7 +421,7 @@ async function closeArbPosition(pos, adapters, log) {
         return false;
     };
     try {
-        const c = await closePerpVerified(adapter, venue, pos.symbol, side, size);
+        const c = await closePerpVerified(adapter, venue, leg === "long" ? pos.longSymbol : pos.shortSymbol, side, size);
         if (c.residual > 0)
             return q(`orphaned ${leg} close on ${venue} closed ${c.closed} of ${size}, ${c.residual} still open${c.note !== null ? ` (${c.note})` : ""}`);
     }

package/dist/utils.d.ts

@@ -34,7 +34,17 @@ export interface ApiResponse<T = unknown> {
         skippedRows?: {
             count: number;
             reason: string;
-        };
+        }; /** Why a value is null / degraded (e.g. a venue's funding rate unavailable). */
+        warnings?: string[]; /** `arb scan --rates`: the --min threshold (annualized %) and how many pairs it hid. */
+        minSpread?: number;
+        belowMinSpread?: number; /** Public-address reads (`account positions --address`): the address read, "public", the sub-reads that failed and notes on an empty answer. */
+        address?: string;
+        source?: "public";
+        errors?: Record<string, {
+            code: string;
+            message: string;
+        }>;
+        notes?: string[];
     };
 }
 /** Wrap successful result in standard envelope */

package/dist/venue-health.js

@@ -68,7 +68,7 @@ export async function probeVenueHealth(network, venueIds) {
         const ping = pingFor(v.id, network);
         return ping !== null
             ? ping()
-            : timed("markets", async () => { await v.publicData.fetchMarkets(network); return { ok: true, status: null }; });
+            : timed("markets", async () => { await v.publicData.fetchMarkets(network, { funding: false }); return { ok: true, status: null }; });
     }));
     const probes = probed.map((v, i) => ({ venue: v.id, ...results[i], apiStatus: v.apiStatus.kind }));
     return { probes, skipped, allHealthy: probes.every(p => p.ok) };

package/dist/ws/arcus-market.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Arcus GET /v1/markets eligibility — the one rule for every Arcus surface (WS directory, CLI
+ * adapter market-data reads, public market data / funding / arb, MCP): a market is listed only
+ * while `status` is "ONLINE". OFFLINE markets (live 2026-10-19: F, BAC, CCL, VT, SGOV, RVI-USD —
+ * 6 of 70) publish placeholder zeros for mark / index / rate / OI / volume, never real values.
+ */
+export declare function isArcusOnlineMarket(row: {
+    status?: unknown;
+}): boolean;

package/dist/ws/arcus-market.js

@@ -0,0 +1,9 @@
+/**
+ * Arcus GET /v1/markets eligibility — the one rule for every Arcus surface (WS directory, CLI
+ * adapter market-data reads, public market data / funding / arb, MCP): a market is listed only
+ * while `status` is "ONLINE". OFFLINE markets (live 2026-10-19: F, BAC, CCL, VT, SGOV, RVI-USD —
+ * 6 of 70) publish placeholder zeros for mark / index / rate / OI / volume, never real values.
+ */
+export function isArcusOnlineMarket(row) {
+    return row.status === "ONLINE";
+}

package/dist/ws/aster-market.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Aster GET /fapi/v3/exchangeInfo market eligibility — the one rule for every Aster surface (WS
+ * directory, CLI adapter, public market data / funding / arb, MCP): a market is listed only while
+ * `contractType` is "PERPETUAL" and `status` is "TRADING". Live 2026-10-19: TRADING/PERPETUAL 605,
+ * SETTLING/PERPETUAL 23 (being delisted: TONUSDT, IRUSDT, …), PENDING_TRADING with contractType ""
+ * 6 (MBLUSDT, AFEEUSDT, …) — neither of the latter two streams or trades.
+ *
+ * The quote asset is NOT part of eligibility: USD1 / U quoted perps are live markets, listed by
+ * every surface (asterCliSymbol gives the CLI symbol, asterMatchable whether it gets a canonical).
+ */
+export declare function isAsterListedPerpetual(row: {
+    contractType?: unknown;
+    status?: unknown;
+}): boolean;
+/**
+ * CLI symbol of a listed Aster perpetual: the base for the USDT-quoted market (ETHUSDT → ETH, the
+ * venue's main listing), the venue symbol for any other quote (BTCUSD1, BTCU) — unique per market
+ * and passed to the venue as is.
+ */
+export declare function asterCliSymbol(row: {
+    symbol: string;
+    baseAsset: string;
+    quoteAsset?: unknown;
+}): string;
+/**
+ * Whether a listed Aster market may carry a cross-venue canonical (then `base`): only its USDT
+ * market. USD1 / U quoted ones (BTCUSD1, GPROUSD1, BTCU) are listed but never matched across
+ * venues — so `arb` (scan / auto / exec) never takes one as a leg: Aster arb sizing, margin checks
+ * and transfers are USDT-collateral, and a USD1 / U margined leg is not handled.
+ */
+export declare function asterMatchable(row: {
+    quoteAsset?: unknown;
+}): boolean;

package/dist/ws/aster-market.js

@@ -0,0 +1,30 @@
+/**
+ * Aster GET /fapi/v3/exchangeInfo market eligibility — the one rule for every Aster surface (WS
+ * directory, CLI adapter, public market data / funding / arb, MCP): a market is listed only while
+ * `contractType` is "PERPETUAL" and `status` is "TRADING". Live 2026-10-19: TRADING/PERPETUAL 605,
+ * SETTLING/PERPETUAL 23 (being delisted: TONUSDT, IRUSDT, …), PENDING_TRADING with contractType ""
+ * 6 (MBLUSDT, AFEEUSDT, …) — neither of the latter two streams or trades.
+ *
+ * The quote asset is NOT part of eligibility: USD1 / U quoted perps are live markets, listed by
+ * every surface (asterCliSymbol gives the CLI symbol, asterMatchable whether it gets a canonical).
+ */
+export function isAsterListedPerpetual(row) {
+    return row.contractType === "PERPETUAL" && row.status === "TRADING";
+}
+/**
+ * CLI symbol of a listed Aster perpetual: the base for the USDT-quoted market (ETHUSDT → ETH, the
+ * venue's main listing), the venue symbol for any other quote (BTCUSD1, BTCU) — unique per market
+ * and passed to the venue as is.
+ */
+export function asterCliSymbol(row) {
+    return row.quoteAsset === "USDT" ? row.baseAsset : row.symbol;
+}
+/**
+ * Whether a listed Aster market may carry a cross-venue canonical (then `base`): only its USDT
+ * market. USD1 / U quoted ones (BTCUSD1, GPROUSD1, BTCU) are listed but never matched across
+ * venues — so `arb` (scan / auto / exec) never takes one as a leg: Aster arb sizing, margin checks
+ * and transfers are USDT-collateral, and a USD1 / U margined leg is not handled.
+ */
+export function asterMatchable(row) {
+    return row.quoteAsset === "USDT";
+}

package/dist/ws/index.d.ts

@@ -4,7 +4,7 @@
  */
 /**
  * Every perp-cli venue id. "ondo" and "qfex" are included for type stability but have no perp-cli/ws
- * codec until 0.15.1 (there is no `ondo` / `qfex` export to pass to createVenueStream yet).
+ * codec (planned, not yet available: there is no `ondo` / `qfex` export to pass to createVenueStream).
  */
 type VenueId = "pacifica" | "hyperliquid" | "lighter" | "aster" | "lighter-rh" | "ondo" | "arcus" | "qfex";
 declare const VENUE_IDS: readonly VenueId[];
@@ -74,6 +74,10 @@ declare class WsError extends Error {
         remediation?: string;
         details?: Record<string, unknown>;
     });
+    /** `structured.code` — the same place as `code` on error events (`e.code`). */
+    get code(): WsErrorCode;
+    /** `structured.remediation` — the same place as `remediation` on error events; null when none. */
+    get remediation(): string | null;
 }
 /** Structural check: a PerpError (CLI) or a WsError — anything carrying `structured.{code,message}`. */
 declare function isPerpError(e: unknown): e is {
@@ -109,6 +113,11 @@ interface WsLike {
         wasClean?: boolean;
     }) => void) | null;
     onerror: ((ev: unknown) => void) | null;
+    /**
+     * Optional: settles once the underlying socket is fully closed (no timer or socket left). The
+     * Node transport sets it; `stream.close()` awaits it (bounded) so the process is idle afterwards.
+     */
+    readonly whenClosed?: Promise<void>;
 }
 type WsFactory = (url: string) => WsLike;
 type FetchLike = (input: string, init?: {
@@ -384,7 +393,7 @@ type UserRef = {
     venue: "lighter" | "lighter-rh";
     accountIndex: number;
 }
-/** KNOWN GAP in 0.15.0: Aster user channels are not implemented (CAPABILITY_UNSUPPORTED); 0.15.1. */
+/** KNOWN GAP: Aster user channels are not implemented (CAPABILITY_UNSUPPORTED; planned, not yet available). */
  | {
     venue: "aster";
     user: `0x${string}`;
@@ -527,7 +536,7 @@ interface VenueStreamOptions {
     canonicalize?: Canonicalize;
     /** Needed for kind:"user". */
     credentials?: CredentialProvider;
-    /** Default false. Required for user channels whose auth needs a signing secret in the page (Aster/Ondo/QFEX, 0.15.1). */
+    /** Default false. Required for user channels whose auth needs a signing secret in the page (Aster / Ondo / QFEX — planned, not yet available). */
     allowInPageSecrets?: boolean;
     /** ≤ venue limits. */
     budget?: {
@@ -807,8 +816,8 @@ declare function createVenueStream(codec: VenueCodec, opts?: VenueStreamOptions)
  */
 declare const USD_LIKE_QUOTES: ReadonlySet<string>;
 /**
- * HIP-3 (dex set) → "<dex>:<BASE>". A USD-like quote → "<BASE>". Any other quote, or an unknown
- * quote (null), → null (not comparable by default).
+ * HIP-3 (dex set) → "<dex>:<BASE>". An ambiguous ticker (isUnclassifiedTicker) → null. A USD-like
+ * quote → "<BASE>". Any other quote, or an unknown quote (null), → null (not comparable by default).
  */
 declare const defaultCanonicalize: Canonicalize;
 
@@ -871,9 +880,17 @@ interface FundingComparator {
     subscribe(cb: (rows: FundingRow[], changed: string[]) => void): () => void;
     close(): void;
 }
-/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+/**
+ * Rate per hour as a FRACTION (0.0000125 = 0.00125 %/h): `rate / rateIntervalHours`.
+ * @experimental 0.15.x (stable from 0.16.0 after consumer sign-off)
+ */
 declare function toHourly(rate: Dec | null, rateIntervalHours: number | null): number | null;
-/** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
+/**
+ * Simple annualized rate as a FRACTION, not a percent: `toHourly × 24 × 365` (0.0000125/h → 0.1095,
+ * i.e. 10.95 %). The CLI's `annualizedPct` (`arb scan --rates`, MCP `get_funding_rates`) is the same
+ * quantity in PERCENT (10.95): multiply `toApr` by 100 to compare the two.
+ * @experimental 0.15.x (stable from 0.16.0 after consumer sign-off)
+ */
 declare function toApr(rate: Dec | null, rateIntervalHours: number | null): number | null;
 /** @experimental 0.15.x (stable from 0.16.0 after consumer sign-off) */
 declare function createFundingComparator(opts: FundingComparatorOptions): FundingComparator;
@@ -916,7 +933,11 @@ declare const pacifica: VenueCodec;
  *
  * Units (Phase 0, the key correction): WS `funding_rate` (last settled) and `current_funding_rate`
  * (predicted) are PERCENT per 1 h → converted to a fraction by an exact 2-place decimal shift,
- * rateIntervalHours = settlementIntervalHours = 1. `open_interest` is USD notional (not base).
+ * rateIntervalHours = settlementIntervalHours = 1. `open_interest` is USD notional (not base) and
+ * one side — INFERRED, not documented by the venue: WS open_interest / mark = REST orderBookDetails
+ * `open_interest` (base) (2026-10-19, BTC: 174.88 M USD / 82,387 = 2,122.7 BTC), and the venue's
+ * exchangeMetrics open_interest — a DAILY snapshot, two days old when compared — was ≈ 2× the
+ * current one-side figure (336.6 M USD).
  * Errors arrive as {error:{code,message}} with no channel field (matched by the channel name in
  * the message). Spot markets (market_type "spot" in /api/v1/orderBooks) are not perps and skipped.
  *
@@ -928,7 +949,7 @@ declare const lighter: VenueCodec;
 declare const lighterRh: VenueCodec;
 
 /**
- * Aster codec (§6.1, public only in 0.15.0). One combined-stream socket (`/stream`, frames
+ * Aster codec (§6.1, public channels only). One combined-stream socket (`/stream`, frames
  * {stream, data}) with `!markPrice@arr@1s` (every symbol, 1 s) + `!ticker@arr` (only changed symbols).
  * r = accruing current-period rate (Phase 0: == premiumIndex.lastFundingRate ≠ last settled).
  * The funding interval is per market from the LABELLED REST source `rest:/fapi/v3/fundingInfo`