perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/txflow/client.js

@@ -0,0 +1,153 @@
+/**
+ * TxFlow transport — UNOFFICIAL API (see venues/txflow.ts).
+ *
+ *  - REST: `POST <rest>/info` with an HL-style `{type, ...}` body. Errors come back three ways and
+ *    are all checked: a non-2xx status (403 "This action is not allowed." = the read is not on the
+ *    venue's allowlist), HTTP 200 with a `{message}` body, or a body of an unexpected shape.
+ *    There is no fallback for a refused read (no HL-endpoint substitution, no guessing).
+ *  - WS one-shot: open → subscribe `allAssetCtxs` → first data frame → close (bulk mark / funding
+ *    snapshot). The socket factory is injectable for tests.
+ */
+import WebSocket from "ws";
+import { PerpError, extractErrorMessage } from "../../errors.js";
+import { acquireRate, rateLimitedError } from "../rate-limiter.js";
+export const TXFLOW_HTTP_TIMEOUT_MS = 15_000;
+export const TXFLOW_WS_SNAPSHOT_TIMEOUT_MS = 10_000;
+const UNOFFICIAL_REMEDIATION = (type) => `TxFlow's unofficial API refused "${type}"; perp-cli cannot read this until it is updated (TxFlow has no official API yet)`;
+/** Shape drift in the unofficial API: an explicit EXCHANGE_ERROR, never a guessed value. */
+export function txflowShapeError(what) {
+    return new PerpError("EXCHANGE_ERROR", `TxFlow unofficial API shape changed: ${what}`, {
+        exchange: "txflow",
+        remediation: "TxFlow's undocumented API changed; perp-cli needs an update to read it. TxFlow data is unavailable until then",
+    });
+}
+function isMessageOnly(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return false;
+    const keys = Object.keys(body);
+    return keys.length === 1 && keys[0] === "message" && typeof body.message === "string";
+}
+export class TxflowClient {
+    restUrl;
+    rateLimit;
+    constructor(restUrl, rateLimit) {
+        this.restUrl = restUrl;
+        this.rateLimit = rateLimit;
+    }
+    /** POST /info. Returns the parsed body; every error path is a PerpError. */
+    async info(body) {
+        await acquireRate("txflow", this.rateLimit, body.type);
+        let res;
+        try {
+            res = await fetch(`${this.restUrl}/info`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(TXFLOW_HTTP_TIMEOUT_MS),
+            });
+        }
+        catch (e) {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `TxFlow ${body.type}: ${extractErrorMessage(e)}`, { exchange: "txflow" });
+        }
+        const text = await res.text().catch((e) => {
+            throw new PerpError("EXCHANGE_UNREACHABLE", `TxFlow ${body.type}: response body unreadable (${extractErrorMessage(e)})`, { exchange: "txflow" });
+        });
+        if (res.status === 429)
+            throw rateLimitedError("txflow", res.headers.get("retry-after"), text);
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (res.status === 403) {
+            throw new PerpError("EXCHANGE_ERROR", `TxFlow ${body.type}: HTTP 403 ${isMessageOnly(parsed) ? parsed.message : text.slice(0, 200)}`, {
+                exchange: "txflow", status: 403, remediation: UNOFFICIAL_REMEDIATION(body.type),
+            });
+        }
+        if (!res.ok) {
+            throw new PerpError("EXCHANGE_ERROR", `TxFlow ${body.type}: HTTP ${res.status} ${text.slice(0, 200)}`, {
+                exchange: "txflow", status: res.status, remediation: UNOFFICIAL_REMEDIATION(body.type),
+            });
+        }
+        if (parsed === undefined)
+            throw txflowShapeError(`${body.type} returned a non-JSON body`);
+        // HTTP 200 with {message} is an error on this API ("Orderbook for coin '…' not found").
+        if (isMessageOnly(parsed)) {
+            throw new PerpError("EXCHANGE_ERROR", `TxFlow ${body.type}: ${parsed.message}`, {
+                exchange: "txflow", remediation: UNOFFICIAL_REMEDIATION(body.type),
+            });
+        }
+        return parsed;
+    }
+}
+export const defaultWsFactory = url => new WebSocket(url, { handshakeTimeout: TXFLOW_WS_SNAPSHOT_TIMEOUT_MS });
+/**
+ * Open the socket, subscribe to `allAssetCtxs`, resolve with the first data frame's `ctxs`, close.
+ * No frame within the timeout (or a socket error / close first) → EXCHANGE_UNREACHABLE; a frame
+ * of an unexpected shape → EXCHANGE_ERROR (shape drift).
+ */
+export function fetchAllAssetCtxsOnce(wsUrl, factory = defaultWsFactory, timeoutMs = TXFLOW_WS_SNAPSHOT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        let done = false;
+        let ws;
+        const finish = (err, value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                ws.close();
+            }
+            catch { /* already closed */ }
+            if (err !== null)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const timer = setTimeout(() => finish(new PerpError("EXCHANGE_UNREACHABLE", `TxFlow allAssetCtxs snapshot: no data within ${timeoutMs / 1000}s`, { exchange: "txflow" })), timeoutMs);
+        try {
+            ws = factory(wsUrl);
+        }
+        catch (e) {
+            clearTimeout(timer);
+            reject(new PerpError("EXCHANGE_UNREACHABLE", `TxFlow WebSocket: ${extractErrorMessage(e)}`, { exchange: "txflow" }));
+            return;
+        }
+        ws.on("open", () => {
+            try {
+                ws.send(JSON.stringify({ method: "subscribe", type: "allAssetCtxs", subscription: { type: "allAssetCtxs" } }));
+            }
+            catch (e) {
+                finish(new PerpError("EXCHANGE_UNREACHABLE", `TxFlow WebSocket subscribe failed: ${extractErrorMessage(e)}`, { exchange: "txflow" }));
+            }
+        });
+        ws.on("error", e => finish(new PerpError("EXCHANGE_UNREACHABLE", `TxFlow WebSocket: ${extractErrorMessage(e)}`, { exchange: "txflow" })));
+        ws.on("close", code => finish(new PerpError("EXCHANGE_UNREACHABLE", `TxFlow WebSocket closed (code ${code}) before a snapshot arrived`, { exchange: "txflow" })));
+        ws.on("message", raw => {
+            let msg;
+            try {
+                msg = JSON.parse(String(raw));
+            }
+            catch {
+                return finish(txflowShapeError("WebSocket frame is not JSON"));
+            }
+            if (msg === null || typeof msg !== "object")
+                return finish(txflowShapeError("WebSocket frame is not an object"));
+            const m = msg;
+            if (m.channel !== "allAssetCtxs")
+                return; // pong / subscription acks / other channels
+            const ctxs = m.data?.ctxs;
+            if (!Array.isArray(ctxs))
+                return finish(txflowShapeError("allAssetCtxs frame has no ctxs array"));
+            for (const c of ctxs) {
+                if (c === null || typeof c !== "object" || typeof c.coin !== "string"
+                    || c.ctx === null || typeof c.ctx !== "object") {
+                    return finish(txflowShapeError("allAssetCtxs entry without coin / ctx"));
+                }
+            }
+            finish(null, ctxs);
+        });
+    });
+}

