perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/risex/units.d.ts

@@ -0,0 +1,29 @@
+/**
+ * RISEx unit conversions — all exact (BigInt / string), never float maths.
+ *
+ *  - WAD: on-chain style 1e18-scaled integers (`/v1/positions` size / prices, IOC
+ *    `filled_quantity`) → plain decimal strings.
+ *  - ns: every RISEx timestamp and `funding_interval` is in NANOseconds → ms.
+ *  - steps / ticks: orders are sent as integers — size_steps = size / step_size (uint32),
+ *    price_ticks = price / step_price (uint24, max 16 777 215). Off-grid values are refused,
+ *    never rounded.
+ */
+export declare const UINT24_MAX = 16777215n;
+export declare const UINT32_MAX = 4294967295n;
+export declare const UINT64_MAX = 18446744073709551615n;
+/** 1e18-scaled integer string ("1143307000000000000", "-2905…") → decimal string ("1.143307"). */
+export declare function wadToDecimal(wad: string): string;
+/** Nanosecond decimal string → unix ms (integer division; exact for ms-aligned values). */
+export declare function nsToMs(ns: string | number): number;
+/** ns timestamp or null for "0" / "" / absent (RISEx sends "0" for "no value"). */
+export declare function nsToMsOrNull(ns: unknown): number | null;
+/** Integer size in steps; refused when off the step grid, zero, or above uint32. */
+export declare function toSizeSteps(size: string, stepSize: string): bigint;
+/** Integer price in ticks; refused (INVALID_TICK) when off-grid, INVALID_PARAMS when above uint24. */
+export declare function toPriceTicks(price: string, stepPrice: string): bigint;
+/** A RISEx decimal field, or null when absent / empty (RISEx sends "" for "not set"). */
+export declare function decOrNull(v: unknown): string | null;
+/** Exact comparison of two plain decimal strings: -1 | 0 | 1. */
+export declare function compareDecimal(a: string, b: string): -1 | 0 | 1;
+/** Strip trailing zeros of a plain decimal ("83425.5900" → "83425.59"). */
+export declare function trimDecimal(s: string): string;

package/dist/exchanges/risex/units.js

