perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/venues/lighter.js

@@ -1,5 +1,5 @@
 /**
- * Lighter (main) venue definition (design §10.1, §10.8, §10.13 #4).
+ * Lighter (main) venue definition.
  * Shares LighterAdapter and constants with lighter-rh (./lighter-family.ts).
  */
 import { LIGHTER_CAPABILITIES, LIGHTER_NETWORKS, LIGHTER_RATE_LIMIT } from "./lighter-family.js";
@@ -8,8 +8,17 @@ const publicData = {
     async fetchFundingRates(net) {
         return (await import("../lighter-public.js")).lighterPublicData("lighter").fetchFundingRates(net);
     },
-    async fetchMarkets(net) {
-        return (await import("../lighter-public.js")).lighterPublicData("lighter").fetchMarkets(net);
+    async fetchMarkets(net, opts) {
+        return (await import("../lighter-public.js")).lighterPublicData("lighter").fetchMarkets(net, opts);
+    },
+    // Keyless positions of any account by public address (account positions --address).
+    addressKind: "evm",
+    async fetchPositionsByAddress(net, address, opts) {
+        return (await import("../public-positions.js")).lighterPositionsByAddress("lighter", net, address, opts);
+    },
+    // Keyless balances of any account by public address (account balance --address).
+    async fetchBalanceByAddress(net, address, opts) {
+        return (await import("../public-balances.js")).lighterBalanceByAddress("lighter", net, address, opts);
     },
 };
 export const lighterVenue = {
@@ -21,17 +30,19 @@ export const lighterVenue = {
     agentKeyKind: "lighter-l2",
     secretStorage: { kind: "perp-keystore", dir: "lighter-agents" },
     networks: LIGHTER_NETWORKS,
-    fundingRateBasis: { kind: "perHours", hours: 8 },
+    // The market rows' fundingRate is the settled hourly rate (WS market_stats, lighter-public.ts).
+    fundingRateBasis: { kind: "perHours", hours: 1 },
     settlementIntervalHours: 1,
     fundingVerified: true,
     roles: ["marketData", "account", "trading"],
+    gatedRoles: null,
     capabilities: LIGHTER_CAPABILITIES,
-    // Declared only — per §10.9 the limiter is applied to new venues + lighter-rh, not lighter.
+    // Declared only — per the limiter is applied to new venues + lighter-rh, not lighter.
     rateLimit: LIGHTER_RATE_LIMIT,
     restrictedRegions: [],
     symbolIdentity: "baseTicker",
     publicData,
-    // §12: per account (account_trading_mode, read by LighterSpotAdapter.init): Unified (1) shares
+    // per account (account_trading_mode, read by LighterSpotAdapter.init): Unified (1) shares
     // the collateral between spot and perp (no transfer); Classic (0) = separate spot balance +
     // self-transfer of the venue collateral.
     spot: {
@@ -51,5 +62,6 @@ export const lighterVenue = {
     },
     maxSlippageBps: 5000,
     builderFee: BUILDER_FEE_CAPABILITIES["lighter"],
+    apiStatus: { kind: "official" },
     create: async (ctx) => (await import("./create-helpers.js")).createLighterFamily("lighter", ctx),
 };

package/dist/exchanges/venues/ondo.d.ts

@@ -1,5 +1,5 @@
 /**
- * Ondo Perps venue definition (design §4, §10).
+ * Ondo Perps venue definition.
  *
  * Off-chain matching engine; collateral is USDC plus eligible Ondo Global
  * Markets tokenized stocks (docs collateral-assets). Hot-path key = HMAC API

package/dist/exchanges/venues/ondo.js

@@ -1,5 +1,5 @@
 /**
- * Ondo Perps venue definition (design §4, §10).
+ * Ondo Perps venue definition.
  *
  * Off-chain matching engine; collateral is USDC plus eligible Ondo Global
  * Markets tokenized stocks (docs collateral-assets). Hot-path key = HMAC API
@@ -81,10 +81,11 @@ export const ondoVenue = {
     settlementIntervalHours: 1,
     fundingVerified: true,
     roles: ["marketData", "account", "trading"],
+    gatedRoles: null,
     capabilities: {
         // The venue offers native market orders; the adapter sends every market order
         // as an IOC LIMIT at the tick-aligned protection price (mark ± resolved
-        // slippage, design §13.2).
+        // slippage).
         marketOrder: "native",
         timeInForce: ["GTC", "IOC", "ALO"],
         // A reduce-only limit order must be IOC: the venue refuses a resting one with HTTP 400
@@ -107,7 +108,7 @@ export const ondoVenue = {
     restrictedRegions: ["US", "PA"],
     symbolIdentity: "baseTicker",
     publicData,
-    // §12: separate spot wallet + POST /v1/spot/transfers (spot ↔ margin).
+    // separate spot wallet + POST /v1/spot/transfers (spot ↔ margin).
     spot: {
         accountModel: "separate",
         quoteAssets: { mainnet: ["USDC"], testnet: ["USDC"] },
@@ -125,6 +126,7 @@ export const ondoVenue = {
     },
     maxSlippageBps: 5000,
     builderFee: BUILDER_FEE_CAPABILITIES["ondo"],
+    apiStatus: { kind: "official" },
     create: async (ctx) => {
         const adapter = new (await import("../ondo/adapter.js")).OndoAdapter(ondoVenue, ctx);
         // Builder code: only settings builder.ondo (off by default). Ondo has no approval step.

package/dist/exchanges/venues/pacifica.d.ts

@@ -1,6 +1,6 @@
 /**
- * Pacifica venue definition (design §10.1, §10.8, §10.13 #4).
- * Adapter + public-data code are loaded lazily (§10.10).
+ * Pacifica venue definition.
+ * Adapter + public-data code are loaded lazily.
  */
 import type { VenueDefinition } from "../venue.js";
 /** Pacifica `client_order_id` format: "Full UUID string" (docs.pacifica.fi rest-api orders/create-limit-order). */

package/dist/exchanges/venues/pacifica.js

@@ -1,6 +1,6 @@
 /**
- * Pacifica venue definition (design §10.1, §10.8, §10.13 #4).
- * Adapter + public-data code are loaded lazily (§10.10).
+ * Pacifica venue definition.
+ * Adapter + public-data code are loaded lazily.
  */
 import { BUILDER_FEE_CAPABILITIES } from "../builder-fee.js";
 const publicData = {
@@ -10,6 +10,15 @@ const publicData = {
     async fetchMarkets(net) {
         return (await import("../../funding/legacy-public.js")).legacyPublicData("pacifica").fetchMarkets(net);
     },
+    // Keyless positions of any account by public address (account positions --address).
+    addressKind: "solana",
+    async fetchPositionsByAddress(net, address) {
+        return (await import("../public-positions.js")).pacificaPositionsByAddress(net, address);
+    },
+    // Keyless balances of any account by public address (account balance --address).
+    async fetchBalanceByAddress(net, address) {
+        return (await import("../public-balances.js")).pacificaBalanceByAddress(net, address);
+    },
 };
 /** Pacifica `client_order_id` format: "Full UUID string" (docs.pacifica.fi rest-api orders/create-limit-order). */
 export const PACIFICA_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -50,6 +59,7 @@ export const pacificaVenue = {
     settlementIntervalHours: 1,
     fundingVerified: true,
     roles: ["marketData", "account", "trading"],
+    gatedRoles: null,
     capabilities: {
         marketOrder: "slippageBounded",
         timeInForce: ["GTC", "IOC", "ALO", "TOB"],
@@ -68,12 +78,12 @@ export const pacificaVenue = {
     // docs.pacifica.fi "Rate limits": "Pacifica uses a credit-based rate limiting system with a
     // 60-second rolling window." Tier "Unidentified IP | 125" base credits/60s (valid API Config
     // Key: 300); "Standard request/action | 1" credit.
-    // Declared only — per §10.9 the limiter is applied to new venues + lighter-rh.
+    // Declared only — per the limiter is applied to new venues + lighter-rh.
     rateLimit: { capacity: 125, refillPerSec: 125 / 60, weights: null },
     restrictedRegions: [],
     symbolIdentity: "baseTicker",
     publicData,
-    // §12: spot (SOL-USDC) shares the perp account — USDC is perp margin, no transfer.
+    // spot (SOL-USDC) shares the perp account — USDC is perp margin, no transfer.
     spot: {
         accountModel: "unified",
         quoteAssets: { mainnet: ["USDC"], testnet: ["USDC"] },
@@ -91,5 +101,6 @@ export const pacificaVenue = {
     },
     maxSlippageBps: 5000,
     builderFee: BUILDER_FEE_CAPABILITIES["pacifica"],
+    apiStatus: { kind: "official" },
     create: async (ctx) => (await import("./create-helpers.js")).createPacifica(ctx),
 };

package/dist/exchanges/venues/qfex.d.ts

@@ -1,5 +1,5 @@
 /**
- * QFEX venue definition (design §14.1 as amended by §14.12).
+ * QFEX venue definition.
  *
  * TradFi perpetuals (equities, indices, commodities; no spot) on a custodial, off-chain
  * matching engine. All markets are cross-margin, margin asset USDC. Orders go over the Trade

package/dist/exchanges/venues/qfex.js

@@ -1,5 +1,5 @@
 /**
- * QFEX venue definition (design §14.1 as amended by §14.12).
+ * QFEX venue definition.
  *
  * TradFi perpetuals (equities, indices, commodities; no spot) on a custodial, off-chain
  * matching engine. All markets are cross-margin, margin asset USDC. Orders go over the Trade
@@ -71,12 +71,13 @@ export const qfexVenue = {
     // hourly × 8760 overstates it. Until both are settled QFEX is not a funding-arb venue.
     fundingVerified: false,
     roles: ["marketData", "account", "trading"],
+    gatedRoles: null,
     capabilities: {
         // The venue offers a native MARKET order (bounded only by the price band — docs /qfex/risk-limits
         // "Dynamic price bands": 1.65%–10% by product preset and session; "integrations should use
         // that live value rather than hardcoding a percentage"); the
         // adapter sends every market order as an IOC LIMIT at the tick-aligned protection price
-        // (mark ± resolved slippage, design §13.2) — the same declaration as Ondo.
+        // (mark ± resolved slippage) — the same declaration as Ondo.
         marketOrder: "native",
         // ALO = order_type "ALO" + GTC.
         timeInForce: ["GTC", "IOC", "FOK", "ALO"],
@@ -123,6 +124,7 @@ export const qfexVenue = {
     // Widest documented price band (equities at the open: 10%). The order's own band is checked before sending.
     maxSlippageBps: 1000,
     builderFee: BUILDER_FEE_CAPABILITIES["qfex"],
+    apiStatus: { kind: "official" },
     create: async (ctx) => {
         const { QfexAdapter } = await import("../qfex/adapter.js");
         const adapter = new QfexAdapter(qfexVenue, ctx);

package/dist/exchanges/venues/risex-release.d.ts

@@ -0,0 +1,14 @@
+/**
+ * RISEx release switch (owner decision 2026-10-19: new venues ship in phases).
+ *
+ * Phase 1 (0.15.0): RISEx is read-only — market data and public-by-address account reads.
+ * Phase 2 (a later release): trading. Flip this to `true`; nothing else needs to change.
+ *
+ * false removes the "trading" role from the RISEx venue definition (risex.ts), so every trading /
+ * signer / agent / bot / MCP-write path refuses with CAPABILITY_UNSUPPORTED through the role
+ * mechanism (venue.ts roleUnsupported()), and the adapter refuses writes itself as well.
+ * The trading code and its tests stay; those tests enable the switch with
+ * `vi.mock(".../venues/risex-release.js", () => ({ RISEX_TRADING_ENABLED: true }))`.
+ * Kept in its own module so tests can mock it without replacing the venue definition.
+ */
+export declare const RISEX_TRADING_ENABLED: boolean;

package/dist/exchanges/venues/risex-release.js

@@ -0,0 +1,14 @@
+/**
+ * RISEx release switch (owner decision 2026-10-19: new venues ship in phases).
+ *
+ * Phase 1 (0.15.0): RISEx is read-only — market data and public-by-address account reads.
+ * Phase 2 (a later release): trading. Flip this to `true`; nothing else needs to change.
+ *
+ * false removes the "trading" role from the RISEx venue definition (risex.ts), so every trading /
+ * signer / agent / bot / MCP-write path refuses with CAPABILITY_UNSUPPORTED through the role
+ * mechanism (venue.ts roleUnsupported()), and the adapter refuses writes itself as well.
+ * The trading code and its tests stay; those tests enable the switch with
+ * `vi.mock(".../venues/risex-release.js", () => ({ RISEX_TRADING_ENABLED: true }))`.
+ * Kept in its own module so tests can mock it without replacing the venue definition.
+ */
+export const RISEX_TRADING_ENABLED = false;

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

@@ -0,0 +1,31 @@
+/**
+ * RISEx — fully on-chain perps order book on RISE chain (chainId 4153), USDC collateral.
+ *
+ * Two keys (developer.rise.trade "Integration"): the account (master EVM wallet) signs setup only;
+ * a registered session SIGNER signs every order / cancel / leverage / margin action with an EIP-712
+ * VerifyWitness permit (the server submits it and pays gas). perp-cli registers the signer with the
+ * master and then restricts it ON-CHAIN to the trading permission (no fund movement), and keeps its
+ * key in OWS wallet `agent-risex-<master>[-testnet]` (SSOT Rule #3).
+ *
+ * RELEASE PHASE: trading is implemented but switched OFF in this release (risex-release.ts
+ * RISEX_TRADING_ENABLED). RISEx is read-only here — market data and public-by-address account
+ * reads; every trading / signer path refuses with CAPABILITY_UNSUPPORTED (RISEX_TRADING_GATE).
+ *
+ * Deposits and withdrawals are app-only (owner decision 2026-10-13): `funds deposit|withdraw risex`
+ * refuse with CAPABILITY_UNSUPPORTED and point to app.rise.trade. Account reads are public by
+ * address. TP/SL and builder fees are not implemented yet.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import type { VenueDefinition } from "../venue.js";
+export declare const RISEX_APP_URL = "https://app.rise.trade";
+/** The uniform deposit / withdraw refusal (owner decision: funds move through the RISEx app only). */
+export declare const RISEX_FUNDS_APP_ONLY: {
+    readonly reason: "RISEx deposits and withdrawals are done in the RISEx app; perp-cli does not move RISEx funds";
+    readonly remediation: "Deposit / withdraw at https://app.rise.trade (Portfolio → Deposit / Withdraw). perp-cli reads RISEx market data and your account (read-only in this release)";
+};
+/** The uniform refusal for every RISEx trading / signer path while RISEX_TRADING_ENABLED is false. */
+export declare const RISEX_TRADING_GATE: {
+    readonly reason: "RISEx trading is planned for a later perp-cli release; in this version RISEx is read-only (market data and account reads)";
+    readonly remediation: "Trade RISEx in the RISEx app (https://app.rise.trade). perp-cli shows RISEx market data (perp -e risex market list|prices|funding|book) and account reads (perp -e risex portfolio, perp -e risex account positions)";
+};
+export declare const risexVenue: VenueDefinition;

package/dist/exchanges/venues/risex.js

@@ -0,0 +1,131 @@
+/**
+ * RISEx — fully on-chain perps order book on RISE chain (chainId 4153), USDC collateral.
+ *
+ * Two keys (developer.rise.trade "Integration"): the account (master EVM wallet) signs setup only;
+ * a registered session SIGNER signs every order / cancel / leverage / margin action with an EIP-712
+ * VerifyWitness permit (the server submits it and pays gas). perp-cli registers the signer with the
+ * master and then restricts it ON-CHAIN to the trading permission (no fund movement), and keeps its
+ * key in OWS wallet `agent-risex-<master>[-testnet]` (SSOT Rule #3).
+ *
+ * RELEASE PHASE: trading is implemented but switched OFF in this release (risex-release.ts
+ * RISEX_TRADING_ENABLED). RISEx is read-only here — market data and public-by-address account
+ * reads; every trading / signer path refuses with CAPABILITY_UNSUPPORTED (RISEX_TRADING_GATE).
+ *
+ * Deposits and withdrawals are app-only (owner decision 2026-10-13): `funds deposit|withdraw risex`
+ * refuse with CAPABILITY_UNSUPPORTED and point to app.rise.trade. Account reads are public by
+ * address. TP/SL and builder fees are not implemented yet.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import { RISEX_TRADING_ENABLED } from "./risex-release.js";
+export const RISEX_APP_URL = "https://app.rise.trade";
+/** The uniform deposit / withdraw refusal (owner decision: funds move through the RISEx app only). */
+export const RISEX_FUNDS_APP_ONLY = {
+    reason: "RISEx deposits and withdrawals are done in the RISEx app; perp-cli does not move RISEx funds",
+    remediation: `Deposit / withdraw at ${RISEX_APP_URL} (Portfolio → Deposit / Withdraw). perp-cli reads RISEx market data and your account (read-only in this release)`,
+};
+/** The uniform refusal for every RISEx trading / signer path while RISEX_TRADING_ENABLED is false. */
+export const RISEX_TRADING_GATE = {
+    reason: "RISEx trading is planned for a later perp-cli release; in this version RISEx is read-only (market data and account reads)",
+    remediation: `Trade RISEx in the RISEx app (${RISEX_APP_URL}). perp-cli shows RISEx market data (perp -e risex market list|prices|funding|book) and account reads (perp -e risex portfolio, perp -e risex account positions)`,
+};
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../risex/public.js")).risexPublicData.fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../risex/public.js")).risexPublicData.fetchMarkets(net);
+    },
+    // Keyless positions of any account by public address (account positions --address): the
+    // adapter's own public-by-address read (/v1/portfolio/details), no signer.
+    addressKind: "evm",
+    async fetchPositionsByAddress(net, address) {
+        const { RisexAdapter } = await import("../risex/adapter.js");
+        const adapter = new RisexAdapter(risexVenue, net, { account: address, signer: null, meta: null, noSignerReason: null });
+        return { positions: await adapter.getPositions(), errors: {}, notes: [] };
+    },
+    // Keyless balance (account balance --address): the same signer-less adapter's getBalance. RISEx
+    // has no spot market: spot null.
+    async fetchBalanceByAddress(net, address) {
+        const { RisexAdapter } = await import("../risex/adapter.js");
+        const adapter = new RisexAdapter(risexVenue, net, { account: address, signer: null, meta: null, noSignerReason: null });
+        return { balance: await adapter.getBalance(), spot: null, accounts: null, dexes: null, accountMode: null, errors: {}, notes: [] };
+    },
+};
+export const risexVenue = {
+    id: "risex",
+    aliases: ["rise"],
+    displayName: "RISEx",
+    family: "risex",
+    masterKeyKind: "evm",
+    agentKeyKind: "evm",
+    secretStorage: { kind: "ows-wallet", dir: null },
+    networks: {
+        mainnet: {
+            restUrl: "https://api.rise.trade",
+            wsUrl: "wss://ws.rise.trade/ws",
+            explorerUrl: "https://explorer.risechain.com",
+            signingChainId: 4153,
+            settlementChain: "rise",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: "https://rpc.risechain.com",
+            depositPins: null,
+        },
+        testnet: {
+            restUrl: "https://api.testnet.rise.trade",
+            // ws.testnet.rise.trade answered 525 on 2026-10-13; the API host serves the socket.
+            wsUrl: "wss://api.testnet.rise.trade/ws/",
+            explorerUrl: null,
+            signingChainId: 11155931,
+            settlementChain: "rise",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: "https://testnet.riselabs.xyz",
+            depositPins: null,
+        },
+    },
+    // funding_interval = 3600e9 ns on every market; current_funding_rate is a fraction per hour.
+    fundingRateBasis: { kind: "perHours", hours: 1 },
+    settlementIntervalHours: 1,
+    // Verified 2026-10-14: current_funding_rate equals the last settled print in
+    // /funding-rate-history, and public /v1/account/funding-payments satisfy
+    // payment = position size × index price × rate for that hour, positive = paid. Evidence: raw
+    // records of 6 mainnet accounts / 23 markets / 31 hours in
+    // src/__tests__/fixtures/risex/funding-payments-evidence.json, checked by risex-evidence.test.ts.
+    fundingVerified: true,
+    // Phase 1 (0.15.0): read-only. The trading role comes back with RISEX_TRADING_ENABLED (phase 2).
+    roles: RISEX_TRADING_ENABLED ? ["marketData", "account", "trading"] : ["marketData", "account"],
+    gatedRoles: RISEX_TRADING_ENABLED ? null : { roles: ["trading"], ...RISEX_TRADING_GATE },
+    // Describes the implemented trading path; unreachable while the trading role is gated
+    // (requireCapabilities() checks the role first).
+    capabilities: {
+        // Market = order_type Market + IOC with a price_ticks bound (the venue requires FOK/IOC).
+        marketOrder: "slippageBounded",
+        // ALO = GTC + post_only. GTT is not offered (the ttl_units unit is undocumented).
+        timeInForce: ["GTC", "IOC", "FOK", "ALO"],
+        reduceOnlyTif: null,
+        clientOrderId: true,
+        // The response carries block_number (on-chain inclusion); IOC also carries filled_quantity.
+        orderAck: "sync",
+        tpsl: null,
+        amend: null,
+        batchPlaceMax: null,
+        marginModes: ["cross", "isolated"],
+        withdrawAssets: null,
+    },
+    // Documented 500 requests / 10 s per IP; Cloudflare 200 / 10 s observed — the stricter one.
+    rateLimit: { capacity: 200, refillPerSec: 20, weights: null },
+    // Not yet reviewed (open question Q-R5).
+    restrictedRegions: [],
+    symbolIdentity: "baseTicker",
+    publicData,
+    spot: null,
+    // The venue's own match_price_band (2% today) is checked per market before sending.
+    maxSlippageBps: 1000,
+    builderFee: null,
+    apiStatus: { kind: "official" },
+    async create(ctx) {
+        const { RisexAdapter } = await import("../risex/adapter.js");
+        return RisexAdapter.create(risexVenue, ctx);
+    },
+};

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

@@ -0,0 +1,18 @@
+/**
+ * TxFlow venue definition — MARKET DATA ONLY, through an UNOFFICIAL API.
+ *
+ * TxFlow publishes no official trading / data API yet (its "Platform API" is "Coming Soon").
+ * perp-cli reads the undocumented Hyperliquid-style `POST /info` endpoint and the WebSocket the
+ * TxFlow web app itself uses. It may change or be blocked without notice, so:
+ *  - apiStatus is "unofficial" and every user-facing surface labels it;
+ *  - funding is unverified (fundingVerified false): the rate is quoted in PERCENT per hour and is a
+ *    live, moving estimate — kept out of arb ranking unless --include-unverified;
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path
+ *    refuses with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported()).
+ * There is no TxFlow order, transfer or account code at all.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import type { VenueDefinition } from "../venue.js";
+export declare const TXFLOW_REST_URL = "https://api.txflow.com";
+export declare const TXFLOW_WS_URL = "wss://api.txflow.com/ws";
+export declare const txflowVenue: VenueDefinition;

package/dist/exchanges/venues/txflow.js

@@ -0,0 +1,77 @@
+/**
+ * TxFlow venue definition — MARKET DATA ONLY, through an UNOFFICIAL API.
+ *
+ * TxFlow publishes no official trading / data API yet (its "Platform API" is "Coming Soon").
+ * perp-cli reads the undocumented Hyperliquid-style `POST /info` endpoint and the WebSocket the
+ * TxFlow web app itself uses. It may change or be blocked without notice, so:
+ *  - apiStatus is "unofficial" and every user-facing surface labels it;
+ *  - funding is unverified (fundingVerified false): the rate is quoted in PERCENT per hour and is a
+ *    live, moving estimate — kept out of arb ranking unless --include-unverified;
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path
+ *    refuses with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported()).
+ * There is no TxFlow order, transfer or account code at all.
+ * Not registered here; the registry module owns registerVenue().
+ */
+export const TXFLOW_REST_URL = "https://api.txflow.com";
+export const TXFLOW_WS_URL = "wss://api.txflow.com/ws";
+/** Lazy: public.ts (and `ws`) is only loaded when market data is actually requested. */
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../txflow/public.js")).txflowPublicData.fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../txflow/public.js")).txflowPublicData.fetchMarkets(net);
+    },
+};
+export const txflowVenue = {
+    id: "txflow",
+    aliases: ["txf"],
+    displayName: "TxFlow",
+    family: "txflow",
+    masterKeyKind: "none",
+    agentKeyKind: "none",
+    secretStorage: { kind: "none", dir: null },
+    networks: {
+        mainnet: {
+            restUrl: TXFLOW_REST_URL,
+            wsUrl: TXFLOW_WS_URL,
+            explorerUrl: null,
+            signingChainId: null,
+            settlementChain: "offchain",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+        // No public testnet.
+        testnet: null,
+    },
+    // settlementIntervalMs = 3600000 on every market (marketTicker); the rate is percent per hour.
+    fundingRateBasis: { kind: "perHours", hours: 1 },
+    settlementIntervalHours: 1,
+    // Unofficial API; the percent unit is inferred (HL-style 0.00125 %/h baseline on most markets);
+    // the published value moves every tick (a live estimate, not a settled print).
+    fundingVerified: false,
+    roles: ["marketData"],
+    gatedRoles: null,
+    capabilities: null,
+    // No rate-limit headers are published; conservative.
+    rateLimit: { capacity: 20, refillPerSec: 2, weights: null },
+    restrictedRegions: [],
+    symbolIdentity: "baseTicker",
+    publicData,
+    spot: null,
+    // Unused (no trading role); the field is required by the definition shape.
+    maxSlippageBps: 1,
+    builderFee: null,
+    apiStatus: {
+        kind: "unofficial",
+        note: "undocumented HL-style API used by the app.txflow.com web app; read-only in perp-cli and may change or be blocked without notice",
+        docs: "https://docs.txflow.com",
+    },
+    // A public-only adapter: market data works, every account / trading method refuses.
+    async create(ctx) {
+        const { TxflowPublicAdapter } = await import("../txflow/adapter.js");
+        return new TxflowPublicAdapter(txflowVenue, ctx.network);
+    },
+};

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

@@ -0,0 +1,21 @@
+/**
+ * Variational (Omni) venue definition — MARKET DATA ONLY, through the OFFICIAL read-only API.
+ *
+ * Variational Omni is an RFQ venue: the Omni Liquidity Provider (OLP) is the only maker and quotes
+ * every trade — there is no order book (docs.variational.io/variational-protocol/key-concepts/trading-via-rfq).
+ * Its documented public API (docs.variational.io/technical-documentation/api) is one endpoint,
+ * `GET /metadata/v2/stats`, serving every market at once. The trading API "is still in
+ * development, and is not yet available to any users", so:
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path refuses
+ *    with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported());
+ *  - `market book` shows the OLP's indicative RFQ quotes at fixed notionals, labelled as such
+ *    (never as order-book levels).
+ * No WebSocket is documented, so there is no ws codec.
+ * Not registered here; the registry module owns registerVenue().
+ */
+import type { VenueDefinition } from "../venue.js";
+export declare const VARIATIONAL_REST_URL = "https://omni-client-api.prod.ap-northeast-1.variational.io";
+export declare const VARIATIONAL_API_DOCS = "https://docs.variational.io/technical-documentation/api";
+/** Every role refusal's remediation (VenueDefinition.readOnlyRemediation, read by roleUnsupported). */
+export declare const VARIATIONAL_READ_ONLY_REMEDIATION = "Variational is read-only (market data) in perp-cli; Variational has no public trading API yet. Trade on omni.variational.io; perp-cli shows Variational market data (perp -e variational market list|prices|info|funding|book, perp arb scan --rates --include-unverified)";
+export declare const variationalVenue: VenueDefinition;

package/dist/exchanges/venues/variational.js

@@ -0,0 +1,85 @@
+/**
+ * Variational (Omni) venue definition — MARKET DATA ONLY, through the OFFICIAL read-only API.
+ *
+ * Variational Omni is an RFQ venue: the Omni Liquidity Provider (OLP) is the only maker and quotes
+ * every trade — there is no order book (docs.variational.io/variational-protocol/key-concepts/trading-via-rfq).
+ * Its documented public API (docs.variational.io/technical-documentation/api) is one endpoint,
+ * `GET /metadata/v2/stats`, serving every market at once. The trading API "is still in
+ * development, and is not yet available to any users", so:
+ *  - roles are ["marketData"]: every account / trading / funds / agent / builder / bot path refuses
+ *    with CAPABILITY_UNSUPPORTED before any request (venue.ts roleUnsupported());
+ *  - `market book` shows the OLP's indicative RFQ quotes at fixed notionals, labelled as such
+ *    (never as order-book levels).
+ * No WebSocket is documented, so there is no ws codec.
+ * Not registered here; the registry module owns registerVenue().
+ */
+export const VARIATIONAL_REST_URL = "https://omni-client-api.prod.ap-northeast-1.variational.io";
+export const VARIATIONAL_API_DOCS = "https://docs.variational.io/technical-documentation/api";
+/** Every role refusal's remediation (VenueDefinition.readOnlyRemediation, read by roleUnsupported). */
+export const VARIATIONAL_READ_ONLY_REMEDIATION = "Variational is read-only (market data) in perp-cli; Variational has no public trading API yet. Trade on omni.variational.io; perp-cli shows Variational market data (perp -e variational market list|prices|info|funding|book, perp arb scan --rates --include-unverified)";
+/** Lazy: public.ts is only loaded when market data is actually requested. */
+const publicData = {
+    async fetchFundingRates(net) {
+        return (await import("../variational/public.js")).variationalPublicData.fetchFundingRates(net);
+    },
+    async fetchMarkets(net) {
+        return (await import("../variational/public.js")).variationalPublicData.fetchMarkets(net);
+    },
+};
+export const variationalVenue = {
+    id: "variational",
+    aliases: ["var", "omni"],
+    displayName: "Variational",
+    family: "variational",
+    masterKeyKind: "none",
+    agentKeyKind: "none",
+    secretStorage: { kind: "none", dir: null },
+    networks: {
+        mainnet: {
+            restUrl: VARIATIONAL_REST_URL,
+            // No WebSocket is documented.
+            wsUrl: null,
+            explorerUrl: null,
+            signingChainId: null,
+            // Settlement pools live on Arbitrum; perp-cli never touches them (read-only).
+            settlementChain: "offchain",
+            collateral: ["USDC"],
+            collateralAssetIndex: null,
+            rpcUrl: null,
+            depositPins: null,
+        },
+        // No public testnet API.
+        testnet: null,
+    },
+    // funding.interval_seconds is per market (1h / 4h / 8h perps; 24h swaps).
+    fundingRateBasis: "perMarket",
+    settlementIntervalHours: "perMarket",
+    // UNVERIFIED (design §14.12 #6: verified = checked against settled payments). The unit is
+    // documented (funding.last.interval_rate = fraction per interval_seconds, positive = longs pay)
+    // and interval_rate = annualized_rate × interval / 365 d holds on every live perp (2026-10-19),
+    // but that only shows the published fields agree: the rate is a moving prediction, there is no
+    // public account API to check settled payments, and the accrual hours of equity / ETF perps are
+    // not documented. Shown only on request (arb scan --rates --include-unverified).
+    fundingVerified: false,
+    roles: ["marketData"],
+    gatedRoles: null,
+    capabilities: null,
+    // Documented: 10 requests / 10 s per IP (shared with the legacy v1 endpoint). One call serves
+    // every market and is cached briefly (variational/public.ts), so commands rarely hit this.
+    rateLimit: { capacity: 10, refillPerSec: 1, weights: null },
+    // docs.variational.io/legal/restricted-persons (last updated 2026-04-20). Warn-only (never enforced).
+    restrictedRegions: ["US", "CA", "CU", "IR", "KP", "SD", "SY", "TW", "PR", "GU", "VI", "AS", "MP", "UM", "FM", "MH", "PW"],
+    symbolIdentity: "baseTicker",
+    publicData,
+    spot: null,
+    // Unused (no trading role); the field is required by the definition shape.
+    maxSlippageBps: 1,
+    builderFee: null,
+    apiStatus: { kind: "official" },
+    readOnlyRemediation: VARIATIONAL_READ_ONLY_REMEDIATION,
+    // A public-only adapter: market data works, every account / trading method refuses.
+    async create(ctx) {
+        const { VariationalPublicAdapter } = await import("../variational/adapter.js");
+        return new VariationalPublicAdapter(variationalVenue, ctx.network);
+    },
+};

package/dist/execution-log.d.ts

@@ -1,7 +1,7 @@
 export interface ExecutionRecord {
     id: string;
     timestamp: string;
-    type: "market_order" | "limit_order" | "cancel" | "stop_order" | "edit_order" | "rebalance" | "arb_entry" | "arb_close" | "bridge" | "multi_leg" | "multi_leg_rollback" | "split_order";
+    type: "market_order" | "limit_order" | "cancel" | "stop_order" | "edit_order" | "rebalance" | "arb_entry" | "arb_close" | "bridge" | "multi_leg" | "multi_leg_rollback" | "split_order" | "print_deposit" | "print_end" | "vault_deposit" | "vault_withdraw";
     exchange: string;
     symbol: string;
     side: string;

package/dist/funding/legacy-public.d.ts

@@ -1,6 +1,6 @@
 /**
  * Public market data for the legacy venues without a native `getVenueMarkets`
- * (pacifica, hyperliquid core, aster) — design §10.6. Lighter uses
+ * (pacifica, hyperliquid core, aster). Lighter uses
  * exchanges/lighter-public.ts.
  *
  * Network-aware: the REST base comes from `legacyPublicBaseUrl(venue, net)`,
@@ -19,13 +19,15 @@
  *   pacifica: crypto-centric; PACIFICA_NON_CRYPTO lists every non-crypto perp
  *     listed on 2026-09-30.
  *   aster: exchangeInfo `underlyingSubType` (STOCK / ETF / Commodities / pre-launch).
- *   AMBIGUOUS tickers are excluded with a warning so they cannot produce a false
- *   cross-venue match (SPX = the SPX6900 token, whose ticker equals the S&P 500
- *   canonical key).
+ *   Ambiguous tickers (UNCLASSIFIED_TICKERS, src/ws/unclassified.ts — SPX = the SPX6900
+ *   token, whose ticker equals the S&P 500 canonical key) are listed as "unclassified"
+ *   (canonical null) so they cannot produce a false cross-venue match.
  *
  * Fields a venue does not publish on this path are null (HL has no fixed tick
  * size; Aster leverage brackets need a signed call; Aster OI is per-symbol only).
  */
 import type { VenuePublicData } from "../exchanges/venue.js";
 export type LegacyPublicVenue = "pacifica" | "hyperliquid" | "aster";
+/** One public JSON read with the venue error mapping (rate limits, HTTP status, invalid JSON). */
+export declare function legacyPublicJson(venue: LegacyPublicVenue, url: string, label: string, init?: RequestInit): Promise<unknown>;
 export declare function legacyPublicData(venue: LegacyPublicVenue): VenuePublicData;