package/dist/exchanges/txflow/public.d.ts

@@ -0,0 +1,76 @@
+/**
+ * TxFlow public market data — UNOFFICIAL API (see venues/txflow.ts).
+ *
+ * Sources:
+ *   POST /info {type:"perpMeta", dex:""}   market directory: index (numeric coin id, with gaps),
+ *                                         name "BTC-USDC", baseCurrency, szDecimals (can be
+ *                                         NEGATIVE: lot 10, 100 …), priceTick, maxLeverage,
+ *                                         haltTrading, delisted, tagIds
+ *   WS allAssetCtxs (one-shot snapshot)   per coin: markPx, oraclePx, funding, openInterest,
+ *                                         nextFundingTime, prevFundingTime. `coin` == perpMeta
+ *                                         `index` (as a string) — joined by id, never by position.
+ *
+ * Funding: `funding` is PERCENT per hour (settlementIntervalMs 3600000 on every market; 0.00125 is
+ * the HL-style 0.00125 %/h baseline). Converted to a fraction per hour by an exact two-place decimal
+ * shift (no float maths). The value moves every tick: an accruing / predicted estimate, not a
+ * settled print — the venue is fundingVerified false. A market whose next − prev funding time is
+ * not one hour gets no funding row.
+ */
+import type { VenuePublicData } from "../venue.js";
+import type { AssetClass, FundingRateBasis, Network, VenueFundingRate, VenueMarket } from "../venue-types.js";
+import { TxflowClient, type TxflowRawAssetCtx, type WsFactory } from "./client.js";
+export declare const TXFLOW_FUNDING_BASIS: FundingRateBasis;
+export declare const TXFLOW_SETTLEMENT_MS = 3600000;
+/** perpMeta tag id of the TradFi (equity / commodity / ETF) markets. */
+export declare const TXFLOW_TRADFI_TAG = 5;
+export interface TxflowMarketMeta {
+    /** Numeric coin id (perpMeta `index`); its decimal string is the wire id and venueSymbol. */
+    index: number;
+    name: string;
+    symbol: string;
+    quote: string;
+    tickSize: string;
+    stepSize: string;
+    maxLeverage: number;
+    halted: boolean;
+    tagIds: number[];
+    assetClass: AssetClass;
+    canonical: string | null;
+}
+/** Lot step from szDecimals, exactly: 4 → "0.0001", 0 → "1", -2 → "100". */
+export declare function stepFromSzDecimals(sz: number): string;
+/** Exact percent → fraction (two-place decimal shift on the string; "0.00125" → "0.0000125"). */
+export declare function percentToFraction(pct: string): string;
+/** Parse one perpMeta row; shape drift is EXCHANGE_ERROR. Returns null for a delisted market. */
+export declare function toTxflowMarketMeta(raw: unknown): TxflowMarketMeta | null;
+export declare function fetchTxflowDirectory(client: TxflowClient): Promise<TxflowMarketMeta[]>;
+export interface TxflowCtx {
+    markPx: string;
+    oraclePx: string | null;
+    /** Percent per hour, as published; null when absent. */
+    fundingPct: string | null;
+    openInterest: string | null;
+    nextFundingTime: number | null;
+    prevFundingTime: number | null;
+}
+/**
+ * Join snapshot entries to the directory by coin id. An entry whose coin id is not a listed
+ * market is dropped with a warning (never matched by position); an entry without a mark price
+ * is dropped too (a market row needs one).
+ */
+export declare function joinSnapshot(dir: readonly TxflowMarketMeta[], ctxs: readonly TxflowRawAssetCtx[], warn: (msg: string) => void): Map<number, TxflowCtx>;
+/**
+ * Hourly funding fraction for one ctx, or null (unknown) when the rate is absent or the one-hour
+ * interval cannot be PROVEN from next − prev funding time (a missing time is unknown, never assumed 1h).
+ */
+export declare function hourlyFundingOf(ctx: TxflowCtx): string | null;
+export declare function toTxflowVenueMarket(m: TxflowMarketMeta, ctx: TxflowCtx): VenueMarket;
+export interface TxflowPublicDeps {
+    wsFactory: WsFactory;
+    warn: (msg: string) => void;
+}
+export declare function fetchTxflowMarkets(net: Network, deps?: TxflowPublicDeps): Promise<VenueMarket[]>;
+export declare function fetchTxflowFundingRates(net: Network, deps?: TxflowPublicDeps): Promise<VenueFundingRate[]>;
+export declare const txflowPublicData: VenuePublicData;
+/** Resolve a CLI symbol ("btc", "BTC-USDC", "BTC-PERP", or the numeric coin id) against the directory. */
+export declare function resolveTxflowMarket(dir: readonly TxflowMarketMeta[], input: string): TxflowMarketMeta;

