perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/variational/public.js

@@ -0,0 +1,430 @@
+/**
+ * Variational public market data — the OFFICIAL read-only API (venues/variational.ts).
+ *
+ * Source: `GET /metadata/v2/stats` (docs.variational.io/technical-documentation/api). One call
+ * returns every listing; it is shared by every reader for VARIATIONAL_STATS_TTL_MS through the
+ * file cache (cache.ts, cross-process, raw JSON body only) plus an in-process in-flight promise,
+ * so `market list` + `arb scan` + `perp health` inside the window cost ONE request.
+ *
+ * Listings (575 on 2026-10-19: 557 perpetuals, 18 swaps):
+ *  - ticker "BTC-PERP" / "XAU-SWAP", contract_type "perpetual" | "swap". Perp display symbol =
+ *    the base ("BTC"); a swap keeps its suffix ("XAU-SWAP") so it never collides with "XAU" perp.
+ *  - mark_price, volume_24h (USDC), open_interest.{long,short}_open_interest (USDC, single-sided:
+ *    trader positions only — the OLP is the other side). Base-unit OI is NOT published, so the
+ *    legacy openInterest (base units) is null; the USD figures are carried separately.
+ *  - quotes.{base,size_1k,size_100k,size_1m}.{bid,ask}: the OLP's INDICATIVE RFQ quotes at fixed
+ *    notionals (may be cached up to 600 s; quotes.updated_at). Omitted while a market is closed.
+ *
+ * Funding (docs.variational.io/omni/trading/funding-rates):
+ *  - perpetual: funding.last.interval_rate is a decimal fraction for ONE interval_seconds window
+ *    (1h / 4h / 8h, per market), positive = longs pay. annualized_rate is the same rate × 365 d /
+ *    interval — the identity is checked per row; a row that breaks it gets no rate (warned).
+ *  - rateKind "predicted": `last` is recomputed during the window (live samples 2026-10-19: 175
+ *    of 557 perps changed within 2 min under the same next_timestamp) and `next` ("predicted
+ *    funding rate for the next interval") equals it. It is the rate the OLP will charge at
+ *    next_timestamp, not a settled print.
+ *  - swap: separate long / short rates paid once per trading day — there is no single funding
+ *    rate, so fundingRate is null and swaps are never matched across venues (canonical null);
+ *    the long / short rates are shown on the Variational rows only.
+ */
+import { getCached, setCached } from "../../cache.js";
+import { canonicalFor } from "../canonical-symbols.js";
+import { networkConfig } from "../venue.js";
+import { variationalVenue } from "../venues/variational.js";
+import { variationalShapeError, VariationalClient } from "./client.js";
+import { symbolNotFound } from "../unknown-symbol.js";
+/** How long one stats payload serves every reader (the venue itself sends max-age=30). */
+export const VARIATIONAL_STATS_TTL_MS = 5_000;
+const YEAR_SECONDS = 365 * 86_400;
+/** interval_rate vs annualized_rate × interval / 365 d: both are rounded to ~4 significant digits. */
+const RATE_IDENTITY_REL_TOL = 0.005;
+const RATE_IDENTITY_ABS_TOL = 1e-9;
+/**
+ * TradFi perpetuals by class (the API publishes no asset class). Equities / ETFs match by ticker
+ * identity; commodities / pre-IPO only through EXPLICIT_CANONICAL. A perp whose `name` reads like
+ * a company or fund but is missing here is listed as equity with NO canonical symbol (never matched
+ * across venues) until it is classified — see looksTradFi().
+ */
+const TRADFI_PERP_CLASS = {
+    // Commodities
+    XAU: "commodity", XAG: "commodity", XPD: "commodity", XPT: "commodity", CL: "commodity", BZ: "commodity",
+    COPPER: "commodity", NATGAS: "commodity",
+    // Pre-IPO
+    ANTHROPIC: "preIpo", OPENAI: "preIpo",
+    // ETFs
+    DRAM: "etf", EWJ: "etf", EWT: "etf", EWY: "etf", EWZ: "etf", IWM: "etf", KSTR: "etf", QQQ: "etf", SOXL: "etf",
+    SOXS: "etf", SPCX: "etf", TMF: "etf", TZA: "etf", URNM: "etf", UVXY: "etf", XBI: "etf", XLE: "etf", US500: "etf",
+    // Equities
+    AAOI: "equity", AAPL: "equity", ADBE: "equity", ALAB: "equity", AMAT: "equity", AMD: "equity", AMZN: "equity",
+    APP: "equity", ARM: "equity", ASML: "equity", AVGO: "equity", BABA: "equity", BBX: "equity", BE: "equity",
+    BMNR: "equity", BNC: "equity", BOT: "equity", BRKB: "equity", BX: "equity", CAT: "equity", CBRS: "equity",
+    CIEN: "equity", COIN: "equity", COST: "equity", CRCL: "equity", CRDO: "equity", CRM: "equity", CRWD: "equity",
+    CRWV: "equity", CSCO: "equity", DELL: "equity", DIS: "equity", DJT: "equity", DKNG: "equity", EBAY: "equity",
+    FLNC: "equity", FWDI: "equity", GLW: "equity", GME: "equity", GOOGL: "equity", GPRO: "equity", HD: "equity",
+    HIMS: "equity", HOOD: "equity", HPE: "equity", IBM: "equity", INTC: "equity", IREN: "equity", JPM: "equity",
+    KLAC: "equity", KO: "equity", LITE: "equity", LLY: "equity", META: "equity", MRNA: "equity", MRVL: "equity",
+    MSFT: "equity", MSTR: "equity", MU: "equity", NBIS: "equity", NFLX: "equity", NOK: "equity", NOW: "equity",
+    NVDA: "equity", NVO: "equity", ONDS: "equity", ORCL: "equity", PAYP: "equity", PENG: "equity", PLTR: "equity",
+    QCOM: "equity", QNTX: "equity", RDDT: "equity", RIVN: "equity", RKLB: "equity", SHAZ: "equity", SHOP: "equity",
+    SKHY: "equity", SMCI: "equity", SNDK: "equity", SNOW: "equity", SOFI: "equity", SONY: "equity", STRC: "equity",
+    STXX: "equity", TER: "equity", TSLA: "equity", TSM: "equity", TTWO: "equity", TXN: "equity", UBER: "equity",
+    USAR: "equity", VISA: "equity", WEN: "equity", WMT: "equity", ZM: "equity",
+};
+/**
+ * Variational tickers whose canonical symbol is NOT the ticker:
+ *  - US500-PERP is "State Street SPDR S&P 500 ETF Trust" (SPY, mark ≈ $760), not the S&P 500 index
+ *    that other venues list as US500 (→ SPX).
+ * `null` = never matched across venues — the same exclusions the other venues apply:
+ *  - SPX-PERP is the SPX6900 token; "SPX" is the canonical key of the S&P 500 index, and
+ *    Hyperliquid / Aster / Lighter all exclude their SPX6900 (legacy-public.ts AMBIGUOUS,
+ *    lighter-public.ts LIGHTER_AMBIGUOUS), so it could only ever pair with the index.
+ *  - QNT-PERP is Quant (crypto); QNT is Quantinuum on Arcus / QFEX (LIGHTER_AMBIGUOUS too).
+ *
+ * Live cross-venue survey (2026-10-19, 440 Variational canonicals shared with another venue):
+ * ZETA (ZetaChain vs QFEX Zeta Global), DIA (DIA oracle vs Lighter DIA ETF) and BEAM (Beam vs QFEX
+ * Beam Global) also collide with an equity / ETF elsewhere but are the same token on the crypto
+ * venues; the wrong pairing is dropped, with a stderr warning, by the cross-venue price guard
+ * (rates.ts dropPriceOutliers / pair gap).
+ */
+const CANONICAL_OVERRIDE = {
+    US500: "SPY",
+    SPX: null,
+    QNT: null,
+};
+/**
+ * Hint for a cross-venue lookup by a Variational ticker whose canonical symbol differs (arb scan
+ * --compare US500): where it is compared instead, or that it is never matched. null = no override.
+ */
+export function canonicalHintFor(symbol) {
+    const up = symbol.trim().toUpperCase().replace(/-PERP$/, "");
+    if (!(up in CANONICAL_OVERRIDE))
+        return null;
+    const canonical = CANONICAL_OVERRIDE[up];
+    return canonical === null
+        ? `Variational's ${up}-PERP is never matched across venues (the ticker means a different asset elsewhere)`
+        : `Variational's ${up}-PERP is compared as ${canonical}: perp arb scan --compare ${canonical} --include-unverified`;
+}
+/** Swaps (daily-funded TradFi swaps) by class — display only: swaps never get a canonical symbol. */
+const SWAP_CLASS = {
+    XAU: "commodity", XAG: "commodity", UKOIL: "commodity", USOIL: "commodity", HOIL: "commodity", GASOL: "commodity",
+    COCOA: "commodity", COPP: "commodity",
+    US30: "index", US100: "index", US500: "index", US400: "index", US2K: "index", CNA50: "index", TWI: "index",
+    USFNG: "index", VXI: "index",
+    DXI: "fx",
+};
+/** A listing name that reads like a company / fund (an unclassified TradFi perp). */
+const TRADFI_NAME = /\b(Inc|Corp|Corporation|Company|Holdings?|Ltd|Limited|plc|N\.V|A\/S|Oyj|ETF|Common Stock|Class [A-Z])\b\.?/i;
+export function looksTradFi(name) {
+    return name !== null && TRADFI_NAME.test(name);
+}
+/** Each distinct warning once per process (the stats body is re-parsed on every read). */
+const warned = new Set();
+export function warnOnce(warn, msg) {
+    if (warned.has(msg))
+        return;
+    warned.add(msg);
+    warn(msg);
+}
+export const QUOTE_TIERS = ["base", "size_1k", "size_100k", "size_1m"];
+/** USD notional of each quote tier; "base" = the market's minimum order size (notional not published). */
+export const QUOTE_TIER_NOTIONAL_USD = {
+    base: null, size_1k: "1000", size_100k: "100000", size_1m: "1000000",
+};
+const DEC = /^-?\d+(\.\d+)?$/;
+const isDec = (v) => typeof v === "string" && DEC.test(v);
+class RowError extends Error {
+}
+const bad = (what) => { throw new RowError(what); };
+const dec = (v, what) => (isDec(v) ? v : bad(`${what} is not a decimal string`));
+const obj = (v, what) => (v !== null && typeof v === "object" && !Array.isArray(v) ? v : bad(`${what} is not an object`));
+/** Unix seconds → ms; null stays null (documented for swaps). */
+function tsMs(v, what, nullable) {
+    if (v === null && nullable)
+        return null;
+    if (typeof v !== "number" || !Number.isInteger(v) || v <= 0)
+        return bad(`${what} is not a unix-seconds integer`);
+    return v * 1000;
+}
+function perpRate(v, what) {
+    const r = obj(v, what);
+    return { annualized: dec(r.annualized_rate, `${what}.annualized_rate`), interval: dec(r.interval_rate, `${what}.interval_rate`) };
+}
+function swapRate(v, what) {
+    if (v === null)
+        return null;
+    const r = obj(v, what);
+    return {
+        annualizedLong: dec(r.annualized_long_rate, `${what}.annualized_long_rate`),
+        annualizedShort: dec(r.annualized_short_rate, `${what}.annualized_short_rate`),
+        intervalLong: dec(r.interval_long_rate, `${what}.interval_long_rate`),
+        intervalShort: dec(r.interval_short_rate, `${what}.interval_short_rate`),
+    };
+}
+function funding(v, kind) {
+    if (v === null)
+        return null;
+    const f = obj(v, "funding");
+    const intervalSeconds = f.interval_seconds;
+    if (typeof intervalSeconds !== "number" || !Number.isInteger(intervalSeconds) || intervalSeconds <= 0)
+        return bad("funding.interval_seconds is not a positive integer");
+    if (kind === "perpetual") {
+        return {
+            kind, intervalSeconds,
+            nextFundingTime: tsMs(f.next_timestamp, "funding.next_timestamp", false),
+            last: perpRate(f.last, "funding.last"),
+            next: f.next === null ? null : perpRate(f.next, "funding.next"),
+        };
+    }
+    return {
+        kind, intervalSeconds,
+        nextFundingTime: tsMs(f.next_timestamp, "funding.next_timestamp", true),
+        last: swapRate(f.last, "funding.last"),
+        next: swapRate(f.next, "funding.next"),
+    };
+}
+function quotes(v) {
+    if (v === undefined)
+        return null; // documented: omitted when unavailable (e.g. a closed swap)
+    const q = obj(v, "quotes");
+    if (typeof q.updated_at !== "string" || Number.isNaN(Date.parse(q.updated_at)))
+        return bad("quotes.updated_at is not an ISO time");
+    const tiers = [];
+    for (const tier of QUOTE_TIERS) {
+        if (q[tier] === undefined)
+            continue; // documented: individual sizes are omitted when unavailable
+        const t = obj(q[tier], `quotes.${tier}`);
+        tiers.push({ tier, notionalUsd: QUOTE_TIER_NOTIONAL_USD[tier], bid: dec(t.bid, `quotes.${tier}.bid`), ask: dec(t.ask, `quotes.${tier}.ask`) });
+    }
+    return { updatedAt: q.updated_at, tiers };
+}
+function classify(base, contractType, name) {
+    if (contractType === "swap") {
+        const assetClass = SWAP_CLASS[base];
+        return assetClass === undefined ? null : { assetClass, canonical: null };
+    }
+    const known = TRADFI_PERP_CLASS[base];
+    const assetClass = known ?? (looksTradFi(name) ? "equity" : "crypto");
+    if (known === undefined && assetClass === "equity")
+        return { assetClass, canonical: null }; // unclassified TradFi
+    if (base in CANONICAL_OVERRIDE)
+        return { assetClass, canonical: CANONICAL_OVERRIDE[base] };
+    return { assetClass, canonical: canonicalFor("variational", base, assetClass) };
+}
+/** Parse one listing. Throws RowError (caught per row by parseStats) on any shape drift. */
+function parseListing(raw) {
+    const r = obj(raw, "listing");
+    if (typeof r.ticker !== "string")
+        return bad("ticker is not a string");
+    const m = /^(.+)-(PERP|SWAP)$/.exec(r.ticker);
+    if (m === null)
+        return bad(`ticker ${r.ticker} has no -PERP / -SWAP suffix`);
+    const contractType = r.contract_type;
+    if (contractType !== "perpetual" && contractType !== "swap")
+        return { skip: `unknown contract_type ${String(contractType)}` };
+    if ((contractType === "perpetual") !== (m[2] === "PERP"))
+        return bad(`ticker suffix ${m[2]} disagrees with contract_type ${contractType}`);
+    const base = m[1].toUpperCase();
+    const name = r.name === undefined ? null : typeof r.name === "string" ? r.name.replace(/​/g, "").trim() : bad("name is not a string");
+    const markPrice = dec(r.mark_price, "mark_price");
+    if (!(Number(markPrice) > 0))
+        return { skip: "no positive mark price" };
+    const oi = obj(r.open_interest, "open_interest");
+    if (!("funding" in r))
+        return bad("funding is missing (documented as always present)");
+    const cls = classify(base, contractType, name);
+    if (cls === null)
+        return { skip: "unclassified swap market" };
+    return {
+        ticker: r.ticker,
+        contractType,
+        symbol: contractType === "perpetual" ? base : r.ticker,
+        base,
+        name,
+        markPrice,
+        volume24h: dec(r.volume_24h, "volume_24h"),
+        longOpenInterestUsd: dec(oi.long_open_interest, "open_interest.long_open_interest"),
+        shortOpenInterestUsd: dec(oi.short_open_interest, "open_interest.short_open_interest"),
+        funding: funding(r.funding, contractType),
+        baseSpreadBps: r.base_spread_bps === undefined ? null : dec(r.base_spread_bps, "base_spread_bps"),
+        quotes: quotes(r.quotes),
+        assetClass: cls.assetClass,
+        canonical: cls.canonical,
+    };
+}
+/**
+ * Parse the stats payload. A non-object payload / missing listings array is EXCHANGE_ERROR; a
+ * single malformed or unclassifiable listing is dropped with a warning naming it (never guessed).
+ */
+export function parseVariationalStats(body, warn) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        throw variationalShapeError("payload is not an object");
+    const listings = body.listings;
+    if (!Array.isArray(listings))
+        throw variationalShapeError("payload has no listings array");
+    const out = [];
+    const dropped = [];
+    const seen = new Set();
+    for (const raw of listings) {
+        const ticker = typeof raw?.ticker === "string" ? raw.ticker : "?";
+        try {
+            const l = parseListing(raw);
+            if ("skip" in l) {
+                dropped.push(`${ticker} (${l.skip})`);
+                continue;
+            }
+            if (seen.has(l.symbol)) {
+                dropped.push(`${ticker} (listed twice)`);
+                continue;
+            }
+            seen.add(l.symbol);
+            out.push(l);
+        }
+        catch (e) {
+            if (!(e instanceof RowError))
+                throw e;
+            dropped.push(`${ticker} (${e.message})`);
+        }
+    }
+    if (dropped.length > 0)
+        warnOnce(warn, `[variational] dropped ${dropped.length} listing(s): ${dropped.join(", ")}`);
+    return out;
+}
+// ── Funding ──
+/** interval_rate agrees with annualized_rate × interval / 365 d (both published, both rounded). */
+export function perpRateConsistent(rate, intervalSeconds) {
+    const interval = Number(rate.interval);
+    const expected = Number(rate.annualized) * intervalSeconds / YEAR_SECONDS;
+    return Math.abs(interval - expected) <= Math.max(RATE_IDENTITY_ABS_TOL, Math.abs(expected) * RATE_IDENTITY_REL_TOL);
+}
+/** Basis of one perp's interval_rate: perHours(interval_seconds / 3600). */
+export function fundingBasisOf(f) {
+    return { kind: "perHours", hours: f.intervalSeconds / 3600 };
+}
+/**
+ * The current (predicted) funding rate per interval, or null: swaps (no single rate), no funding
+ * terms, or a perp whose two published representations disagree (unit drift — warned).
+ */
+export function currentPerpRate(l, warn) {
+    const f = l.funding;
+    if (f === null || f.kind !== "perpetual")
+        return null;
+    if (!perpRateConsistent(f.last, f.intervalSeconds)) {
+        warnOnce(warn, `[variational] ${l.ticker}: interval_rate ${f.last.interval} disagrees with annualized_rate ${f.last.annualized} over ${f.intervalSeconds}s — funding not shown`);
+        return null;
+    }
+    return f.last.interval;
+}
+function clientFor(net) {
+    return new VariationalClient(networkConfig(variationalVenue, net).restUrl, variationalVenue.rateLimit); // testnet → NOT_IMPLEMENTED
+}
+const DEFAULT_DEPS = {
+    stats: net => clientFor(net).stats(),
+    cache: { get: key => getCached(key), set: (key, value, ttl) => setCached(key, value, ttl) },
+    warn: msg => process.stderr.write(`${msg}\n`),
+};
+const inflight = new Map();
+export const statsCacheKey = (net) => `pub:variational:${net}:stats`;
+/**
+ * The raw stats body: from the cache when fresh, else ONE request shared by every concurrent
+ * caller in this process. Only the raw JSON body is cached (JSON-safe); parsing runs per read.
+ */
+export function fetchVariationalStatsRaw(net, deps = DEFAULT_DEPS) {
+    const key = statsCacheKey(net);
+    const pending = inflight.get(key);
+    if (pending !== undefined)
+        return pending;
+    const p = (async () => {
+        const hit = deps.cache.get(key);
+        if (hit !== null && hit !== undefined)
+            return hit;
+        const body = await deps.stats(net);
+        // Only a body of the documented shape is shared; drift fails this read and is never cached.
+        if (!Array.isArray(body?.listings))
+            throw variationalShapeError("payload has no listings array");
+        deps.cache.set(key, body, VARIATIONAL_STATS_TTL_MS);
+        return body;
+    })().finally(() => { inflight.delete(key); });
+    inflight.set(key, p);
+    return p;
+}
+export async function fetchVariationalListings(net, deps = DEFAULT_DEPS) {
+    return parseVariationalStats(await fetchVariationalStatsRaw(net, deps), deps.warn);
+}
+// ── Mapping ──
+/** null when the listing has no funding terms (its interval — part of VenueMarket — is unknown). */
+export function toVariationalVenueMarket(l, warn) {
+    if (l.funding === null)
+        return null;
+    return {
+        venue: "variational",
+        venueSymbol: l.ticker,
+        symbol: l.symbol,
+        canonical: l.canonical,
+        assetClass: l.assetClass,
+        settle: "USDC",
+        quoteAsset: "USDC",
+        markPrice: l.markPrice,
+        // No index / oracle price is published.
+        indexPrice: null,
+        fundingRate: currentPerpRate(l, warn),
+        fundingRateBasis: fundingBasisOf(l.funding),
+        settlementIntervalHours: l.funding.intervalSeconds / 3600,
+        // Published in USD and single-sided only; base-unit OI is unknown.
+        openInterest: null,
+        volume24h: l.volume24h,
+        tickSize: null,
+        stepSize: null,
+        minSize: null,
+        minNotional: null,
+        maxLeverage: null,
+        marginTiers: null,
+        session: null,
+        // Quotes are omitted while a market is closed: no quote → not tradable right now.
+        tradable: l.quotes !== null && l.quotes.tiers.length > 0,
+    };
+}
+export async function fetchVariationalMarkets(net, deps = DEFAULT_DEPS) {
+    const out = [];
+    const noFunding = [];
+    for (const l of await fetchVariationalListings(net, deps)) {
+        const m = toVariationalVenueMarket(l, deps.warn);
+        if (m === null)
+            noFunding.push(l.ticker);
+        else
+            out.push(m);
+    }
+    if (noFunding.length > 0)
+        warnOnce(deps.warn, `[variational] ${noFunding.length} market(s) publish no funding terms (interval unknown) and are not shown here: ${noFunding.join(", ")}`);
+    return out;
+}
+export async function fetchVariationalFundingRates(net, deps = DEFAULT_DEPS) {
+    const out = [];
+    for (const l of await fetchVariationalListings(net, deps)) {
+        const m = toVariationalVenueMarket(l, deps.warn);
+        if (m === null || !m.tradable || m.fundingRate === null || l.funding === null)
+            continue;
+        out.push({
+            venue: "variational",
+            venueSymbol: m.venueSymbol,
+            symbol: m.symbol,
+            canonical: m.canonical,
+            rate: m.fundingRate,
+            basis: m.fundingRateBasis,
+            markPrice: m.markPrice,
+            nextFundingTime: l.funding.nextFundingTime,
+        });
+    }
+    return out;
+}
+export const variationalPublicData = {
+    fetchMarkets: net => fetchVariationalMarkets(net),
+    fetchFundingRates: net => fetchVariationalFundingRates(net),
+};
+/** Resolve a CLI symbol ("btc", "BTC-PERP", "xau-swap") against the parsed listings. */
+export function resolveVariationalListing(listings, input) {
+    const up = input.trim().toUpperCase();
+    const hit = listings.find(l => l.ticker === up || l.symbol === up);
+    if (hit === undefined)
+        throw symbolNotFound("variational", input, `Variational has no listed market ${input}`);
+    return hit;
+}

