perp-cli 0.14.3 → 0.16.0

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

@@ -0,0 +1,47 @@
+/**
+ * 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 { PerpError } from "../../errors.js";
+import type { RateLimitPolicy } from "../venue.js";
+export declare const TXFLOW_HTTP_TIMEOUT_MS = 15000;
+export declare const TXFLOW_WS_SNAPSHOT_TIMEOUT_MS = 10000;
+/** Shape drift in the unofficial API: an explicit EXCHANGE_ERROR, never a guessed value. */
+export declare function txflowShapeError(what: string): PerpError;
+export declare class TxflowClient {
+    private readonly restUrl;
+    private readonly rateLimit;
+    constructor(restUrl: string, rateLimit: RateLimitPolicy);
+    /** POST /info. Returns the parsed body; every error path is a PerpError. */
+    info<T = unknown>(body: {
+        type: string;
+    } & Record<string, unknown>): Promise<T>;
+}
+/** The subset of a `ws` WebSocket the one-shot reader uses (a fake in tests). */
+export interface WsLike {
+    on(event: "open", cb: () => void): unknown;
+    on(event: "message", cb: (data: unknown) => void): unknown;
+    on(event: "error", cb: (err: unknown) => void): unknown;
+    on(event: "close", cb: (code: number) => void): unknown;
+    send(data: string): void;
+    close(): void;
+}
+export type WsFactory = (url: string) => WsLike;
+export declare const defaultWsFactory: WsFactory;
+/** One raw `allAssetCtxs` entry: `coin` is the perpMeta `index` as a decimal string. */
+export interface TxflowRawAssetCtx {
+    coin: string;
+    ctx: Record<string, unknown>;
+}
+/**
+ * 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 declare function fetchAllAssetCtxsOnce(wsUrl: string, factory?: WsFactory, timeoutMs?: number): Promise<TxflowRawAssetCtx[]>;

package/dist/exchanges/txflow/client.js

@@ -0,0 +1,155 @@
+/**
+ * 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) {
+            // A 5xx can be a raw Cloudflare HTML page (live: candleSnapshot 1w / 3d → HTTP 500): tags stripped.
+            const clean = text.replace(/<(script|style)[\s\S]*?<\/\1>/gi, " ").replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 200);
+            throw new PerpError("EXCHANGE_ERROR", `TxFlow ${body.type}: HTTP ${res.status} ${clean}`, {
+                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,87 @@
+/**
+ * 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
+ *   POST /info {type:"allMarketTickers"}  per instrument: dayNtlVlm (24 h USD notional), prevDayPx …;
+ *                                         `instrumentId` == perpMeta `index` (spot rows ≥ 10000),
+ *                                         empty fields are "" (→ null). `market list|prices` only.
+ *   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;
+export declare function looksTxflowTradFi(symbol: string, tagIds: readonly number[], fullName: string | null, description: string | null): boolean;
+/** 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;
+/** First spot instrumentId in allMarketTickers (perp ids are the perpMeta index, below it). */
+export declare const TXFLOW_SPOT_ID_BASE = 10000;
+/**
+ * 24 h USD notional volume per perp coin id from allMarketTickers. "" (no trades) → null, never
+ * "0"; a non-list answer or a row without a numeric instrumentId is EXCHANGE_ERROR.
+ */
+export declare function fetchTxflowDayVolumes(client: TxflowClient): Promise<Map<number, string | null>>;
+export declare function toTxflowVenueMarket(m: TxflowMarketMeta, ctx: TxflowCtx, volume24h: string | null): 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,355 @@
+/**
+ * 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
+ *   POST /info {type:"allMarketTickers"}  per instrument: dayNtlVlm (24 h USD notional), prevDayPx …;
+ *                                         `instrumentId` == perpMeta `index` (spot rows ≥ 10000),
+ *                                         empty fields are "" (→ null). `market list|prices` only.
+ *   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;
+}
+/**
+ * TradFi markets listed WITHOUT the TradFi tag (live 2026-10-19: ~38 rows with `tagIds: []`, e.g.
+ * COPPER, NATGAS, MRNA, GS, PATH, TEAM, TLT, SOXS) were classed as crypto and got a crypto
+ * canonical, so arb could pair GS or PATH with same-named crypto tokens. A row is TradFi when it is
+ * tagged, its description reads like a share / ETF / commodity / FX / pre-IPO contract, its
+ * fullName reads like a company or fund (as Variational's looksTradFi), or it is one of the
+ * untagged equities whose perpMeta row has no description (UNTAGGED_TRADFI, from the live listing).
+ */
+const TRADFI_DESCRIPTION = /\b(common stock|ordinary shares|shares\b|ETF\b|Pre-IPO|exchange rate|price reference for|priced in US dollars, representing)/i;
+const TRADFI_FULLNAME = /\b(Inc|Corp|Corporation|Company|Holdings?|Ltd|Limited|plc|PBC|N\.V|Group|ETF|Shares|Currency FX|Co\.)\b\.?/i;
+const UNTAGGED_TRADFI = new Set([
+    "CRDO", "APP", "ADBE", "COST", "BX", "DKNG", "BRKB", "KO", "IBM", "QNTX", "UNH", "TWST", "CVNA", "MCD", "NKE",
+    "AAOI", "ASTS", "VST", "SNPS", "BSP",
+]);
+/** Crypto tokens whose description reads like a commodity contract (Tether Gold is a token). */
+const CRYPTO_DESPITE_DESCRIPTION = new Set(["XAUT"]);
+export function looksTxflowTradFi(symbol, tagIds, fullName, description) {
+    if (tagIds.includes(TXFLOW_TRADFI_TAG))
+        return true;
+    if (CRYPTO_DESPITE_DESCRIPTION.has(symbol))
+        return false;
+    if (description !== null && TRADFI_DESCRIPTION.test(description))
+        return true;
+    if (fullName !== null && TRADFI_FULLNAME.test(fullName))
+        return true;
+    return UNTAGGED_TRADFI.has(symbol);
+}
+/** Class of an unclassified TradFi row from its listing text (its canonical stays null either way). */
+function textClassOf(fullName, description) {
+    const text = `${fullName ?? ""} ${description ?? ""}`;
+    if (/exchange rate|Currency FX/i.test(text))
+        return "fx";
+    if (/Pre-IPO|\bPBC\b|private artificial intelligence company/i.test(text))
+        return "preIpo";
+    if (/\bETF\b|\bShares\b/.test(text))
+        return "etf";
+    if (/priced in US dollars, representing/i.test(text))
+        return "commodity";
+    return "equity";
+}
+function assetClassOf(symbol, tradFi, fullName, description) {
+    if (!tradFi)
+        return "crypto";
+    const known = TRADFI_CLASS[symbol];
+    return known !== undefined ? known : textClassOf(fullName, description);
+}
+function canonicalOf(symbol, tradFi, assetClass) {
+    // An unclassified TradFi market (tagged or not) is never matched across venues.
+    if (tradFi && 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 fullName = typeof r.fullName === "string" ? r.fullName : null;
+    const description = typeof r.description === "string" ? r.description : null;
+    const tradFi = looksTxflowTradFi(symbol, tagIds, fullName, description);
+    const assetClass = assetClassOf(symbol, tradFi, fullName, description);
+    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, tradFi, 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 ──
+/** First spot instrumentId in allMarketTickers (perp ids are the perpMeta index, below it). */
+export const TXFLOW_SPOT_ID_BASE = 10_000;
+/**
+ * 24 h USD notional volume per perp coin id from allMarketTickers. "" (no trades) → null, never
+ * "0"; a non-list answer or a row without a numeric instrumentId is EXCHANGE_ERROR.
+ */
+export async function fetchTxflowDayVolumes(client) {
+    const res = await client.info({ type: "allMarketTickers" });
+    if (!Array.isArray(res))
+        throw txflowShapeError("allMarketTickers is not an array");
+    const out = new Map();
+    for (const r of res) {
+        const x = r;
+        if (typeof x.instrumentId !== "number" || !Number.isInteger(x.instrumentId))
+            throw txflowShapeError("allMarketTickers row without a numeric instrumentId");
+        if (x.instrumentId >= TXFLOW_SPOT_ID_BASE)
+            continue;
+        out.set(x.instrumentId, decOrNull(x.dayNtlVlm));
+    }
+    return out;
+}
+export function toTxflowVenueMarket(m, ctx, volume24h) {
+    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,
+        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) {
+    const { client } = clientFor(net); // testnet → NOT_IMPLEMENTED before any request
+    const [joined, volumes] = await Promise.all([fetchJoined(net, deps), fetchTxflowDayVolumes(client)]);
+    // A market absent from allMarketTickers has no published volume → null.
+    return joined.map(({ meta, ctx }) => toTxflowVenueMarket(meta, ctx, volumes.has(meta.index) ? volumes.get(meta.index) : null));
+}
+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;
+}