package/dist/exchanges/txflow/public.js

@@ -0,0 +1,284 @@
+/**
+ * TxFlow public market data — UNOFFICIAL API (see venues/txflow.ts).
+ *
+ * Sources:
+ *   POST /info {type:"perpMeta", dex:""}   market directory: index (numeric coin id, with gaps),
+ *                                         name "BTC-USDC", baseCurrency, szDecimals (can be
+ *                                         NEGATIVE: lot 10, 100 …), priceTick, maxLeverage,
+ *                                         haltTrading, delisted, tagIds
+ *   WS allAssetCtxs (one-shot snapshot)   per coin: markPx, oraclePx, funding, openInterest,
+ *                                         nextFundingTime, prevFundingTime. `coin` == perpMeta
+ *                                         `index` (as a string) — joined by id, never by position.
+ *
+ * Funding: `funding` is PERCENT per hour (settlementIntervalMs 3600000 on every market; 0.00125 is
+ * the HL-style 0.00125 %/h baseline). Converted to a fraction per hour by an exact two-place decimal
+ * shift (no float maths). The value moves every tick: an accruing / predicted estimate, not a
+ * settled print — the venue is fundingVerified false. A market whose next − prev funding time is
+ * not one hour gets no funding row.
+ */
+import { PerpError } from "../../errors.js";
+import { canonicalFor } from "../canonical-symbols.js";
+import { networkConfig } from "../venue.js";
+import { txflowVenue } from "../venues/txflow.js";
+import { fetchAllAssetCtxsOnce, txflowShapeError, TxflowClient, defaultWsFactory } from "./client.js";
+export const TXFLOW_FUNDING_BASIS = { kind: "perHours", hours: 1 };
+export const TXFLOW_SETTLEMENT_MS = 3_600_000;
+/** perpMeta tag id of the TradFi (equity / commodity / ETF) markets. */
+export const TXFLOW_TRADFI_TAG = 5;
+/**
+ * TradFi markets by class. Equities are matched by ticker identity; commodities / ETFs / pre-IPO only
+ * through EXPLICIT_CANONICAL. A TradFi market missing here is listed as equity with NO canonical
+ * symbol (never matched across venues) until it is classified.
+ */
+const TRADFI_CLASS = {
+    XAU: "commodity", XAG: "commodity", XPD: "commodity", XPT: "commodity", CL: "commodity", BZ: "commodity",
+    SPY: "etf", QQQ: "etf", EWJ: "etf", SOXL: "etf", URNM: "etf", UVXY: "etf",
+    SPCX: "preIpo",
+    MSTR: "equity", CRCL: "equity", TSLA: "equity", COIN: "equity", HOOD: "equity", META: "equity", MU: "equity",
+    AAPL: "equity", AMZN: "equity", GOOGL: "equity", INTC: "equity", NVDA: "equity", PLTR: "equity", SNDK: "equity",
+    TSM: "equity", MSFT: "equity", AMD: "equity", LITE: "equity", AVGO: "equity", CRWV: "equity", QCOM: "equity",
+    ARM: "equity", LRCX: "equity", SKHYNIX: "equity", SAMSUNG: "equity", STXX: "equity",
+};
+/** Lot step from szDecimals, exactly: 4 → "0.0001", 0 → "1", -2 → "100". */
+export function stepFromSzDecimals(sz) {
+    if (!Number.isInteger(sz))
+        throw txflowShapeError(`szDecimals ${sz} is not an integer`);
+    if (sz > 0)
+        return `0.${"0".repeat(sz - 1)}1`;
+    return `1${"0".repeat(-sz)}`;
+}
+/** Exact percent → fraction (two-place decimal shift on the string; "0.00125" → "0.0000125"). */
+export function percentToFraction(pct) {
+    const s = pct.trim();
+    if (!/^-?\d+(\.\d+)?$/.test(s))
+        throw txflowShapeError(`funding "${pct}" is not a plain decimal`);
+    const neg = s.startsWith("-");
+    const body = neg ? s.slice(1) : s;
+    const [ip, fp = ""] = body.split(".");
+    const digits = `${ip}${fp}`;
+    const scale = fp.length + 2;
+    const padded = digits.padStart(scale + 1, "0");
+    let out = `${padded.slice(0, padded.length - scale)}.${padded.slice(padded.length - scale)}`;
+    out = out.replace(/0+$/, "").replace(/\.$/, "");
+    out = out.replace(/^0+(?=\d)/, "");
+    if (/^0(\.0*)?$/.test(out) || out === "")
+        return "0";
+    return neg ? `-${out}` : out;
+}
+function assetClassOf(symbol, tagIds) {
+    if (!tagIds.includes(TXFLOW_TRADFI_TAG))
+        return "crypto";
+    return TRADFI_CLASS[symbol] ?? "equity";
+}
+function canonicalOf(symbol, tagIds, assetClass) {
+    // An unclassified TradFi market is never matched across venues.
+    if (tagIds.includes(TXFLOW_TRADFI_TAG) && TRADFI_CLASS[symbol] === undefined)
+        return null;
+    return canonicalFor("txflow", symbol, assetClass);
+}
+/** Parse one perpMeta row; shape drift is EXCHANGE_ERROR. Returns null for a delisted market. */
+export function toTxflowMarketMeta(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw txflowShapeError("perpMeta universe row is not an object");
+    const r = raw;
+    if (typeof r.index !== "number" || !Number.isInteger(r.index) || r.index < 0)
+        throw txflowShapeError(`perpMeta row ${String(r.name)} has a non-numeric index`);
+    if (typeof r.name !== "string" || typeof r.baseCurrency !== "string" || r.baseCurrency === "")
+        throw txflowShapeError(`perpMeta row ${r.index} has no name / baseCurrency`);
+    if (typeof r.quoteCurrency !== "string")
+        throw txflowShapeError(`perpMeta ${r.name} has no quoteCurrency`);
+    if (typeof r.szDecimals !== "number")
+        throw txflowShapeError(`perpMeta ${r.name} has no szDecimals`);
+    if (typeof r.priceTick !== "string" || !/^\d+(\.\d+)?$/.test(r.priceTick) || !(Number(r.priceTick) > 0))
+        throw txflowShapeError(`perpMeta ${r.name} has no valid priceTick`);
+    if (typeof r.maxLeverage !== "number" || !(r.maxLeverage > 0))
+        throw txflowShapeError(`perpMeta ${r.name} has no maxLeverage`);
+    if (typeof r.haltTrading !== "boolean" || typeof r.delisted !== "boolean")
+        throw txflowShapeError(`perpMeta ${r.name} has no haltTrading / delisted flags`);
+    if (!Array.isArray(r.tagIds) || r.tagIds.some(t => typeof t !== "number"))
+        throw txflowShapeError(`perpMeta ${r.name} has no tagIds`);
+    if (r.delisted)
+        return null;
+    const symbol = r.baseCurrency.toUpperCase();
+    const tagIds = r.tagIds;
+    const assetClass = assetClassOf(symbol, tagIds);
+    return {
+        index: r.index,
+        name: r.name,
+        symbol,
+        quote: r.quoteCurrency,
+        tickSize: r.priceTick,
+        stepSize: stepFromSzDecimals(r.szDecimals),
+        maxLeverage: r.maxLeverage,
+        halted: r.haltTrading,
+        tagIds,
+        assetClass,
+        canonical: canonicalOf(symbol, tagIds, assetClass),
+    };
+}
+export async function fetchTxflowDirectory(client) {
+    const res = await client.info({ type: "perpMeta", dex: "" });
+    if (res === null || typeof res !== "object" || !Array.isArray(res.universe))
+        throw txflowShapeError("perpMeta has no universe array");
+    const out = [];
+    const seen = new Set();
+    for (const row of res.universe) {
+        const m = toTxflowMarketMeta(row);
+        if (m === null)
+            continue;
+        if (seen.has(m.symbol))
+            throw txflowShapeError(`perpMeta lists ${m.symbol} twice`);
+        seen.add(m.symbol);
+        out.push(m);
+    }
+    return out;
+}
+function decOrNull(v) {
+    return typeof v === "string" && /^-?\d+(\.\d+)?$/.test(v) ? v : null;
+}
+function msOrNull(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
+}
+/**
+ * Join snapshot entries to the directory by coin id. An entry whose coin id is not a listed
+ * market is dropped with a warning (never matched by position); an entry without a mark price
+ * is dropped too (a market row needs one).
+ */
+export function joinSnapshot(dir, ctxs, warn) {
+    const byIndex = new Map(dir.map(m => [String(m.index), m]));
+    const out = new Map();
+    const unknown = [];
+    const unpriced = [];
+    for (const { coin, ctx } of ctxs) {
+        const meta = byIndex.get(coin);
+        if (meta === undefined) {
+            unknown.push(coin);
+            continue;
+        }
+        const markPx = decOrNull(ctx.markPx);
+        if (markPx === null || !(Number(markPx) > 0)) {
+            unpriced.push(meta.symbol);
+            continue;
+        }
+        out.set(meta.index, {
+            markPx,
+            oraclePx: decOrNull(ctx.oraclePx),
+            fundingPct: decOrNull(ctx.funding),
+            openInterest: decOrNull(ctx.openInterest),
+            nextFundingTime: msOrNull(ctx.nextFundingTime),
+            prevFundingTime: msOrNull(ctx.prevFundingTime),
+        });
+    }
+    if (unknown.length > 0)
+        warn(`[txflow] dropped ${unknown.length} snapshot entr${unknown.length === 1 ? "y" : "ies"} for unknown coin id(s): ${unknown.join(", ")}`);
+    if (unpriced.length > 0)
+        warn(`[txflow] dropped ${unpriced.length} snapshot entr${unpriced.length === 1 ? "y" : "ies"} without a mark price: ${unpriced.join(", ")}`);
+    return out;
+}
+/**
+ * Hourly funding fraction for one ctx, or null (unknown) when the rate is absent or the one-hour
+ * interval cannot be PROVEN from next − prev funding time (a missing time is unknown, never assumed 1h).
+ */
+export function hourlyFundingOf(ctx) {
+    if (ctx.fundingPct === null)
+        return null;
+    if (ctx.nextFundingTime === null || ctx.prevFundingTime === null)
+        return null;
+    if (ctx.nextFundingTime - ctx.prevFundingTime !== TXFLOW_SETTLEMENT_MS)
+        return null;
+    return percentToFraction(ctx.fundingPct);
+}
+// ── Mapping ──
+export function toTxflowVenueMarket(m, ctx) {
+    return {
+        venue: "txflow",
+        venueSymbol: String(m.index),
+        symbol: m.symbol,
+        canonical: m.canonical,
+        assetClass: m.assetClass,
+        settle: "USDC",
+        quoteAsset: m.quote,
+        markPrice: ctx.markPx,
+        indexPrice: ctx.oraclePx,
+        fundingRate: hourlyFundingOf(ctx),
+        fundingRateBasis: TXFLOW_FUNDING_BASIS,
+        settlementIntervalHours: 1,
+        // Base units (as Hyperliquid publishes it) [inferred].
+        openInterest: ctx.openInterest,
+        volume24h: null,
+        tickSize: m.tickSize,
+        stepSize: m.stepSize,
+        minSize: null,
+        minNotional: null,
+        maxLeverage: m.maxLeverage,
+        marginTiers: null,
+        session: null,
+        tradable: !m.halted,
+    };
+}
+const DEFAULT_DEPS = {
+    wsFactory: defaultWsFactory,
+    warn: msg => process.stderr.write(`${msg}\n`),
+};
+function clientFor(net) {
+    const cfg = networkConfig(txflowVenue, net); // testnet → NOT_IMPLEMENTED (no testnet)
+    if (cfg.wsUrl === null)
+        throw new Error("txflow venue definition has no wsUrl");
+    return { client: new TxflowClient(cfg.restUrl, txflowVenue.rateLimit), wsUrl: cfg.wsUrl };
+}
+/** Directory + one snapshot, joined; markets missing from the snapshot are dropped with a warning. */
+async function fetchJoined(net, deps) {
+    const { client, wsUrl } = clientFor(net);
+    const [dir, ctxs] = await Promise.all([fetchTxflowDirectory(client), fetchAllAssetCtxsOnce(wsUrl, deps.wsFactory)]);
+    const joined = joinSnapshot(dir, ctxs, deps.warn);
+    const out = [];
+    const missing = [];
+    for (const meta of dir) {
+        const ctx = joined.get(meta.index);
+        if (ctx === undefined) {
+            missing.push(meta.symbol);
+            continue;
+        }
+        out.push({ meta, ctx });
+    }
+    if (missing.length > 0)
+        deps.warn(`[txflow] ${missing.length} listed market(s) had no snapshot entry and are not shown: ${missing.join(", ")}`);
+    return out;
+}
+export async function fetchTxflowMarkets(net, deps = DEFAULT_DEPS) {
+    return (await fetchJoined(net, deps)).map(({ meta, ctx }) => toTxflowVenueMarket(meta, ctx));
+}
+export async function fetchTxflowFundingRates(net, deps = DEFAULT_DEPS) {
+    const out = [];
+    for (const { meta, ctx } of await fetchJoined(net, deps)) {
+        const rate = hourlyFundingOf(ctx);
+        if (rate === null)
+            continue;
+        out.push({
+            venue: "txflow",
+            venueSymbol: String(meta.index),
+            symbol: meta.symbol,
+            canonical: meta.canonical,
+            rate,
+            basis: TXFLOW_FUNDING_BASIS,
+            markPrice: ctx.markPx,
+            nextFundingTime: ctx.nextFundingTime,
+        });
+    }
+    return out;
+}
+export const txflowPublicData = {
+    fetchMarkets: net => fetchTxflowMarkets(net),
+    fetchFundingRates: net => fetchTxflowFundingRates(net),
+};
+/** Resolve a CLI symbol ("btc", "BTC-USDC", "BTC-PERP", or the numeric coin id) against the directory. */
+export function resolveTxflowMarket(dir, input) {
+    const up = input.trim().toUpperCase().replace(/-PERP$/, "");
+    const hit = dir.find(m => m.symbol === up || m.name.toUpperCase() === up || String(m.index) === up);
+    if (hit === undefined) {
+        throw new PerpError("SYMBOL_NOT_FOUND", `TxFlow has no listed market ${input}`, {
+            exchange: "txflow", remediation: "List markets: perp -e txflow market list",
+        });
+    }
+    return hit;
+}