package/dist/exchanges/venue-types.d.ts

@@ -1,13 +1,13 @@
 /**
- * Venue-level data contracts (docs/DESIGN-venue-abstraction.md §10).
+ * Venue-level data contracts.
  *
  * SSOT Rule #2: every "unknown" value is `T | null`, never optional, never a
  * silently substituted default.
  */
-import type { ExchangeMarketInfo } from "./interface.js";
+import type { ExchangeMarketInfo, FundingRateKind } from "./interface.js";
 import type { ResolvedSlippage, SlippageSource } from "./slippage.js";
 import type { AppliedBuilderFee } from "./builder-fee.js";
-export type VenueId = "pacifica" | "hyperliquid" | "lighter" | "aster" | "lighter-rh" | "ondo" | "arcus" | "qfex";
+export type VenueId = "pacifica" | "hyperliquid" | "lighter" | "aster" | "lighter-rh" | "ondo" | "arcus" | "qfex" | "risex" | "txflow" | "variational" | "grvt" | "extended";
 export type LegacyVenueId = "pacifica" | "hyperliquid" | "lighter" | "aster";
 export declare const VENUE_IDS: readonly VenueId[];
 export declare const LEGACY_VENUE_IDS: readonly LegacyVenueId[];
@@ -23,7 +23,12 @@ export type FundingRateBasis = {
 };
 /** Convert a raw quoted rate to a per-hour rate. */
 export declare function rateToHourly(rate: number, basis: FundingRateBasis): number;
