perp-cli 0.14.2 → 0.15.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,5 +1,5 @@
 /**
- * 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.
@@ -7,7 +7,7 @@
 import type { ExchangeMarketInfo } 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[];
@@ -48,7 +48,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;
@@ -111,7 +111,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 +138,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 {

package/dist/exchanges/venue-types.js

@@ -1,12 +1,12 @@
 /**
- * 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.
  */
 export const VENUE_IDS = [
     "pacifica", "hyperliquid", "lighter", "aster",
-    "lighter-rh", "ondo", "arcus", "qfex",
+    "lighter-rh", "ondo", "arcus", "qfex", "risex", "txflow", "variational", "grvt", "extended",
 ];
 export const LEGACY_VENUE_IDS = ["pacifica", "hyperliquid", "lighter", "aster"];
 export function isVenueId(s) {

package/dist/exchanges/venue.d.ts

@@ -2,12 +2,13 @@
  * Venue definitions — the single source of truth for "which venue, on which
  * network, signed how, funded how, supporting what".
  *
- * See docs/DESIGN-venue-abstraction.md §10. One adapter class may serve several
+ * One adapter class may serve several
  * venues (LighterAdapter serves `lighter` and `lighter-rh`).
  *
  * Venue definition modules must load adapter code lazily (`import()` inside
  * `create`) so that public-data paths never pull in heavy SDKs (lighter WASM).
  */
+import { PerpError } from "../errors.js";
 import type { ExchangeAdapter } from "./interface.js";
 import type { SpotAdapter } from "./spot-interface.js";
 import type { FundingRateBasis, LegacyVenueId, Network, TimeInForce, VenueFundingRate, VenueId, VenueMarket } from "./venue-types.js";
@@ -127,11 +128,29 @@ export interface VenueCreateContext {
 export declare const READ_ONLY_CREDENTIALS: VenueCredentials;
 export type VenueRole = "marketData" | "account" | "trading";
 export type SymbolIdentity = "baseTicker" | "explicit";
+/**
+ * How perp-cli reaches the venue. "official" = a documented public API. "unofficial" = an
+ * undocumented API (e.g. the one the venue's own web app uses) that may change or be blocked
+ * without notice; every user-facing surface (JSON `venueApi` / `apiStatus`, human footnotes,
+ * MCP output, the landing screen, the skill docs) labels data read through it.
+ */
+export type VenueApiStatus = {
+    kind: "official";
+} | {
+    kind: "unofficial";
+    note: string;
+    docs: string | null;
+};
+export declare const OFFICIAL_API: VenueApiStatus;
+/** "official" | "unofficial" — the per-row label for mixed-venue tables and JSON. */
+export declare function apiStatusOf(venue: VenueId): VenueApiStatus["kind"];
+/** Human footnote for an unofficial-API venue; null for an official one. */
+export declare function unofficialApiNote(def: VenueDefinition): string | null;
 export interface VenueDefinition {
     id: VenueId;
     aliases: readonly string[];
     displayName: string;
-    family: "pacifica" | "hyperliquid" | "lighter" | "aster" | "ondo" | "arcus" | "qfex";
+    family: "pacifica" | "hyperliquid" | "lighter" | "aster" | "ondo" | "arcus" | "qfex" | "risex" | "txflow" | "variational" | "grvt" | "extended";
     masterKeyKind: MasterKeyKind;
     agentKeyKind: AgentKeyKind;
     secretStorage: SecretStorage;
@@ -143,12 +162,22 @@ export interface VenueDefinition {
     settlementIntervalHours: number | "perMarket";
     /**
      * false = the unit / meaning of the venue's published funding rate is not verified against
-     * settled funding payments yet (design §14.12 #6). Such a venue is left out of cross-venue
+     * settled funding payments yet. Such a venue is left out of cross-venue
      * funding comparison (fetchVenuesRates drops it unless includeUnverified is passed), its
      * adapter reports fundingRate null to bots, and funding-arb strategies refuse it as a leg.
      */
     fundingVerified: boolean;
     roles: readonly VenueRole[];
+    /**
+     * Roles that are implemented but switched off in this release (phased venue rollout, e.g.
+     * RISEx trading in 0.15.0). They are NOT in `roles`; roleUnsupported() uses `reason` /
+     * `remediation` for them. null = nothing held back.
+     */
+    gatedRoles: {
+        roles: readonly VenueRole[];
+        reason: string;
+        remediation: string;
+    } | null;
     /** null when the venue has no trading role. */
     capabilities: VenueCapabilities | null;
     rateLimit: RateLimitPolicy;
@@ -159,11 +188,10 @@ export interface VenueDefinition {
     publicData: VenuePublicData;
     /** null when the venue cannot produce an adapter (public data only). */
     create: ((ctx: VenueCreateContext) => Promise<ExchangeAdapter>) | null;
-    /** null = venue has no spot trading (§12). */
+    /** null = venue has no spot trading. */
     spot: VenueSpotDefinition | null;
     /**
-     * Largest slippage bound (bps) a market-type order may carry on this venue
-     * (design §13.10 #1). resolveSlippage() rejects anything above it with
+     * Largest slippage bound (bps) a market-type order may carry on this venue. resolveSlippage() rejects anything above it with
      * INVALID_PARAMS before sending — never clamps.
      */
     maxSlippageBps: number;
@@ -173,6 +201,13 @@ export interface VenueDefinition {
      * settings.builder.<venue> and the approval is confirmed.
      */
     builderFee: BuilderFeeCapability | null;
+    /** Official documented API, or an unofficial one that is labelled everywhere (VenueApiStatus). */
+    apiStatus: VenueApiStatus;
+    /**
+     * Remediation of every role refusal (roleUnsupported) on a venue that is read-only in this
+     * version (Variational, GRVT, Extended). Absent = the generic market-data-only remediation.
+     */
+    readOnlyRemediation?: string;
 }
 export declare function registerVenue(def: VenueDefinition): void;
 /** Resolve a venue id or alias. Throws UNKNOWN_VENUE. */
@@ -182,6 +217,14 @@ export declare function getVenue(nameOrAlias: string): VenueDefinition;
 export declare function listVenues(): VenueDefinition[];
 export declare function listVenuesWithRole(role: VenueRole): VenueDefinition[];
 export declare function networkConfig(def: VenueDefinition, net: Network): VenueNetworkConfig;
+/**
+ * The uniform refusal for any account / trading / funds / agent / builder / bot action on a venue
+ * whose roles do not include `role` (a market-data-only venue such as TxFlow). Raised before any
+ * credential is resolved or any request is sent.
+ */
+export declare function roleUnsupported(def: VenueDefinition, feature: string, role?: VenueRole): PerpError;
+/** Throws roleUnsupported() unless the venue has `role`. */
+export declare function requireRole(def: VenueDefinition, role: VenueRole, feature: string): void;
 export declare function requireCapabilities(def: VenueDefinition): VenueCapabilities;
 /**
  * A venue reference as it appears in stored data and funding keys:
@@ -194,7 +237,7 @@ export interface VenueRef {
 export declare function parseVenueRef(ref: string): VenueRef;
 /**
  * Funding basis for a venue ref. HIP-3 dexes use the Hyperliquid core basis
- * (current behavior preserved; see design §10.1 — verify against live data).
+ * (current behavior preserved; verify against live data).
  * Throws for venues whose basis is per-market; callers must use the market's value.
  */
 export declare function fundingBasisOf(ref: string): FundingRateBasis;
@@ -202,7 +245,7 @@ export declare function settlementIntervalOf(ref: string): number;
 /**
  * Refuse a venue whose funding rate is unverified (VenueDefinition.fundingVerified false) as a
  * leg of a funding strategy (arb scan ranking, arb exec / auto, funding bots). Uniform
- * CAPABILITY_UNSUPPORTED (design §13.6, §14.12 #6). Unknown venue refs throw UNKNOWN_VENUE.
+ * CAPABILITY_UNSUPPORTED. Unknown venue refs throw UNKNOWN_VENUE.
  */
 export declare function assertFundingArbVenue(ref: string): void;
 export declare function isLegacyVenue(def: VenueDefinition): def is VenueDefinition & {