perp-cli 0.14.2 → 0.15.0

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)`,

package/dist/funding/legacy-public.js

@@ -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)`,
@@ -27,6 +27,7 @@
  * size; Aster leverage brackets need a signed call; Aster OI is per-symbol only).
  */
 import { HL_MIN_ORDER_VALUE_USD } from "../constants.js";
+import { isPacificaPerpetual } from "../ws/pacifica-instrument.js";
 import { PerpError } from "../errors.js";
 import { venueRateString } from "../utils/numeric.js";
 import { assertOk } from "../api/public/_http.js";
@@ -127,11 +128,11 @@ async function pacificaRows(net) {
     const unclassified = [];
     const unpriced = [];
     for (const m of info) {
-        // /info lists spot markets too (e.g. SOL-USDC). A row without the field cannot be classified.
+        // /info lists spot markets too (e.g. SOL-USDC): perps only. A row without the field cannot be classified.
         if (typeof m.instrument_type !== "string") {
             throw new PerpError("EXCHANGE_ERROR", `Pacifica /info row ${String(m.symbol)} has no instrument_type`, { exchange: "pacifica" });
         }
-        if (m.instrument_type === "spot")
+        if (!isPacificaPerpetual(m))
             continue;
         const symbol = String(m.symbol ?? "");
         const assetClass = classifyPacifica(symbol);
@@ -200,6 +201,10 @@ async function hyperliquidRows(net) {
     const unclassified = [];
     const unpriced = [];
     universe.forEach((a, i) => {
+        // Delisted assets stay in meta (isDelisted: true) with zeroed funding / volume / OI
+        // (live 2026-10-14: 56 of 234) — not a market: excluded from listings, prices and scans.
+        if (a.isDelisted === true)
+            return;
         const ctx = ctxs[i];
         const symbol = String(a.name ?? "");
         const assetClass = classifyHyperliquid(symbol);
@@ -237,7 +242,7 @@ async function hyperliquidRows(net) {
                 maxLeverage: Number.isFinite(maxLeverage) && maxLeverage > 0 ? maxLeverage : null,
                 marginTiers: null,
                 session: null,
-                tradable: a.isDelisted !== true,
+                tradable: true, // delisted assets are skipped above
             },
             nextFundingTime: null, // not published in metaAndAssetCtxs
         });

package/dist/funding/normalize.d.ts

@@ -1,5 +1,5 @@
 /**
- * Funding rate normalization (design §10.1, §10.13 #1).
+ * Funding rate normalization.
  *
  * The number of hours one quoted rate covers (the funding BASIS) comes from the
  * venue definition — `VenueDefinition.fundingRateBasis`, read through

package/dist/funding/normalize.js

@@ -1,5 +1,5 @@
 /**
- * Funding rate normalization (design §10.1, §10.13 #1).
+ * Funding rate normalization.
  *
  * The number of hours one quoted rate covers (the funding BASIS) comes from the
  * venue definition — `VenueDefinition.fundingRateBasis`, read through

package/dist/funding/rates.d.ts

@@ -1,11 +1,11 @@
 /**
  * Real-time cross-venue funding rate comparison.
  *
- * Fans out over every venue with the "marketData" role (design §10.6) using
+ * Fans out over every venue with the "marketData" role using
  * each venue's `publicData.fetchFundingRates(net)`, normalizes every row to a
  * per-hour rate with the row's own basis (Lighter
  * family 8h, Aster per-symbol), and matches markets across venues by
- * `canonical` (null → excluded, §10.9).
+ * `canonical` (null → excluded).
  *
  * A venue that fails is reported in `exchangeStatus` ("error") and
  * `exchangeErrors` (message) — its rows are absent, never silently empty.
@@ -28,6 +28,8 @@ export interface ExchangeFundingRate {
     historicalAvg: HistoricalAverages | null;
     /** false = the venue's funding rate is unverified (VenueDefinition.fundingVerified) — shown only on explicit request. */
     fundingVerified: boolean;
+    /** How the row was read: "unofficial" = an undocumented venue API (VenueDefinition.apiStatus) — may change without notice. */
+    apiStatus: "official" | "unofficial";
 }
 export interface SymbolFundingComparison {
     /** Canonical symbol shared by every row. */
@@ -38,12 +40,19 @@ export interface SymbolFundingComparison {
     shortExchange: string;
     bestMarkPrice: number;
     estHourlyIncomeUsd: number;
+    /**
+     * false = a leg of the long/short pair sits on a venue without the trading role (RISEx while its
+     * trading is gated in this release): the spread is data only — `arb exec` refuses it.
+     */
+    executable: boolean;
+    /** Venues of the long/short pair that perp-cli cannot trade (read-only); [] when executable. */
+    readOnlyLegs: string[];
 }
 export interface FundingRateSnapshot {
     timestamp: string;
     symbols: SymbolFundingComparison[];
     exchangeStatus: Record<string, "ok" | "error">;
-    /** Error message per venue whose status is "error" (§10.13 #3). */
+    /** Error message per venue whose status is "error". */
     exchangeErrors: Record<string, string>;
 }
 export declare const TOP_SYMBOLS: string[];
@@ -59,6 +68,37 @@ export declare function fetchVenuesRates(venues: VenueDefinition[], net: Network
     exchangeStatus: Record<string, "ok" | "error">;
     exchangeErrors: Record<string, string>;
 }>;
+export interface VenuePrice {
+    exchange: VenueId;
+    /** Venue display symbol. */
+    symbol: string;
+    canonical: string;
+    markPrice: number;
+    apiStatus: "official" | "unofficial";
+}
+export interface PriceGroupSnapshot {
+    /** canonical → venue prices, after the median price-outlier drop (same guard as the funding scan). */
+    groups: Map<string, VenuePrice[]>;
+    exchangeStatus: Record<string, "ok" | "error">;
+    exchangeErrors: Record<string, string>;
+}
+/**
+ * Mark prices of `venues`, grouped by canonical symbol — the grouping and price-outlier guard of
+ * the funding comparison, WITHOUT any funding dependency: read from each venue's market directory
+ * (publicData.fetchMarkets), so a market with a null funding rate or a venue whose funding is
+ * unverified is still priced. Rows without a canonical symbol, not tradable, or without a
+ * positive mark are excluded. A venue that fails is reported in exchangeStatus / exchangeErrors.
+ */
+export declare function fetchCanonicalPriceGroups(venues: VenueDefinition[], opts?: {
+    symbols?: string[];
+    network?: Network;
+    tag?: string;
+}): Promise<PriceGroupSnapshot>;
+/** Whether perp-cli can trade both legs of a long/short pair (the trading role), and which it cannot. */
+export declare function pairExecutability(longExchange: string, shortExchange: string): {
+    executable: boolean;
+    readOnlyLegs: string[];
+};
 /**
  * Fetch funding rates from every market-data venue in parallel, normalize, and compare.
  * Returns rates sorted by max spread (descending).
@@ -97,7 +137,7 @@ export interface SpotPerpSpread {
 /**
  * Fetch spot+perp funding rate spreads.
  * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
- * Only includes symbols available on at least one bot spot venue (def.spot, §12.4 #3).
+ * Only includes symbols available on at least one bot spot venue (def.spot).
  *
  * Key safety checks:
  * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN

package/dist/funding/rates.js

@@ -1,11 +1,11 @@
 /**
  * Real-time cross-venue funding rate comparison.
  *
- * Fans out over every venue with the "marketData" role (design §10.6) using
+ * Fans out over every venue with the "marketData" role using
  * each venue's `publicData.fetchFundingRates(net)`, normalizes every row to a
  * per-hour rate with the row's own basis (Lighter
  * family 8h, Aster per-symbol), and matches markets across venues by
- * `canonical` (null → excluded, §10.9).
+ * `canonical` (null → excluded).
  *
  * A venue that fails is reported in `exchangeStatus` ("error") and
  * `exchangeErrors` (message) — its rows are absent, never silently empty.
@@ -26,7 +26,11 @@ export const TOP_SYMBOLS = [
 ];
 /** Mark-price source preference for `bestMarkPrice` (most liquid first). */
 const MARK_PRICE_PREFERENCE = [
-    "hyperliquid", "pacifica", "lighter", "aster", "lighter-rh", "ondo", "arcus", "qfex",
+    "hyperliquid", "pacifica", "lighter", "aster", "lighter-rh", "ondo", "arcus", "risex", "qfex", "grvt", "extended",
+    // RFQ venue: the mark is the single maker's (OLP) price.
+    "variational",
+    // Unofficial API: last resort as a mark-price source.
+    "txflow",
 ];
 // ── Per-venue fetch ──
 function errorMessage(e) {
@@ -57,14 +61,14 @@ async function fetchVenueRates(def, net) {
             unpriced.push(r.symbol);
             continue;
         }
-        out.push(toExchangeRate(r, r.canonical, markPrice, def.fundingVerified));
+        out.push(toExchangeRate(r, r.canonical, markPrice, def.fundingVerified, def.apiStatus.kind));
     }
     if (unpriced.length > 0) {
         console.warn(`[${def.id}] excluded ${unpriced.length} funding row(s) without a mark price: ${unpriced.join(", ")}`);
     }
     return out;
 }
-function toExchangeRate(r, canonical, markPrice, fundingVerified) {
+function toExchangeRate(r, canonical, markPrice, fundingVerified, apiStatus) {
     const fundingRate = Number(r.rate);
     if (!Number.isFinite(fundingRate)) {
         throw new PerpError("EXCHANGE_ERROR", `${r.venue} ${r.symbol}: non-numeric funding rate "${r.rate}"`);
@@ -82,6 +86,7 @@ function toExchangeRate(r, canonical, markPrice, fundingVerified) {
         nextFundingTime: r.nextFundingTime,
         historicalAvg: null,
         fundingVerified,
+        apiStatus,
     };
 }
 /**
@@ -117,7 +122,7 @@ const _warnedPriceMismatch = new Set();
  * venue whose mark price deviates more than MAX_PRICE_DEVIATION_PCT from the
  * group median, with a one-time stderr warning per (symbol, venue).
  */
-function dropPriceOutliers(canonical, list) {
+function dropPriceOutliers(canonical, list, tag = "funding") {
     if (list.length < 2)
         return list;
     const sorted = list.map(r => r.markPrice).sort((x, y) => x - y);
@@ -133,12 +138,12 @@ function dropPriceOutliers(canonical, list) {
         const key = `${canonical}:${r.exchange}`;
         if (!_warnedPriceMismatch.has(key)) {
             _warnedPriceMismatch.add(key);
-            process.stderr.write(`[funding] excluded ${r.exchange} ${canonical}: mark ${r.markPrice} deviates ${devPct.toFixed(1)}% from cross-venue median ${mid} (likely a different asset with the same ticker)\n`);
+            process.stderr.write(`[${tag}] excluded ${r.exchange} ${canonical}: mark ${r.markPrice} deviates ${devPct.toFixed(1)}% from cross-venue median ${mid} (likely a different asset with the same ticker)\n`);
         }
         return false;
     });
 }
-function groupByCanonical(rates, symbols) {
+function groupByCanonical(rates, symbols, tag = "funding") {
     const out = new Map();
     for (const r of rates) {
         if (symbols && !symbols.includes(r.canonical))
@@ -150,7 +155,7 @@ function groupByCanonical(rates, symbols) {
             out.set(r.canonical, [r]);
     }
     for (const [canonical, list] of [...out]) {
-        const kept = dropPriceOutliers(canonical, list);
+        const kept = dropPriceOutliers(canonical, list, tag);
         if (kept.length === 0)
             out.delete(canonical); // every venue disagreed — not comparable
         else
@@ -158,6 +163,44 @@ function groupByCanonical(rates, symbols) {
     }
     return out;
 }
+/**
+ * Mark prices of `venues`, grouped by canonical symbol — the grouping and price-outlier guard of
+ * the funding comparison, WITHOUT any funding dependency: read from each venue's market directory
+ * (publicData.fetchMarkets), so a market with a null funding rate or a venue whose funding is
+ * unverified is still priced. Rows without a canonical symbol, not tradable, or without a
+ * positive mark are excluded. A venue that fails is reported in exchangeStatus / exchangeErrors.
+ */
+export async function fetchCanonicalPriceGroups(venues, opts) {
+    ensureVenuesRegistered();
+    const net = opts?.network ?? sharedApiNetwork();
+    const settled = await Promise.allSettled(venues.map(v => v.publicData.fetchMarkets(net)));
+    const exchangeStatus = {};
+    const exchangeErrors = {};
+    const prices = [];
+    settled.forEach((res, i) => {
+        const def = venues[i];
+        if (res.status === "rejected") {
+            exchangeStatus[def.id] = "error";
+            exchangeErrors[def.id] = errorMessage(res.reason);
+            return;
+        }
+        exchangeStatus[def.id] = "ok";
+        for (const m of res.value) {
+            if (m.canonical === null || !m.tradable)
+                continue;
+            const markPrice = Number(m.markPrice);
+            if (!Number.isFinite(markPrice) || markPrice <= 0)
+                continue;
+            prices.push({ exchange: def.id, symbol: m.symbol, canonical: m.canonical, markPrice, apiStatus: def.apiStatus.kind });
+        }
+    });
+    return { groups: groupByCanonical(prices, opts?.symbols, opts?.tag ?? "prices"), exchangeStatus, exchangeErrors };
+}
+/** Whether perp-cli can trade both legs of a long/short pair (the trading role), and which it cannot. */
+export function pairExecutability(longExchange, shortExchange) {
+    const readOnlyLegs = [...new Set([longExchange, shortExchange])].filter(v => !getVenue(v).roles.includes("trading"));
+    return { executable: readOnlyLegs.length === 0, readOnlyLegs };
+}
 function bestMarkPrice(rates) {
     const rank = (id) => MARK_PRICE_PREFERENCE.indexOf(id);
     return [...rates].sort((a, b) => rank(a.exchange) - rank(b.exchange))[0].markPrice;
@@ -218,6 +261,7 @@ export async function fetchAllFundingRates(opts) {
             shortExchange: highest.exchange, // short where funding is highest
             bestMarkPrice: bestMarkPrice(rates),
             estHourlyIncomeUsd,
+            ...pairExecutability(lowest.exchange, highest.exchange),
         });
     }
     // Sort by spread descending
@@ -239,7 +283,7 @@ export async function fetchSymbolFundingRates(symbol, includeUnverified = false)
 /**
  * Fetch spot+perp funding rate spreads.
  * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
- * Only includes symbols available on at least one bot spot venue (def.spot, §12.4 #3).
+ * Only includes symbols available on at least one bot spot venue (def.spot).
  *
  * Key safety checks:
  * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
@@ -247,8 +291,8 @@ export async function fetchSymbolFundingRates(symbol, includeUnverified = false)
  *   (filters out same-ticker-different-token issues like HIP-1 TRUMP ≠ perp TRUMP)
  */
 export async function fetchSpotPerpSpreads(opts) {
-    // Spot legs come from the venue definitions (def.spot, §12): only bot/arb spot venues
-    // (separate/runtime account + transfer, §12.4 #3). Perp legs: those venues + pacifica.
+    // Spot legs come from the venue definitions (def.spot): only bot/arb spot venues
+    // (separate/runtime account + transfer). Perp legs: those venues + pacifica.
     ensureVenuesRegistered();
     const net = opts?.network ?? sharedApiNetwork();
     const { listBotSpotVenues, requireSpotAdapter, defaultSpotQuote } = await import("../exchanges/spot-factory.js");

package/dist/index.js

@@ -17,6 +17,7 @@ import { createRequire } from "node:module";
 config({ path: resolve(process.env.HOME || "~", ".perp", ".env") });
 import chalk from "chalk";
 import { listVenues } from "./exchanges/venue.js";
+import { optionsVenueWords } from "./exchanges/options-venues.js";
 import { PerpError } from "./errors.js";
 import { loadSettings } from "./settings.js";
 import { jsonError, jsonOk, printCliError, printJson } from "./utils.js";
@@ -49,7 +50,7 @@ const _defaultExchange = _settings.defaultExchange || "pacifica";
 const { program, getAdapterForExchange, isJson } = buildProgram({ defaultExchange: _defaultExchange, version: _pkg.version });
 // Smart landing page: `perp` with no subcommand
 const rawArgs = process.argv.slice(2);
-const _venueWords = listVenues().flatMap(v => [v.id, ...v.aliases]);
+const _venueWords = [...listVenues().flatMap(v => [v.id, ...v.aliases]), ...optionsVenueWords()];
 const hasSubcommand = rawArgs.some((a) => !a.startsWith("-") && ![..._venueWords, "mainnet", "testnet"].includes(a));
 // `history list -n 5` (old record-count flag) → INVALID_PARAMS with the --limit migration, before
 // Commander turns it into a bare "invalid network" usage error.
@@ -118,18 +119,18 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                     const landingVenues = [];
                     for (const ex of LANDING_EXCHANGES) {
                         const def = getVenue(ex);
-                        if (def.create === null || await hasCredentials(def.id, NO_CLI_CREDENTIAL_OPTS))
+                        if (!def.roles.includes("account") || await hasCredentials(def.id, NO_CLI_CREDENTIAL_OPTS))
                             landingVenues.push(ex);
                     }
                     const statusResults = await Promise.allSettled(landingVenues.map(async (ex) => {
-                        if (getVenue(ex).create === null) {
-                            return { exchange: ex, marketDataOnly: true, ok: false, equity: 0, positions: 0 };
+                        if (!getVenue(ex).roles.includes("account")) {
+                            return { exchange: ex, marketDataOnly: true, unofficialApi: getVenue(ex).apiStatus.kind === "unofficial", ok: false, equity: 0, positions: 0 };
                         }
                         try {
                             const adapter = await withTimeout(getAdapterForExchange(ex), 5000);
                             const [balance, positions] = await withTimeout(Promise.all([adapter.getBalance(), adapter.getPositions()]), 5000);
                             const posCount = positions.filter(p => Number(p.size) > 0).length;
-                            // Spot value on top of perp equity for venues with def.spot (§12). Shared balances
+                            // Spot value on top of perp equity for venues with def.spot. Shared balances
                             // (already in perp equity) are skipped; unpriced tokens are excluded + warned.
                             let spotValue = 0;
                             const spotDef = getVenue(ex);
@@ -196,7 +197,7 @@ else {
     }).catch(async (err) => {
         // Central printer (utils.printCliError): typed PerpError code / remediation / details
         // are preserved (Rule #2: stay loud, keep semantic envelope); generic Errors go
-        // through classifyError; CAPABILITY_UNSUPPORTED prints the uniform §13.6 line.
+        // through classifyError; CAPABILITY_UNSUPPORTED prints the uniform line.
         const { printCliError } = await import("./utils.js");
         printCliError(err, isJson());
         _origExit(1);

package/dist/jobs.d.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 import type { Network } from "./exchanges/venue-types.js";
+import "./exchanges/venues/index.js";
 export interface JobEntry {
     id: string;
     strategy: string;

package/dist/jobs.js

@@ -4,9 +4,11 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
 import { parse as parseDotenv } from "dotenv";
+import { getVenue, roleUnsupported, tryResolveVenueId } from "./exchanges/venue.js";
+import "./exchanges/venues/index.js";
 import { PerpError } from "./errors.js";
 import { QFEX_AUTOMATION_VERIFIED, QFEX_REDUCE_ONLY_WIRE, qfexAutomationGate, qfexReduceOnlyGate } from "./exchanges/qfex/signing.js";
-import { startRefusal } from "./exchanges/trading-v2.js";
+import { startRefusal, unsupported } from "./exchanges/trading-v2.js";
 import { scrubSecretEnv, secretEnvNamesIn } from "./secret-env.js";
 const JOBS_DIR = join(homedir(), ".perp", "jobs");
 const LOGS_DIR = join(homedir(), ".perp", "logs");
@@ -165,6 +167,28 @@ export function startJob(opts) {
             if (automation !== null)
                 throw startRefusal(what, "it would trade unattended", automation);
         }
+        for (const v of new Set([opts.venue, opts.exchange])) {
+            const id = v?.toLowerCase();
+            const what = `Background job "${opts.strategy}"`;
+            // RISEx: unattended trading stays off until its trading path is verified on mainnet (no TP/SL yet).
+            if (id === "risex" || id === "rise") {
+                // Read-only release (trading role gated): the uniform phase refusal.
+                const risex = getVenue("risex");
+                if (!risex.roles.includes("trading"))
+                    throw startRefusal(what, "it would trade unattended", roleUnsupported(risex, "automation"));
+                throw startRefusal(what, "it would trade unattended", unsupported("RISEx", "automation", "unattended trading on RISEx is not enabled until its trading path is verified on mainnet (and it has no TP/SL yet)", "Trade RISEx manually with perp trade …"));
+            }
+            // TxFlow: market data only (unofficial read-only API).
+            if (id === "txflow" || id === "txf") {
+                throw startRefusal(what, "TxFlow has no trading in perp-cli", unsupported("txflow", "trading", "TxFlow is integrated through an unofficial read-only API (market data only)", "Trade on the TxFlow website"));
+            }
+            // Any other registered venue without the trading role (Variational, GRVT, Extended: read-only in this version).
+            const venueId = id === undefined ? null : tryResolveVenueId(id);
+            if (venueId !== null && !getVenue(venueId).roles.includes("trading")) {
+                const def = getVenue(venueId);
+                throw startRefusal(what, `${def.displayName} has no trading in perp-cli`, roleUnsupported(def, "trading"));
+            }
+        }
     }
     if (!hasTmux()) {
         throw new Error("tmux is required for background jobs. Install with: brew install tmux");

package/dist/landing.d.ts

@@ -5,6 +5,8 @@ export type LandingExchangeStatus = {
     exchange: string;
     /** Venue has no account API — rendered as market data only. */
     marketDataOnly?: boolean;
+    /** Venue is read through an undocumented API (VenueDefinition.apiStatus) — labelled "unofficial API". */
+    unofficialApi?: boolean;
     ok: boolean;
     equity: number;
     positions: number;

package/dist/landing.js

@@ -25,7 +25,7 @@ export function renderLandingExchangeLine(status, asterAgentMissing) {
         return `    ${chalk.yellow("⚙")} ${chalk.cyan(exchangeLabel(status.exchange).padEnd(14))} ${chalk.yellow("agent required")} ${chalk.gray("→ perp wallet agent approve aster")}`;
     }
     if (status.marketDataOnly) {
-        return `    ${chalk.gray("◇")} ${chalk.cyan(exchangeLabel(status.exchange).padEnd(14))} ${chalk.gray("market data only")}`;
+        return `    ${chalk.gray("◇")} ${chalk.cyan(exchangeLabel(status.exchange).padEnd(14))} ${chalk.gray("market data only")}${status.unofficialApi ? chalk.yellow(" (unofficial API)") : ""}`;
     }
     const icon = status.ok ? chalk.green("●") : chalk.red("○");
     const equity = status.ok

package/dist/mcp-pacifica-earn.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read-only MCP tools for Pacifica Print and vaults (unauthenticated GETs; nothing is signed).
+ * Print deposits / ends and vault deposits / withdrawals are NOT exposed over MCP: the server has
+ * no money-moving deposit / withdraw tools (funds moves are CLI-only, `perp funds …`), and these
+ * follow the same rule — use `perp print deposit` / `perp vault deposit|withdraw` (with --dry-run).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Network } from "./exchanges/venue-types.js";
+export declare function registerPacificaEarnMcpTools(server: McpServer, network: Network, ok: (data: unknown, meta?: Record<string, unknown>) => string, errOf: (e: unknown, meta?: Record<string, unknown>) => string): void;

package/dist/mcp-pacifica-earn.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { PacificaClient } from "./pacifica/client.js";
+import { fetchPrintGames, fetchPrintHistory, fetchPrintMarket, fetchPrintPositions, findPrintGame, quotePrintOrder } from "./exchanges/pacifica-print.js";
+import { DEPOSIT_WHITELIST_API_STATUS, fetchDepositWhitelist, fetchVaults, findVault, heldShares, withdrawWindowAt } from "./exchanges/pacifica-vaults.js";
+export function registerPacificaEarnMcpTools(server, network, ok, errOf) {
+    const client = () => new PacificaClient({ network });
+    const run = async (meta, f) => {
+        try {
+            return { content: [{ type: "text", text: ok(await f(), meta) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: errOf(e, meta) }], isError: true };
+        }
+    };
+    const address = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, "base58 Solana address");
+    server.tool("pacifica_print_products", "Pacifica Print products (read-only): game id (e.g. BTC_24H, BTC_7D, BTC_1M), cycle length in days, max leverage, deposit caps, allowed target distance from mark. Print = a strike order that earns a premium each cycle; while resting it fills / is liquidated only at a cycle checkpoint, after a fill it is an ordinary perp position (continuous liquidation).", {}, async () => run({ exchange: "pacifica" }, async () => fetchPrintGames(client())));
+    server.tool("pacifica_print_quote", "Validate a Pacifica Print order and preview it (read-only, nothing signed): notional, size on fill, docs-formula liquidation price (an outer bound — a liquidation was observed earlier in one live case; venue trigger unpublished), max loss (deposit + premiums), lock period. The premium is not quoted (the venue's preview is a signed request). Placing the order is CLI-only: perp -e pacifica print deposit … (supports --dry-run).", {
+        game: z.string().describe("Print product, e.g. BTC_24H"),
+        direction: z.enum(["long", "short"]).describe("long = target below mark, short = target above mark"),
+        deposit: z.string().describe("USDC deposit, min 10"),
+        strike: z.string().describe("Target price (on the market tick)"),
+        leverage: z.string().describe("Whole-number leverage 1 … product max"),
+        cycles: z.number().int().optional().describe("Cycles 1 … 1000; omit = roll until cancelled"),
+    }, async ({ game, direction, deposit, strike, leverage, cycles }) => run({ exchange: "pacifica", game }, async () => {
+        const c = client();
+        const g = findPrintGame(await fetchPrintGames(c), game);
+        return quotePrintOrder(g, { game: g.game, direction, deposit, strikePrice: strike, leverage, cycles: cycles ?? null }, await fetchPrintMarket(c, g.asset));
+    }));
+    server.tool("pacifica_print_positions", "Pacifica Print orders of an account (read-only): current orders, or with history=true every order (paginated: limit / cursor). Status printing | cancelling | filled | liquidated | cancelled | completed | ended.", {
+        account: address.describe("Pacifica account (Solana address)"),
+        history: z.boolean().optional().describe("true = every order (history_summary), default false = current orders"),
+        limit: z.number().int().positive().optional(),
+        cursor: z.string().optional(),
+    }, async ({ account, history, limit, cursor }) => run({ exchange: "pacifica", account }, async () => {
+        if (history !== true)
+            return { account, positions: await fetchPrintPositions(client(), account) };
+        const page = await fetchPrintHistory(client(), account, { limit: limit ?? null, cursor: cursor ?? null });
+        return { account, positions: page.items, hasMore: page.hasMore, nextCursor: page.nextCursor };
+    }));
+    server.tool("pacifica_vaults", "Pacifica vaults (API: lakes), read-only. Without vault: every vault (TVL, NAV per share, fee, lock-up, withdrawal window, config); with account: plus that account's shares. With vault (address, or a nickname matching exactly one vault — an ambiguous nickname is INVALID_PARAMS listing the candidates): one vault plus live account equity, positions, deposit whitelist (unofficial endpoint, advisory) and whether withdrawals are open now. APY is not published (null). Deposits / withdrawals are CLI-only: perp -e pacifica vault deposit|withdraw (supports --dry-run).", {
+        vault: z.string().optional().describe("Vault address or exact nickname"),
+        account: address.optional().describe("Include this account's shares"),
+    }, async ({ vault, account }) => run({ exchange: "pacifica" }, async () => {
+        const c = client();
+        const vaults = await fetchVaults(c, account ?? null);
+        if (vault === undefined)
+            return vaults;
+        const v = findVault(vaults, vault);
+        const [acct, positions, whitelist] = await Promise.all([c.getAccount(v.address), c.getPositions(v.address), fetchDepositWhitelist(c, v.address).catch(() => null)]);
+        return {
+            ...v,
+            ...(account !== undefined ? { holding: heldShares(v, account) } : {}),
+            live: { accountEquity: acct.account_equity ?? null, availableToWithdraw: acct.available_to_withdraw ?? null, positions: positions.map((p) => ({ symbol: p.symbol, side: p.side, amount: p.amount, entryPrice: p.entry_price })) },
+            depositWhitelist: { apiStatus: DEPOSIT_WHITELIST_API_STATUS, addresses: whitelist },
+            withdrawWindow: withdrawWindowAt(v.config, Date.now()),
+        };
+    }));
+}