-export type AssetClass = "crypto" | "equity" | "index" | "etf" | "commodity" | "fx" | "preIpo";
+/**
+ * "unclassified": listed, but its class is ambiguous (a ticker that names different instruments
+ * on different venues: SPX6900 vs the S&P 500, Pacifica BP / CHIP, Lighter BB / BOT / WEN / QNT,
+ * Lighter RH USELESS). Its canonical is always null, so it is never matched across venues.
+ */
+export type AssetClass = "crypto" | "equity" | "index" | "etf" | "commodity" | "fx" | "preIpo" | "unclassified";
 export interface MarketSession {
     /** Whether the underlying (e.g. US equity) market is open right now. */
     underlyingOpen: boolean;
@@ -48,7 +53,7 @@ export interface VenueMarket {
     /**
      * Currency prices are quoted in ("USD", "KRW", ...); null = this venue's data path does not
      * record it. A non-USD quote is never traded through perp-cli (sizing, risk limits and
-     * notionals assume USD) — see QFEX, design §14.12 #7.
+     * notionals assume USD) — see QFEX,.
      */
     quoteAsset: string | null;
     markPrice: string;
@@ -73,7 +78,18 @@ export interface VenueMarket {
     session: MarketSession | null;
     /** false = listed but not tradable right now (offline / paused / corporate action). */
     tradable: boolean;
+    /**
+     * The venue's listing status as the CLI market row shows it (Extended "ACTIVE" / "REDUCE_ONLY",
+     * Ondo "active" / …, QFEX "active" / "nonUsdQuote"); absent = the venue states none.
+     */
+    status?: string | null;
 }
+/**
+ * Quantity decimals of a lot step, or null when the step is not a power of ten ≤ 1 ("0.001" → 3,
+ * "1" → 0; TxFlow "10" / "100" and a "0.5" step → null): a decimals count cannot express them, and
+ * 0 next to stepSize "10" read as "any integer". `stepSize` is the authoritative grid.
+ */
+export declare function decimalsOf(step: string): number | null;
 /** Pure mapping used by new-venue adapters to serve the legacy getMarkets(). */
 /** Tick/step/leverage required for order entry. Throws when the venue did not publish them. */
 export declare function requireTradingPrecision(m: VenueMarket): {
@@ -81,16 +97,35 @@ export declare function requireTradingPrecision(m: VenueMarket): {
     stepSize: string;
     maxLeverage: number;
 };
+export declare function fundingRateKindOf(venue: VenueMarket["venue"], fundingRate: string | null): FundingRateKind | null;
+/**
+ * THE market-row shape (`perp market list` / `info` / `prices`, ExchangeMarketInfo) of a
+ * VenueMarket — the one mapper for the CLI adapters of VenueMarket venues and the keyless MCP
+ * `get_markets` public directory rows. It does not require trading precision: a public row
+ * without a published tick / lot / leverage maps those to null.
+ */
+export declare function venueMarketRow(m: VenueMarket): ExchangeMarketInfo & {
+    tradable: boolean;
+    quoteAsset: string | null;
+    status: string | null;
+};
+/** venueMarketRow for an adapter that trades the market: tick / lot / leverage must be published. */
 export declare function toLegacyMarketInfo(m: VenueMarket): ExchangeMarketInfo;
 export interface VenueFundingRate {
     venue: VenueId;
     venueSymbol: string;
     symbol: string;
     canonical: string | null;
-    rate: string;
+    /** null = no funding right now (`marketClosed` true: outside the market's funding hours). */
+    rate: string | null;
     basis: FundingRateBasis;
     markPrice: string | null;
     nextFundingTime: number | null;
+    /**
+     * true = the current funding window is outside the market's funding hours (QFEX market_hours):
+     * `rate` is null — the venue's 0 is "no funding", not a 0 rate. Absent = funds around the clock.
+     */
+    marketClosed?: boolean;
 }
 /** CLI-level TIF inputs. "TOB" = Pacifica top-of-book, "GTX" = Aster post-only. */
 export type TimeInForce = "GTC" | "GTT" | "IOC" | "FOK" | "ALO" | "TOB" | "GTX";
@@ -111,7 +146,7 @@ export interface OrderRequest {
     /** Required when the venue's orderAck is "async". */
     clientOrderId: string | null;
     /**
-     * Resolved slippage bound (resolveSlippage(), design §13.10 #1). Required for
+     * Resolved slippage bound (resolveSlippage()). Required for
      * type "market"; adapters whose stopMarket / TP-SL legs are protection-priced
      * (Arcus) require it there too. null only for orders that carry no market leg.
      */
@@ -138,13 +173,12 @@ export interface OrderResult {
     /** Filled base size; null = the venue response does not report it (never "0" as a stand-in). */
     filledSize: string | null;
     avgPrice: string | null;
-    /** How the venue adapter actually executed the request (design §13.1 #3, §13.10 #14). */
+    /** How the venue adapter actually executed the request. */
     execution: OrderExecution;
     venueRaw: unknown;
 }
 /**
- * Transparent record of the venue-specific handling behind a uniform order
- * (design §13.1 #3, §13.2, §13.10 #14). Every field is required; a value the
+ * Transparent record of the venue-specific handling behind a uniform order. Every field is required; a value the
  * venue / adapter did not report is null (SSOT Rule #2), never a guess.
  */
 export interface OrderExecution {
@@ -229,3 +263,11 @@ export interface LeverageResult {
 export declare function orderRefOf(r: Pick<OrderResult, "orderId" | "clientOrderId">): OrderRef;
 /** Parse a CLI order reference: "c:<id>" → clientOrderId, otherwise orderId. */
 export declare function parseOrderRef(s: string): OrderRef;
+/**
+ * Next funding settlement of a venue that documents hourly settlement on the hour (UTC): the next
+ * top of the hour after `now`. Used only where the venue's docs say so — Hyperliquid ("paid every
+ * hour"), Lighter ("at each hour mark"), Pacifica ("at the end of each 1-hour interval") — and
+ * their settled history is stamped on the hour (live 2026-10-19: HL 18:00:00.139 … 21:00:00.032,
+ * Pacifica 18:00:02.674 … 21:00:02.574). Other venues keep null unless they publish the time.
+ */
+export declare function nextTopOfHourMs(now?: number): number;