@@ -0,0 +1,104 @@
+/**
+ * RISEx unit conversions — all exact (BigInt / string), never float maths.
+ *
+ *  - WAD: on-chain style 1e18-scaled integers (`/v1/positions` size / prices, IOC
+ *    `filled_quantity`) → plain decimal strings.
+ *  - ns: every RISEx timestamp and `funding_interval` is in NANOseconds → ms.
+ *  - steps / ticks: orders are sent as integers — size_steps = size / step_size (uint32),
+ *    price_ticks = price / step_price (uint24, max 16 777 215). Off-grid values are refused,
+ *    never rounded.
+ */
+import { PerpError } from "../../errors.js";
+import { exactUnits } from "../precision.js";
+export const UINT24_MAX = 16777215n;
+export const UINT32_MAX = 4294967295n;
+export const UINT64_MAX = 18446744073709551615n;
+/** 1e18-scaled integer string ("1143307000000000000", "-2905…") → decimal string ("1.143307"). */
+export function wadToDecimal(wad) {
+    const s = wad.trim();
+    if (!/^-?\d+$/.test(s))
+        throw new PerpError("EXCHANGE_ERROR", `RISEx: "${wad}" is not a WAD integer`, { exchange: "risex" });
+    const neg = s.startsWith("-");
+    const digits = (neg ? s.slice(1) : s).replace(/^0+(?=\d)/, "");
+    const padded = digits.padStart(19, "0");
+    const int = padded.slice(0, padded.length - 18).replace(/^0+(?=\d)/, "");
+    const frac = padded.slice(padded.length - 18).replace(/0+$/, "");
+    const out = frac.length > 0 ? `${int}.${frac}` : int;
+    return neg && out !== "0" ? `-${out}` : out;
+}
+/** Nanosecond decimal string → unix ms (integer division; exact for ms-aligned values). */
+export function nsToMs(ns) {
+    const s = String(ns).trim();
+    if (!/^\d+$/.test(s))
+        throw new PerpError("EXCHANGE_ERROR", `RISEx: "${ns}" is not a nanosecond timestamp`, { exchange: "risex" });
+    return Number(BigInt(s) / 1000000n);
+}
+/** ns timestamp or null for "0" / "" / absent (RISEx sends "0" for "no value"). */
+export function nsToMsOrNull(ns) {
+    if (typeof ns !== "string" && typeof ns !== "number")
+        return null;
+    const s = String(ns).trim();
+    if (s === "" || s === "0")
+        return null;
+    return nsToMs(s);
+}
+/** Integer size in steps; refused when off the step grid, zero, or above uint32. */
+export function toSizeSteps(size, stepSize) {
+    const u = exactUnits(size, stepSize);
+    if (u === null) {
+        throw new PerpError("INVALID_PARAMS", `RISEx size ${size} is not a multiple of the step size ${stepSize}`, {
+            exchange: "risex", remediation: `Use a size that is a multiple of ${stepSize}`,
+        });
+    }
+    if (u <= 0n)
+        throw new PerpError("SIZE_TOO_SMALL", `RISEx size ${size} is below one step (${stepSize})`, { exchange: "risex" });
+    if (u > UINT32_MAX) {
+        throw new PerpError("SIZE_TOO_LARGE", `RISEx size ${size} is ${u} steps, above the uint32 limit`, {
+            exchange: "risex", remediation: "Split the order",
+        });
+    }
+    return u;
+}
+/** Integer price in ticks; refused (INVALID_TICK) when off-grid, INVALID_PARAMS when above uint24. */
+export function toPriceTicks(price, stepPrice) {
+    const u = exactUnits(price, stepPrice);
+    if (u === null) {
+        throw new PerpError("INVALID_TICK", `RISEx price ${price} is not a multiple of the tick ${stepPrice}`, {
+            exchange: "risex", remediation: `Use a price that is a multiple of ${stepPrice}`,
+        });
+    }
+    if (u <= 0n)
+        throw new PerpError("INVALID_PARAMS", `RISEx price ${price} must be positive`, { exchange: "risex" });
+    if (u > UINT24_MAX) {
+        throw new PerpError("INVALID_PARAMS", `RISEx price ${price} is ${u} ticks, above the uint24 order limit (${UINT24_MAX})`, { exchange: "risex" });
+    }
+    return u;
+}
+/** A RISEx decimal field, or null when absent / empty (RISEx sends "" for "not set"). */
+export function decOrNull(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim();
+    return /^-?\d+(\.\d+)?$/.test(s) ? s : null;
+}
+/** Exact comparison of two plain decimal strings: -1 | 0 | 1. */
+export function compareDecimal(a, b) {
+    const parse = (s) => {
+        if (!/^-?\d+(\.\d+)?$/.test(s))
+            throw new PerpError("EXCHANGE_ERROR", `RISEx: "${s}" is not a decimal`, { exchange: "risex" });
+        const neg = s.startsWith("-");
+        const [ip, fp = ""] = (neg ? s.slice(1) : s).split(".");
+        return { int: BigInt(ip + fp) * (neg ? -1n : 1n), scale: fp.length };
+    };
+    const x = parse(a), y = parse(b);
+    const scale = Math.max(x.scale, y.scale);
+    const xi = x.int * 10n ** BigInt(scale - x.scale), yi = y.int * 10n ** BigInt(scale - y.scale);
+    return xi < yi ? -1 : xi > yi ? 1 : 0;
+}
+/** Strip trailing zeros of a plain decimal ("83425.5900" → "83425.59"). */
+export function trimDecimal(s) {
+    if (!s.includes("."))
+        return s;
+    const out = s.replace(/0+$/, "").replace(/\.$/, "");
+    return out === "-0" ? "0" : out;
+}

package/dist/exchanges/slippage.d.ts