package/dist/exchanges/unknown-symbol.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Unknown-symbol handling shared by the adapters' public market-data reads.
+ *
+ * Several venues answer a read for a market they do not list with an empty success
+ * (Pacifica /trades, /kline, /funding_rate/history; Ondo /v1/perps/trades and candles; Aster
+ * /fapi/v3/fundingRate — all `200 []`, live 2026-10-14). An empty list must not stand for
+ * "no such market": after an empty answer the symbol is checked against the venue's own market
+ * directory (getMarkets) — SYMBOL_NOT_FOUND when it is not listed, the empty list when it is
+ * (a listed market with no trades / candles in the window is a real empty result).
+ */
+import { PerpError } from "../errors.js";
+import type { ExchangeMarketInfo } from "./interface.js";
+/** SYMBOL_NOT_FOUND for `symbol` on `venue`, with the listing command as remediation. */
+export declare function symbolNotFound(venue: string, symbol: string, message?: string): PerpError;
+/** Directory match: case-insensitive, a "-PERP" display suffix ignored on either side. */
+export declare function listsSymbol(markets: readonly Pick<ExchangeMarketInfo, "symbol">[], symbol: string): boolean;
+/**
+ * `rows` as returned by the venue, unless they are empty and the market is not in the venue's
+ * market directory — then SYMBOL_NOT_FOUND. The directory is read only for an empty answer.
+ *
+ * `directorySymbol` is the symbol in the directory's form, derived by the adapter from what the
+ * user typed (Ondo "TSLA-USD.P" → "TSLA", Aster "BTCUSDT" → "BTC"); `symbol` is kept for messages.
+ * A failed directory read is re-thrown with its code (and so its retryable flag), saying what was
+ * being checked — never turned into SYMBOL_NOT_FOUND or an empty result.
+ */
+export declare function nonEmptyOrListed<T>(adapter: {
+    readonly name: string;
+    getMarkets(): Promise<Pick<ExchangeMarketInfo, "symbol">[]>;
+}, symbol: string, rows: T[], directorySymbol?: string): Promise<T[]>;