@@ -1,5 +1,5 @@
 /**
- * Single slippage resolver for every market-type order (design §13.2, §13.10 #1).
+ * Single slippage resolver for every market-type order.
  *
  * Precedence (all explicit configuration, no hidden constants):
  *   --slippage-bps flag → settings.slippageBps[venue] → settings.defaultSlippageBps.

package/dist/exchanges/slippage.js

@@ -1,5 +1,5 @@
 /**
- * Single slippage resolver for every market-type order (design §13.2, §13.10 #1).
+ * Single slippage resolver for every market-type order.
  *
  * Precedence (all explicit configuration, no hidden constants):
  *   --slippage-bps flag → settings.slippageBps[venue] → settings.defaultSlippageBps.

package/dist/exchanges/spot-factory.d.ts

@@ -1,5 +1,5 @@
 /**
- * Spot adapter factory — the only place spot adapters are created (design §12.4 #1).
+ * Spot adapter factory — the only place spot adapters are created.
  *
  * - `getSpotAdapter` returns null iff the venue has no spot (`def.spot === null`).
  *   Creation / init / network errors propagate (SSOT Rule #2 — no catch).
@@ -8,8 +8,8 @@
  *   so the key is the adapter's own network, not the process-wide one) and per
  *   on-chain-approve option. Read-only and signed perp adapters keep separate entries.
  *
- * Bot scope (§12.4 #3): bots only trade spot on venues where `isBotSpotVenue(def)`.
- * Quote/base detection (§12.4 #6) goes through `def.spot.quoteAssets`.
+ * Bot scope: bots only trade spot on venues where `isBotSpotVenue(def)`.
+ * Quote/base detection goes through `def.spot.quoteAssets`.
  */
 import type { AssetClass, Network, VenueMarket } from "./venue-types.js";
 import type { ExchangeAdapter } from "./interface.js";

package/dist/exchanges/spot-factory.js

@@ -1,5 +1,5 @@
 /**
- * Spot adapter factory — the only place spot adapters are created (design §12.4 #1).
+ * Spot adapter factory — the only place spot adapters are created.
  *
  * - `getSpotAdapter` returns null iff the venue has no spot (`def.spot === null`).
  *   Creation / init / network errors propagate (SSOT Rule #2 — no catch).
@@ -8,8 +8,8 @@
  *   so the key is the adapter's own network, not the process-wide one) and per
  *   on-chain-approve option. Read-only and signed perp adapters keep separate entries.
  *
- * Bot scope (§12.4 #3): bots only trade spot on venues where `isBotSpotVenue(def)`.
- * Quote/base detection (§12.4 #6) goes through `def.spot.quoteAssets`.
+ * Bot scope: bots only trade spot on venues where `isBotSpotVenue(def)`.
+ * Quote/base detection goes through `def.spot.quoteAssets`.
  */
 import { classifyError, extractErrorMessage, PerpError } from "../errors.js";
 import { unsupported } from "./trading-v2.js";
@@ -84,7 +84,7 @@ export async function requireSpotAdapter(venue, perp, opts = NO_ONCHAIN_APPROVE)
         throw new Error(`unreachable: ${venue} spot definition present but no adapter`);
     return spot;
 }