package/dist/exchanges/unknown-symbol.js

@@ -0,0 +1,51 @@
+/**
+ * Unknown-symbol handling shared by the adapters' public market-data reads.
+ *
+ * Several venues answer a read for a market they do not list with an empty success
+ * (Pacifica /trades, /kline, /funding_rate/history; Ondo /v1/perps/trades and candles; Aster
+ * /fapi/v3/fundingRate — all `200 []`, live 2026-10-14). An empty list must not stand for
+ * "no such market": after an empty answer the symbol is checked against the venue's own market
+ * directory (getMarkets) — SYMBOL_NOT_FOUND when it is not listed, the empty list when it is
+ * (a listed market with no trades / candles in the window is a real empty result).
+ */
+import { PerpError, classifyError } from "../errors.js";
+/** SYMBOL_NOT_FOUND for `symbol` on `venue`, with the listing command as remediation. */
+export function symbolNotFound(venue, symbol, message) {
+    return new PerpError("SYMBOL_NOT_FOUND", message ?? `${venue} has no market ${symbol.toUpperCase()}`, {
+        exchange: venue,
+        remediation: `List markets: perp -e ${venue} market list`,
+    });
+}
+/** Directory match: case-insensitive, a "-PERP" display suffix ignored on either side. */
+export function listsSymbol(markets, symbol) {
+    const norm = (s) => s.toUpperCase().replace(/-PERP$/, "");
+    const want = norm(symbol);
+    return markets.some(m => norm(m.symbol) === want);
+}
+/**
+ * `rows` as returned by the venue, unless they are empty and the market is not in the venue's
+ * market directory — then SYMBOL_NOT_FOUND. The directory is read only for an empty answer.
+ *
+ * `directorySymbol` is the symbol in the directory's form, derived by the adapter from what the
+ * user typed (Ondo "TSLA-USD.P" → "TSLA", Aster "BTCUSDT" → "BTC"); `symbol` is kept for messages.
+ * A failed directory read is re-thrown with its code (and so its retryable flag), saying what was
+ * being checked — never turned into SYMBOL_NOT_FOUND or an empty result.
+ */
+export async function nonEmptyOrListed(adapter, symbol, rows, directorySymbol = symbol) {
+    if (rows.length > 0)
+        return rows;
+    let markets;
+    try {
+        markets = await adapter.getMarkets();
+    }
+    catch (e) {
+        const c = classifyError(e, adapter.name);
+        throw new PerpError(c.code, `${adapter.name}: ${symbol} returned no rows and the market list could not be read to check the symbol — ${c.message}`, {
+            exchange: adapter.name,
+            ...(c.remediation !== undefined ? { remediation: c.remediation } : {}),
+        });
+    }
+    if (!listsSymbol(markets, directorySymbol))
+        throw symbolNotFound(adapter.name, symbol);
+    return rows;
+}