-// ── Bot scope (§12.4 #3) ──
+// ── Bot scope ──
 /**
  * Bots (funding-arb*, spot-perp-*, arb-auto, arb/index) only use spot venues with a
  * separate (or runtime-decided) spot balance and a spot↔perp transfer. Pacifica
@@ -116,7 +116,7 @@ export async function getBotSpotAdapter(name, perp) {
         return null;
     return getSpotAdapter(id, perp);
 }
-// ── Quote / base helpers (§12.4 #6) ──
+// ── Quote / base helpers ──
 /** Upper-cased token with venue balance suffixes removed ("USDC_SPOT" / "PURR-SPOT" → base). */
 export function spotTokenBase(token) {
     return token.toUpperCase().replace(/[-_]SPOT$/, "");
@@ -171,7 +171,7 @@ export function spotSharesPerpMargin(def, perp) {
  * `shared` is carried through so aggregators can skip money already in perp equity.
  */
 export function valueSpotBalances(def, net, balances, markets, warn) {
-    // markPrice null = no usable price (§12 SpotMarketInfo) → the token is excluded below.
+    // markPrice null = no usable price (SpotMarketInfo) → the token is excluded below.
     const prices = new Map(markets.flatMap(m => (m.markPrice === null ? [] : [[m.baseToken.toUpperCase(), Number(m.markPrice)]])));
     const out = [];
     for (const b of balances) {
@@ -248,7 +248,7 @@ export async function withSpotTimeout(p, what, timeoutMs = SPOT_VALUATION_TIMEOU
         clearTimeout(timer);
     }
 }
-// ── Transfers (§12.4 #4) ──
+// ── Transfers ──
 function ownerOf(spot) {
     const o = _owner.get(spot);
     if (!o)

package/dist/exchanges/spot-interface.d.ts

@@ -3,10 +3,10 @@
  * Separate from ExchangeAdapter because spot uses balance-based tracking
  * (not position-based) and has no leverage, liquidation, or funding concepts.
  *
- * Venues declare spot support in their VenueDefinition (`spot`, design §12);
+ * Venues declare spot support in their VenueDefinition (`spot`);
  * adapters are created only through `getSpotAdapter()` in spot-factory.ts.
  *
- * Symbol rule (§12.4 #6): `SpotMarketInfo.symbol` is "BASE/QUOTE". Adapter
+ * Symbol rule: `SpotMarketInfo.symbol` is "BASE/QUOTE". Adapter
  * methods accept a bare base ("ETH" → BASE/quoteAssets[0]) or "BASE/QUOTE"
  * and translate to the venue's wire form.
  */
@@ -33,11 +33,11 @@ export interface SpotBalance {
     entryNtl?: string;
     /**
      * true = this balance is the same money as the perp account (Pacifica USDC,
-     * HL unified). Aggregators must not add it on top of perp equity (§12.4 #8).
+     * HL unified). Aggregators must not add it on top of perp equity.
      */
     shared: boolean;
 }
-/** Normalized spot order result for venues added under §12 (legacy HL/Lighter return unknown). */
+/** Normalized spot order result for venue-definition spot venues (legacy HL/Lighter return unknown). */
 export interface SpotOrderResult {
     venue: string;
     symbol: string;
@@ -129,7 +129,7 @@ export interface SpotAdapter {
         asks: [string, string][];
     }>;
     getSpotBalances(): Promise<SpotBalance[]>;
-    /** Market order within the resolved slippage bound (design §13.2 — same rule as perps). */
+    /** Market order within the resolved slippage bound (same rule as perps). */
     spotMarketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
         slippage: ResolvedSlippage;
     }): Promise<unknown>;

package/dist/exchanges/spot-interface.js

@@ -3,10 +3,10 @@
  * Separate from ExchangeAdapter because spot uses balance-based tracking
  * (not position-based) and has no leverage, liquidation, or funding concepts.
  *
- * Venues declare spot support in their VenueDefinition (`spot`, design §12);
+ * Venues declare spot support in their VenueDefinition (`spot`);
  * adapters are created only through `getSpotAdapter()` in spot-factory.ts.
  *
- * Symbol rule (§12.4 #6): `SpotMarketInfo.symbol` is "BASE/QUOTE". Adapter
+ * Symbol rule: `SpotMarketInfo.symbol` is "BASE/QUOTE". Adapter
  * methods accept a bare base ("ETH" → BASE/quoteAssets[0]) or "BASE/QUOTE"
  * and translate to the venue's wire form.
  */

package/dist/exchanges/spot-result.d.ts

@@ -1,7 +1,7 @@
 /**
- * Spot order outcome → filled size, for bots / arb (design §12.4 #5).
+ * Spot order outcome → filled size, for bots / arb.
  *
- * A resolved `spotMarketOrder()` promise does NOT mean "filled": the §12 adapters
+ * A resolved `spotMarketOrder()` promise does NOT mean "filled": the adapters
  * return a `SpotOrderResult` (rejected / cancelled / pending / partial / filled),
  * and the legacy Hyperliquid / Lighter adapters return a venue payload. Every bot /
  * arb spot leg goes through `spotMarketFill()` so the hedge is sized to what
@@ -31,7 +31,7 @@
  *    zero delta is ORDER_PENDING (the IOC may still be unconfirmed), never "nothing
  *    filled"; a failed read is never zero.
  *
- * Venue-final IOC outcome (design §13.10 #4): when the spot adapter is IocOutcomeCapable
+ * Venue-final IOC outcome: when the spot adapter is IocOutcomeCapable
  * and iocOutcomeOf(result) reports the order's FINAL filled size, that report is used in
  * preference to the balance delta, cross-checked against a fresh base-balance delta:
  *  - final 0 and the balance did not move (≤ one lot) → ORDER_REJECTED (definite);

package/dist/exchanges/spot-result.js

@@ -1,7 +1,7 @@
 /**
- * Spot order outcome → filled size, for bots / arb (design §12.4 #5).
+ * Spot order outcome → filled size, for bots / arb.
  *
- * A resolved `spotMarketOrder()` promise does NOT mean "filled": the §12 adapters
+ * A resolved `spotMarketOrder()` promise does NOT mean "filled": the adapters
  * return a `SpotOrderResult` (rejected / cancelled / pending / partial / filled),
  * and the legacy Hyperliquid / Lighter adapters return a venue payload. Every bot /
  * arb spot leg goes through `spotMarketFill()` so the hedge is sized to what
@@ -31,7 +31,7 @@
  *    zero delta is ORDER_PENDING (the IOC may still be unconfirmed), never "nothing
  *    filled"; a failed read is never zero.
  *
- * Venue-final IOC outcome (design §13.10 #4): when the spot adapter is IocOutcomeCapable
+ * Venue-final IOC outcome: when the spot adapter is IocOutcomeCapable
  * and iocOutcomeOf(result) reports the order's FINAL filled size, that report is used in
  * preference to the balance delta, cross-checked against a fresh base-balance delta:
  *  - final 0 and the balance did not move (≤ one lot) → ORDER_REJECTED (definite);

package/dist/exchanges/trading-v2.d.ts

@@ -1,6 +1,6 @@
 /**
  * TradingV2 — normalized order entry for venues added under the venue
- * abstraction (docs/DESIGN-venue-abstraction.md §3 L3, §10.7, §10.10).
+ * abstraction.
  *
  * Method names deliberately do not overlap the legacy ExchangeAdapter trading
  * methods, so an adapter can implement both without overloads.
@@ -26,7 +26,7 @@ export interface TradingV2 extends VenueMarketsSource {
 }
 export declare function isTradingV2(a: unknown): a is TradingV2;
 /**
- * Uniform "not supported" response (design §13.6, §13.10 #13): CAPABILITY_UNSUPPORTED
+ * Uniform "not supported" response: CAPABILITY_UNSUPPORTED
  * with details { venue, feature, reason } and an alternative in `remediation`.
  * `venue` is a venue id or display name; `feature` a short capability name
  * ("limitOrder", "fok", "postOnly", "amend", "trading", "orderbook", ...).
@@ -72,7 +72,7 @@ export declare function validateOrderRequest(venue: VenueDefinition, caps: Venue
 /**
  * Resolve a CLI TIF input (common GTC/IOC/FOK/ALO or a venue alias GTT/GTX/TOB,
  * case-insensitive) to a value the venue declares in its capabilities. Never
- * substitutes a different meaning: FOK is never emulated (§13.3) and an
+ * substitutes a different meaning: FOK is never emulated and an
  * unknown / unoffered value is the uniform CAPABILITY_UNSUPPORTED response.
  */
 export declare function validateLegacyTif(venue: VenueDefinition, caps: VenueCapabilities, tif: string): TimeInForce;

package/dist/exchanges/trading-v2.js

@@ -1,6 +1,6 @@
 /**
  * TradingV2 — normalized order entry for venues added under the venue
- * abstraction (docs/DESIGN-venue-abstraction.md §3 L3, §10.7, §10.10).
+ * abstraction.
  *
  * Method names deliberately do not overlap the legacy ExchangeAdapter trading
  * methods, so an adapter can implement both without overloads.
@@ -18,7 +18,7 @@ export function isTradingV2(a) {
         && typeof r.getVenueMarkets === "function";
 }
 /**
- * Uniform "not supported" response (design §13.6, §13.10 #13): CAPABILITY_UNSUPPORTED
+ * Uniform "not supported" response: CAPABILITY_UNSUPPORTED
  * with details { venue, feature, reason } and an alternative in `remediation`.
  * `venue` is a venue id or display name; `feature` a short capability name
  * ("limitOrder", "fok", "postOnly", "amend", "trading", "orderbook", ...).
@@ -113,7 +113,7 @@ export function validateOrderRequest(venue, caps, req) {
         requirePositive(req.price, "price");
     if (req.triggerPrice !== null)
         requirePositive(req.triggerPrice, "triggerPrice");
-    // Callers resolve the common default (GTC, design §13.3) before building the request;
+    // Callers resolve the common default (GTC) before building the request;
     // a missing TIF here is a programming error, never a user-facing TIF_REQUIRED.
     if (needsPrice && req.tif === null) {
         throw new PerpError("INVALID_PARAMS", `${venue.displayName} ${req.type} order is missing its resolved time-in-force`);
@@ -132,7 +132,7 @@ export function validateOrderRequest(venue, caps, req) {
         const alternative = `set a take-profit / stop-loss on the position instead: perp trade tpsl ${req.symbol} <long|short> --tp <price>${caps.tpsl !== null && caps.tpsl !== "positionLevel" ? " [--size <qty>]" : ""} -e ${venue.id}`;
         throw unsupported(venue.displayName, "restingReduceOnly", `a reduce-only limit order can only be ${caps.reduceOnlyTif.join(" / ")} (got ${req.tif})`, `Use --tif ${caps.reduceOnlyTif.join(" | ")}, or ${alternative}`);
     }
-    // Callers always pass resolveSlippage() output for market orders (§13.10 #1); a
+    // Callers always pass resolveSlippage() output for market orders; a
     // missing bound here is a programming error, never "send unbounded".
     if (req.type === "market" && req.slippage === null) {
         throw new PerpError("INVALID_PARAMS", `${venue.displayName} market order is missing its resolved slippage bound`);
@@ -159,7 +159,7 @@ export function validateOrderRequest(venue, caps, req) {
     }
 }
 /**
- * Common TIF aliases (design §13.3): a common name the venue lists under its own
+ * Common TIF aliases: a common name the venue lists under its own
  * spelling, and venue spellings accepted for the common name. Only same-meaning
  * pairs: GTC ↔ GTT (resting until cancelled / venue expiry), ALO ↔ GTX (post-only).
  */
@@ -172,7 +172,7 @@ const TIF_ALIASES = {
 /**
  * Resolve a CLI TIF input (common GTC/IOC/FOK/ALO or a venue alias GTT/GTX/TOB,
  * case-insensitive) to a value the venue declares in its capabilities. Never
- * substitutes a different meaning: FOK is never emulated (§13.3) and an
+ * substitutes a different meaning: FOK is never emulated and an
  * unknown / unoffered value is the uniform CAPABILITY_UNSUPPORTED response.
  */
 export function validateLegacyTif(venue, caps, tif) {
@@ -250,6 +250,9 @@ export function newVenueClientOrderId(venue) {
         return randomUUID();
     if (venue.family === "hyperliquid")
         return `0x${randomBytes(16).toString("hex")}`;
+    // RISEx: uint64 decimal — ms timestamp × 1e6 + 6 random digits (< 2^64).
+    if (venue.family === "risex")
+        return (BigInt(Date.now()) * 1000000n + BigInt(randomBytes(4).readUInt32BE(0) % 1_000_000)).toString();
     return newClientOrderId();
 }
 /** Finality wait after an async (orderAck "async") placement ack. */

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

@@ -0,0 +1,54 @@
+/**
+ * TxFlow public-only adapter — UNOFFICIAL read-only API (see venues/txflow.ts).
+ *
+ * Market data (markets, orderbook, trades, klines) is implemented. Funding history is not
+ * readable (the unofficial API refuses it) and every account / trading method refuses with
+ * CAPABILITY_UNSUPPORTED before any request — there is no TxFlow account or order code.
+ */
+import type { ExchangeAdapter, ExchangeBalance, ExchangeFundingPayment, ExchangeKline, ExchangeMarketInfo, ExchangeOrder, ExchangePosition, ExchangeTrade, ExchangePublicTrade } from "../interface.js";
+import { type VenueDefinition } from "../venue.js";
+import { type Network, type VenueMarket } from "../venue-types.js";
+/** Candle intervals the TxFlow app requests (HL-style). */
+export declare const TXFLOW_KLINE_INTERVALS: ReadonlySet<string>;
+/** Legacy market row plus the labels every TxFlow row carries in JSON output. */
+export type TxflowMarketInfo = ExchangeMarketInfo & {
+    venueApi: "unofficial";
+    fundingVerified: false;
+};
+export declare class TxflowPublicAdapter implements ExchangeAdapter {
+    readonly venue: VenueDefinition;
+    readonly network: Network;
+    readonly name: "txflow";
+    readonly aliases: readonly ["txf"];
+    private readonly client;
+    private dir;
+    constructor(venue: VenueDefinition, network: Network);
+    private market;
+    getVenueMarkets(): Promise<VenueMarket[]>;
+    getMarkets(): Promise<TxflowMarketInfo[]>;
+    getOrderbook(symbol: string): Promise<{
+        bids: [string, string][];
+        asks: [string, string][];
+    }>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
+    getFundingHistory(): Promise<{
+        time: number;
+        rate: string;
+        price: string | null;
+    }[]>;
+    getKlines(symbol: string, interval: string, startTime: number, endTime: number): 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>;
+}

package/dist/exchanges/txflow/adapter.js

@@ -0,0 +1,118 @@
+/**
+ * TxFlow public-only adapter — UNOFFICIAL read-only API (see venues/txflow.ts).
+ *
+ * Market data (markets, orderbook, trades, klines) is implemented. Funding history is not
+ * readable (the unofficial API refuses it) and every account / trading method refuses with
+ * CAPABILITY_UNSUPPORTED before any request — there is no TxFlow account or order code.
+ */
+import { PerpError } from "../../errors.js";
+import { unsupported } from "../trading-v2.js";
+import { roleUnsupported, networkConfig } from "../venue.js";
+import { toLegacyMarketInfo } from "../venue-types.js";
+import { txflowShapeError, TxflowClient } from "./client.js";
+import { fetchTxflowDirectory, fetchTxflowMarkets, resolveTxflowMarket } from "./public.js";
+/** Candle intervals the TxFlow app requests (HL-style). */
+export const TXFLOW_KLINE_INTERVALS = new Set(["1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "8h", "12h", "1d", "3d", "1w", "1M"]);
+function dec(v, what) {
+    if (typeof v !== "string" || !/^-?\d+(\.\d+)?$/.test(v))
+        throw txflowShapeError(`${what} is not a decimal string`);
+    return v;
+}
+export class TxflowPublicAdapter {
+    venue;
+    network;
+    name = "txflow";
+    aliases = ["txf"];
+    client;
+    dir = null;
+    constructor(venue, network) {
+        this.venue = venue;
+        this.network = network;
+        this.client = new TxflowClient(networkConfig(venue, network).restUrl, venue.rateLimit);
+    }
+    async market(symbol) {
+        if (this.dir === null) {
+            this.dir = fetchTxflowDirectory(this.client);
+            this.dir.catch(() => { this.dir = null; });
+        }
+        return resolveTxflowMarket(await this.dir, symbol);
+    }
+    // ── Market data ──
+    async getVenueMarkets() {
+        return fetchTxflowMarkets(this.network);
+    }
+    async getMarkets() {
+        return (await this.getVenueMarkets()).map(m => ({ ...toLegacyMarketInfo(m), venueApi: "unofficial", fundingVerified: false }));
+    }
+    async getOrderbook(symbol) {
+        const m = await this.market(symbol);
+        const res = await this.client.info({ type: "l2Book", coin: String(m.index) });
+        const levels = res?.levels;
+        if (!Array.isArray(levels) || levels.length !== 2 || !Array.isArray(levels[0]) || !Array.isArray(levels[1])) {
+            throw txflowShapeError("l2Book has no [bids, asks] levels");
+        }
+        const side = (rows) => rows.map(r => {
+            const x = r;
+            return [dec(x.px, "l2Book px"), dec(x.sz, "l2Book sz")];
+        });
+        return { bids: side(levels[0]), asks: side(levels[1]) };
+    }
+    async getRecentTrades(symbol, limit = 50) {
+        const m = await this.market(symbol);
+        const res = await this.client.info({ type: "trades", coin: String(m.index) });
+        if (!Array.isArray(res))
+            throw txflowShapeError("trades is not an array");
+        return res.slice(0, limit).map(t => {
+            const x = t;
+            if (x.side !== "B" && x.side !== "A")
+                throw txflowShapeError(`trade side ${String(x.side)}`);
+            if (typeof x.time !== "number")
+                throw txflowShapeError("trade without time");
+            // Public tape carries no fee; "0" follows the legacy ExchangeTrade convention for public trades.
+            return { time: x.time, symbol: m.symbol, side: x.side === "B" ? "buy" : "sell", price: dec(x.px, "trade px"), size: dec(x.sz, "trade sz"), fee: null };
+        });
+    }
+    async getFundingHistory() {
+        throw unsupported("txflow", "fundingHistory", "TxFlow's unofficial API refuses funding-history reads (HTTP 403)", "Current TxFlow funding (unverified, per hour): perp -e txflow market info <symbol>, or perp arb scan --rates --include-unverified");
+    }
+    async getKlines(symbol, interval, startTime, endTime) {
+        if (!TXFLOW_KLINE_INTERVALS.has(interval)) {
+            throw new PerpError("INVALID_PARAMS", `TxFlow: unsupported candle interval "${interval}"`, {
+                remediation: `Use one of: ${[...TXFLOW_KLINE_INTERVALS].join(", ")}`,
+            });
+        }
+        const m = await this.market(symbol);
+        const res = await this.client.info({ type: "candleSnapshot", req: { coin: String(m.index), interval, startTime, endTime } });
+        if (!Array.isArray(res))
+            throw txflowShapeError("candleSnapshot is not an array");
+        return res.map(c => {
+            const x = c;
+            if (typeof x.t !== "number")
+                throw txflowShapeError("candle without t");
+            return {
+                time: x.t,
+                open: dec(x.o, "candle o"), high: dec(x.h, "candle h"), low: dec(x.l, "candle l"), close: dec(x.c, "candle c"),
+                volume: dec(x.v, "candle v"),
+                quoteVolume: null,
+                trades: typeof x.n === "number" ? x.n : null,
+            };
+        });
+    }
+    // ── Account / trading: refused (market-data-only venue, unofficial API) ──
+    refuse(feature) {
+        throw roleUnsupported(this.venue, feature);
+    }
+    async getBalance() { return this.refuse("account"); }
+    async getPositions() { return this.refuse("account"); }
+    async getOpenOrders() { return this.refuse("account"); }
+    async getOrderHistory() { return this.refuse("account"); }
+    async getTradeHistory() { return this.refuse("account"); }
+    async getFundingPayments() { return this.refuse("account"); }
+    async marketOrder() { return this.refuse("trading"); }
+    async limitOrder() { return this.refuse("trading"); }
+    async editOrder() { return this.refuse("trading"); }
+    async cancelOrder() { return this.refuse("trading"); }
+    async cancelAllOrders() { return this.refuse("trading"); }
+    async setLeverage() { return this.refuse("trading"); }
+    async stopOrder() { return this.refuse("trading"); }
+}

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[]>;