package/dist/exchanges/variational/adapter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Variational public-only adapter — OFFICIAL read-only API (venues/variational.ts).
+ *
+ * Markets, current funding terms and the OLP's indicative RFQ quotes come from the one stats
+ * payload (variational/public.ts). Variational is an RFQ venue with a single maker, so there is no
+ * order book, trade tape or candle feed in the API: getOrderbook / getRecentTrades / getKlines /
+ * getFundingHistory refuse with CAPABILITY_UNSUPPORTED (with the command that does work), and every
+ * account / trading method refuses before any request.
+ */
+import type { CurrentFundingTerms, RfqQuotes, ExchangeAdapter, ExchangeBalance, ExchangeFundingPayment, ExchangeKline, ExchangeMarketInfo, ExchangeOrder, ExchangePosition, ExchangeTrade, ExchangePublicTrade } from "../interface.js";
+import { type VenueDefinition } from "../venue.js";
+import { type Network } from "../venue-types.js";
+import { type VariationalSwapRate } from "./public.js";
+/** Legacy market row plus the Variational-only fields every row carries in JSON output. */
+export type VariationalMarketInfo = ExchangeMarketInfo & {
+    venueApi: "official";
+    ticker: string;
+    contractType: "perpetual" | "swap";
+    name: string | null;
+    /** "predicted" for a perpetual with a rate; null otherwise. */
+    fundingRateKind: "predicted" | null;
+    nextFundingTime: number | null;
+    /** USDC, single-sided (trader positions only; the OLP is the counterparty). */
+    openInterestUsd: {
+        long: string;
+        short: string;
+    };
+    swapFunding: {
+        last: VariationalSwapRate | null;
+        next: VariationalSwapRate | null;
+    } | null;
+};
+export declare class VariationalPublicAdapter implements ExchangeAdapter {
+    readonly venue: VenueDefinition;
+    readonly network: Network;
+    readonly name: "variational";
+    readonly aliases: readonly ["var", "omni"];
+    constructor(venue: VenueDefinition, network: Network);
+    private warn;
+    private listing;
+    getMarkets(): Promise<VariationalMarketInfo[]>;
+    /** Current funding terms of one market (the API publishes no funding history). */
+    getFundingTerms(symbol: string): Promise<CurrentFundingTerms>;
+    /** The OLP's indicative RFQ quotes (Variational has no order book). */
+    getRfqQuotes(symbol: string): Promise<RfqQuotes>;
+    getOrderbook(): Promise<{
+        bids: [string, string][];
+        asks: [string, string][];
+    }>;
+    getRecentTrades(): Promise<ExchangePublicTrade[]>;
+    getFundingHistory(): Promise<{
+        time: number;
+        rate: string;
+        price: string | null;
+    }[]>;
+    getKlines(): Promise<ExchangeKline[]>;
+    private refuse;
+    getBalance(): Promise<ExchangeBalance>;
+    getPositions(): Promise<ExchangePosition[]>;
+    getOpenOrders(): Promise<ExchangeOrder[]>;
+    getOrderHistory(): Promise<ExchangeOrder[]>;
+    getTradeHistory(): Promise<ExchangeTrade[]>;
+    getFundingPayments(): Promise<ExchangeFundingPayment[]>;
+    marketOrder(): Promise<unknown>;
+    limitOrder(): Promise<unknown>;
+    editOrder(): Promise<unknown>;
+    cancelOrder(): Promise<unknown>;
+    cancelAllOrders(): Promise<unknown>;
+    setLeverage(): Promise<unknown>;
+    stopOrder(): Promise<unknown>;
+}