perp-cli 0.14.2 → 0.15.0

package/dist/commands/arb.js

@@ -1,99 +1,13 @@
 import { makeTable, formatUsd, formatPercent, formatPnl, printJson, jsonOk, withJsonErrors, logSettledRejections } from "../utils.js";
 import chalk from "chalk";
 import { toHourlyRate, annualizeHourlyRate, estimateHourlyFundingFromHourly } from "../funding.js";
-import { fetchAllFundingRates, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
+import { fetchAllFundingRates, fetchCanonicalPriceGroups, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
 import { saveFundingSnapshot, getHistoricalRates, getCompoundedAnnualReturn, getExchangeCompoundingHours, } from "../funding-history.js";
 import { getVenue, listVenuesWithRole, tryResolveVenueId } from "../exchanges/venue.js";
 import "../exchanges/venues/index.js";
-import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidAllMidsRaw, fetchLighterOrderBookDetailsRaw, } from "../shared-api.js";
+import { MAX_PRICE_DEVIATION_PCT } from "../exchanges/index.js";
+import { fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidAllMidsRaw, fetchLighterOrderBookDetailsRaw, } from "../shared-api.js";
 import { scanDexArb } from "../dex-asset-map.js";
-async function fetchPacificaRates() {
-    const assets = await fetchPacificaPrices();
-    return assets.map(p => ({
-        exchange: "pacifica",
-        symbol: p.symbol,
-        fundingRate: p.funding,
-        markPrice: p.mark,
-    }));
-}
-async function fetchHyperliquidRates() {
-    const assets = await fetchHyperliquidMeta();
-    return assets.map(a => ({
-        exchange: "hyperliquid",
-        symbol: a.symbol,
-        fundingRate: a.funding,
-        markPrice: a.markPx,
-    }));
-}
-async function fetchAsterRates() {
-    // SSOT rule #2: do NOT silently coerce missing markPrice / lastFundingRate
-    // to 0 — that would corrupt comparisons against other DEXs. Skip symbols
-    // whose Aster row is malformed instead. An endpoint failure PROPAGATES: the
-    // caller (handleBasisScan) runs every DEX under Promise.allSettled and reports
-    // the rejection on stderr — Aster is never silently absent from the scan.
-    const res = await fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex");
-    if (!res.ok)
-        throw new Error(`Aster premiumIndex HTTP ${res.status}`);
-    const premiums = await res.json();
-    if (!Array.isArray(premiums))
-        throw new Error("Aster premiumIndex returned a non-array response");
-    const out = [];
-    for (const p of premiums) {
-        const rawSym = String(p.symbol ?? "");
-        if (!rawSym.endsWith("USDT"))
-            continue;
-        const fundingRate = Number(p.lastFundingRate);
-        const markPrice = Number(p.markPrice);
-        if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0) {
-            continue;
-        }
-        out.push({
-            exchange: "aster",
-            symbol: rawSym.replace(/USDT$/, ""),
-            fundingRate,
-            markPrice,
-        });
-    }
-    return out;
-}
-async function fetchLighterRates() {
-    // SSOT rule #2: error must propagate. Caller (handleBasisScan) uses
-    // Promise.allSettled to keep multi-DEX comparison alive when one DEX is
-    // down, with explicit stderr logging.
-    const [details, funding] = await Promise.all([
-        fetchLighterOrderBookDetails(),
-        fetchLighterFundingRates(),
-    ]);
-    const priceMap = new Map(details.map(d => [d.marketId, d.lastTradePrice]));
-    const symMap = new Map(details.map(d => [d.marketId, d.symbol]));
-    const rates = [];
-    for (const fr of funding) {
-        const symbol = fr.symbol || symMap.get(fr.marketId);
-        if (!symbol)
-            continue;
-        // Prefer fr.markPrice; fall back to orderBook last-trade as documented
-        // price-source preference (NOT error fallback). Skip if neither resolves
-        // — never publish a 0 markPrice downstream.
-        const directMark = fr.markPrice;
-        const fallbackMark = priceMap.get(fr.marketId);
-        let markPrice;
-        if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
-            markPrice = directMark;
-        }
-        else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
-            markPrice = fallbackMark;
-        }
-        if (markPrice === undefined || !Number.isFinite(fr.rate))
-            continue;
-        rates.push({
-            exchange: "lighter",
-            symbol,
-            fundingRate: fr.rate,
-            markPrice,
-        });
-    }
-    return rates;
-}
 // annualize moved to ../funding.ts — use annualizeRate() / computeAnnualSpread()
 export function registerArbCommands(program, isJson, getAdapterForExchange) {
     const arb = program.command("arb").description("Funding rate arbitrage & basis trading");
@@ -291,12 +205,15 @@ function printSnapshotTable(snapshot) {
                 return r ? formatPercent(r.fundingRate) : chalk.gray("-");
             }),
             spreadColor(`${s.maxSpreadAnnual.toFixed(1)}%`), trend,
-            s.maxSpreadAnnual >= 5 ? `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}` : chalk.gray("-"),
+            s.maxSpreadAnnual >= 5 ? `${exAbbr(s.shortExchange)}>${exAbbr(s.longExchange)}${s.executable ? "" : chalk.gray(" (read-only)")}` : chalk.gray("-"),
             formatAvgRate(bestRate?.historicalAvg?.avg8h), formatAvgRate(bestRate?.historicalAvg?.avg24h), formatAvgRate(bestRate?.historicalAvg?.avg7d),
         ];
     });
-    console.log(makeTable(["Symbol", ...columns.map(v => v.displayName), "Spread", "24h", "Direction", "Avg 8h", "Avg 24h", "Avg 7d"], rows));
+    console.log(makeTable(["Symbol", ...columns.map(v => v.apiStatus.kind === "unofficial" ? `${v.displayName}*` : v.displayName), "Spread", "24h", "Direction", "Avg 8h", "Avg 24h", "Avg 7d"], rows));
     console.log(chalk.gray(`\n  ${snapshot.symbols.length} symbols compared across exchanges.\n`));
+    const unofficial = columns.filter(v => v.apiStatus.kind === "unofficial");
+    if (unofficial.length > 0)
+        console.log(chalk.yellow(`  * ${unofficial.map(v => v.displayName).join(", ")}: UNOFFICIAL API (undocumented, read-only; may change or break). Unverified funding — shown only with --include-unverified.\n`));
 }
 function printFundingExchangeStatus(snapshot) {
     const statuses = Object.entries(snapshot.exchangeStatus).map(([ex, status]) => {
@@ -317,7 +234,7 @@ function printDetailedComparison(comparison) {
     }
     const spreadColor = comparison.maxSpreadAnnual >= 30 ? chalk.green.bold : comparison.maxSpreadAnnual >= 10 ? chalk.yellow : chalk.white;
     console.log(`\n  Max Spread:     ${spreadColor(`${comparison.maxSpreadAnnual.toFixed(1)}%`)} annual`);
-    console.log(`  Direction:      Long ${exAbbr(comparison.longExchange)} / Short ${exAbbr(comparison.shortExchange)}`);
+    console.log(`  Direction:      Long ${exAbbr(comparison.longExchange)} / Short ${exAbbr(comparison.shortExchange)}${comparison.executable ? "" : chalk.yellow(`  — not executable: ${comparison.readOnlyLegs.join(", ")} is read-only in perp-cli`)}`);
     console.log(`  Est. Income:    $${comparison.estHourlyIncomeUsd.toFixed(4)}/hr per $1K notional\n`);
 }
 // registerFundingSubcommands removed — use 'arb scan --rates/--compare/--history/--positions' instead
@@ -325,9 +242,13 @@ function printDetailedComparison(comparison) {
 /** One-line stderr notice when rows of unverified-funding venues are shown (--include-unverified). */
 function warnUnverifiedFunding(rates) {
     const venues = [...new Set(rates.filter(r => !r.fundingVerified).map(r => r.exchange))];
-    if (venues.length === 0)
-        return;
-    process.stderr.write(`[warn] ${venues.join(", ")}: funding rates are UNVERIFIED (unit not confirmed against funding payments; annualized values overstate venues whose funding accrues only during market hours). Shown on request — not for trading decisions.\n`);
+    if (venues.length > 0) {
+        process.stderr.write(`[warn] ${venues.join(", ")}: funding rates are UNVERIFIED (unit not confirmed against funding payments; annualized values overstate venues whose funding accrues only during market hours). Shown on request — not for trading decisions.\n`);
+    }
+    const unofficial = [...new Set(rates.filter(r => r.apiStatus === "unofficial").map(r => r.exchange))];
+    if (unofficial.length > 0) {
+        process.stderr.write(`[warn] ${unofficial.join(", ")}: read through an UNOFFICIAL API (undocumented; may change or be blocked without notice). Rows carry apiStatus "unofficial".\n`);
+    }
 }
 export async function handleRates(isJson, opts) {
     const minSpread = parseFloat(opts.minSpread);
@@ -373,59 +294,52 @@ export async function handleRates(isJson, opts) {
     printSnapshotTable(snapshot);
     printFundingExchangeStatus(snapshot);
 }
+/**
+ * Cross-venue price basis — a PRICE comparison, independent of funding.
+ *
+ * Venue scope: every venue with the "trading" role (both legs must be executable), whether or not
+ * its funding rate is verified; market-data-only venues (TxFlow, unofficial API) are out. Prices
+ * come from each venue's market directory and are grouped by `canonical` symbol with the funding
+ * scan's guards (fetchCanonicalPriceGroups): unclassified / ambiguous tickers have no canonical and
+ * never pair, and a venue whose mark deviates more than MAX_PRICE_DEVIATION_PCT from the group
+ * median is dropped. The chosen cheap / rich pair must itself agree within MAX_PRICE_DEVIATION_PCT:
+ * a wider gap is a different asset under the same ticker (BB on Lighter 8.50 vs Aster 0.0091).
+ * A venue that fails is reported on stderr and is absent from the scan, never silently empty.
+ */
 export async function handleBasisScan(isJson, opts) {
     if (!isJson())
         console.log(chalk.cyan("  Fetching prices for basis calculation...\n"));
-    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
-    // alive when one DEX errors out, while rejection reasons get logged to
-    // stderr (explicit failure, never silent [] downgrade).
-    const settled = await Promise.allSettled([
-        fetchPacificaRates(),
-        fetchHyperliquidRates(),
-        fetchLighterRates(),
-        fetchAsterRates(),
-    ]);
-    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter", "aster"], "basis-scan");
-    const pacRates = settled[0].status === "fulfilled" ? settled[0].value : [];
-    const hlRates = settled[1].status === "fulfilled" ? settled[1].value : [];
-    const ltRates = settled[2].status === "fulfilled" ? settled[2].value : [];
-    const astRates = settled[3].status === "fulfilled" ? settled[3].value : [];
-    const exchangePrices = new Map();
     const filterSymbol = opts.symbol?.toUpperCase();
-    for (const r of [...pacRates, ...hlRates, ...ltRates, ...astRates]) {
-        if (r.markPrice <= 0)
-            continue;
-        if (filterSymbol && r.symbol.toUpperCase() !== filterSymbol)
-            continue;
-        if (!exchangePrices.has(r.symbol))
-            exchangePrices.set(r.symbol, new Map());
-        exchangePrices.get(r.symbol).set(r.exchange, r.markPrice);
-    }
+    const snapshot = await fetchCanonicalPriceGroups(listVenuesWithRole("trading"), {
+        symbols: filterSymbol !== undefined ? [filterSymbol] : undefined, tag: "basis-scan",
+    });
+    for (const [venue, msg] of Object.entries(snapshot.exchangeErrors))
+        console.error(`[basis-scan] ${venue} fetch failed: ${msg}`);
     const opps = [];
-    for (const [symbol, prices] of exchangePrices.entries()) {
-        if (prices.size < 2)
+    for (const [symbol, priced] of snapshot.groups) {
+        if (priced.length < 2)
             continue;
-        let minEx = "", maxEx = "", minPrice = Infinity, maxPrice = 0;
-        for (const [ex, price] of prices) {
-            if (price < minPrice) {
-                minPrice = price;
-                minEx = ex;
-            }
-            if (price > maxPrice) {
-                maxPrice = price;
-                maxEx = ex;
-            }
+        let min = priced[0], max = priced[0];
+        for (const r of priced) {
+            if (r.markPrice < min.markPrice)
+                min = r;
+            if (r.markPrice > max.markPrice)
+                max = r;
         }
-        if (minEx === maxEx)
+        if (min.exchange === max.exchange)
             continue;
-        const diff = maxPrice - minPrice;
-        const avgPrice = (maxPrice + minPrice) / 2;
+        const diff = max.markPrice - min.markPrice;
+        const avgPrice = (max.markPrice + min.markPrice) / 2;
         const pctDiff = (diff / avgPrice) * 100;
+        if (!(pctDiff <= MAX_PRICE_DEVIATION_PCT)) {
+            console.error(`[basis-scan] excluded ${symbol} ${min.exchange}↔${max.exchange}: mark gap ${pctDiff.toFixed(1)}% > ${MAX_PRICE_DEVIATION_PCT}% (likely a different asset with the same ticker)`);
+            continue;
+        }
         if (pctDiff * 365 >= parseFloat(opts.minBasis)) {
             const priceObj = {};
-            for (const [ex, p] of prices)
-                priceObj[ex] = p;
-            opps.push({ symbol, prices: priceObj, priceDiff: diff, pctDiff, buyOn: minEx, sellOn: maxEx });
+            for (const r of priced)
+                priceObj[r.exchange] = r.markPrice;
+            opps.push({ symbol, prices: priceObj, priceDiff: diff, pctDiff, buyOn: min.exchange, sellOn: max.exchange });
         }
     }
     opps.sort((a, b) => b.pctDiff - a.pctDiff);
@@ -439,12 +353,12 @@ export async function handleBasisScan(isJson, opts) {
     console.log(chalk.gray("  Strategy: Buy cheap, sell expensive, profit from convergence.\n"));
     const rows = opps.map((o) => [
         chalk.white.bold(o.symbol),
-        o.prices.pacifica ? `$${formatUsd(o.prices.pacifica)}` : chalk.gray("-"),
-        o.prices.hyperliquid ? `$${formatUsd(o.prices.hyperliquid)}` : chalk.gray("-"),
-        o.prices.lighter ? `$${formatUsd(o.prices.lighter)}` : chalk.gray("-"),
+        `$${formatUsd(o.prices[o.buyOn])}`,
+        `$${formatUsd(o.prices[o.sellOn])}`,
         `$${formatUsd(o.priceDiff)}`, `${o.pctDiff.toFixed(4)}%`, chalk.green(o.buyOn), chalk.red(o.sellOn),
+        chalk.gray(String(Object.keys(o.prices).length)),
     ]);
-    console.log(makeTable(["Symbol", "Pacifica", "Hyperliquid", "Lighter", "Diff", "Basis %", "Buy On", "Sell On"], rows));
+    console.log(makeTable(["Symbol", "Buy Price", "Sell Price", "Diff", "Basis %", "Buy On", "Sell On", "Venues"], rows));
 }
 export async function handleDexScan(isJson, opts) {
     if (!isJson())
@@ -497,9 +411,13 @@ export async function handleCompare(isJson, symbol, includeUnverified = false) {
     if (comparison)
         warnUnverifiedFunding(comparison.rates);
     if (!comparison) {
+        // A venue ticker whose canonical symbol differs (Variational US500-PERP = SPY): say where to look.
+        const hint = (await import("../exchanges/variational/public.js")).canonicalHintFor(symbol);
         if (isJson())
-            return printJson(jsonOk({ symbol: symbol.toUpperCase(), available: false }));
+            return printJson(jsonOk({ symbol: symbol.toUpperCase(), available: false, ...(hint !== null ? { hint } : {}) }));
         console.log(chalk.gray(`  ${symbol.toUpperCase()} not found on at least 2 exchanges.\n`));
+        if (hint !== null)
+            console.log(chalk.yellow(`  Hint: ${hint}\n`));
         return;
     }
     if (isJson())
@@ -594,7 +512,7 @@ export async function handleFundingPositions(isJson, getAdapterForExchange, opts
                     }
                     const sz = Math.abs(Number(pos.size));
                     const nu = sz * mk;
-                    const fh = fd ? fd.fundingHours : null; /* market basis first (§10.1) */
+                    const fh = fd ? fd.fundingHours : null; /* market basis first */
                     const hr = fh !== null ? fr / fh : toHourlyRate(fr, exchange);
                     const ap = annualizeHourlyRate(hr);
                     const hp = estimateHourlyFundingFromHourly(hr, nu, pos.side);

package/dist/commands/bot.js

@@ -419,7 +419,7 @@ export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJ
         }
         console.log();
     });
-    // ── quarantine (design §12.3): positions the bot refuses to touch until a human clears them ──
+    // ── quarantine: positions the bot refuses to touch until a human clears them ──
     bot
         .command("quarantine")
         .description("List quarantined symbols (unknown / unverified order outcome or unhedged leg) — blocked for every bot strategy, arb exec and arb auto (~/.perp/bot-quarantine.json)")

package/dist/commands/builder.js

@@ -283,7 +283,7 @@ export function registerWalletBuilderCommands(wallet, isJson, getAdapterForExcha
         .action(async (venueArg, _opts, cmd) => {
         await withJsonErrors(isJson(), async () => {
             const network = networkOf(cmd);
-            const venues = venueArg !== undefined ? [getVenue(venueArg).id] : [...builderFeeVenues(), ...["lighter", "lighter-rh", "arcus"]];
+            const venues = venueArg !== undefined ? [getVenue(venueArg).id] : [...builderFeeVenues(), ...["lighter", "lighter-rh", "arcus", "risex", "txflow", "variational", "grvt", "extended"]];
             const rows = [];
             for (const v of venues) {
                 const configured = builderTargetOf(loadSettings().builder, v) !== null;

package/dist/commands/funds.js

@@ -7,7 +7,10 @@ import { registerFundsBridgeCommands } from "./bridge.js";
 import { registerFundsRebalanceCommands } from "./rebalance.js";
 import { PerpError, isConnectFailure, isDefiniteOrderFailure, isTransportFailure, orderOutcomeUnknown, parsePositiveDecimal } from "../errors.js";
 import { cliCredentialOptsFrom, requireMasterWallet } from "../config.js";
-import { getVenue, requireCapabilities, READ_ONLY_CREDENTIALS } from "../exchanges/venue.js";
+import { getVenue, requireCapabilities, roleUnsupported, READ_ONLY_CREDENTIALS } from "../exchanges/venue.js";
+import { RISEX_APP_URL, RISEX_FUNDS_APP_ONLY } from "../exchanges/venues/risex.js";
+import { VARIATIONAL_READ_ONLY_REMEDIATION } from "../exchanges/venues/variational.js";
+import { EXTENDED_READ_ONLY_REMEDIATION } from "../exchanges/venues/extended.js";
 import { unsupported } from "../exchanges/trading-v2.js";
 import { registerOnchainFundsCommands } from "./funds-onchain.js";
 import { QFEX_BANKER_NETWORK, QFEX_WITHDRAW_DISABLED, QFEX_WITHDRAW_ENABLED, QFEX_WITHDRAW_NETWORK } from "../exchanges/venues/qfex.js";
@@ -857,6 +860,34 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
             throw err;
         }
     });
+    supportsDryRun(faucet.command("risex"))
+        .description("[testnet tooling] Get the RISEx testnet faucet's 1000 test USDC (once per wallet; also registers the account; refused on mainnet; supports --dry-run). Refused while RISEx is read-only (trading in a later release)")
+        .action(async () => {
+        // Gated with RISEx trading (read-only release): the faucet is a venue write.
+        const risexDef = getVenue("risex");
+        if (!risexDef.roles.includes("trading"))
+            throw roleUnsupported(risexDef, "faucet");
+        const network = getNetwork();
+        if (network !== "testnet") {
+            throw unsupported("RISEx", `the test-USDC faucet on ${network}`, "the faucet exists only on testnet", "Run on testnet: perp -n testnet funds faucet risex");
+        }
+        const adapter = await getAdapterForExchange("risex");
+        const { RisexAdapter } = await import("../exchanges/risex/adapter.js");
+        if (!(adapter instanceof RisexAdapter))
+            throw new Error("risex venue did not produce a RisexAdapter");
+        const account = adapter.accountAddress();
+        if (isDryRun()) {
+            return printFundsPlan({ action: "deposit", venue: "risex", network, asset: "USDC (test)", amount: "1000", method: "testnet faucet POST /v1/account/deposit", account });
+        }
+        const res = await adapter.testnetFaucet();
+        logExecution({ type: "bridge", exchange: "risex", symbol: "USDC", side: "deposit", size: "1000", status: "success", dryRun: false, meta: { action: "faucet", network, account } });
+        if (isJson())
+            return printJson(jsonOk({ ...res, account, amount: "1000", network, method: "faucet" }));
+        console.log(chalk.green(`\n  RISEx testnet faucet: 1000 test USDC requested for ${account}`));
+        if (res.txHash !== null)
+            console.log(`  Tx: ${res.txHash}`);
+        console.log();
+    });
     // ═══════════════════════════════════════════════════════
     //  WITHDRAW
     // ═══════════════════════════════════════════════════════
@@ -1049,7 +1080,7 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
             throw err;
         }
     });
-    // ── Arcus — uniform surface (design §13.1): same <amount> + --to,
+    // ── Arcus — uniform surface: same <amount> + --to,
     //    same jsonOk(result), global --dry-run plans without sending. ──
     // Ondo Perps: the API does not allow withdrawals (address-book destinations only; adding one is
     // refused for API keys). The command stays so the refusal is explicit — also under --dry-run.
@@ -1059,6 +1090,42 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
         .action(async () => {
         throw unsupported("Ondo Perps", "withdraw", "the Ondo Perps API does not allow withdrawals", "Withdraw from the Ondo Perps web app");
     });
+    // RISEx: deposits / withdrawals are app-only (owner decision). The commands stay so the refusal
+    // is explicit — also under --dry-run, before any credential or request.
+    supportsDryRun(withdraw.command("risex [amount]"))
+        .description(`Not available: RISEx withdrawals are done in the RISEx app (${RISEX_APP_URL}) — refused, also with --dry-run`)
+        .option("--to <address>", "Ignored — perp-cli does not move RISEx funds")
+        .action(async () => {
+        throw unsupported("risex", "withdraw", RISEX_FUNDS_APP_ONLY.reason, RISEX_FUNDS_APP_ONLY.remediation);
+    });
+    // TxFlow: market data only (unofficial read-only API).
+    supportsDryRun(withdraw.command("txflow [amount]"))
+        .description("Not available: TxFlow is market data only in perp-cli (unofficial read-only API) — refused")
+        .option("--to <address>", "Ignored")
+        .action(async () => {
+        throw roleUnsupported(getVenue("txflow"), "withdraw");
+    });
+    // Variational: read-only (market data) in perp-cli; no public trading API yet.
+    supportsDryRun(withdraw.command("variational [amount]"))
+        .description("Not available: Variational is read-only (market data) in perp-cli — refused")
+        .option("--to <address>", "Ignored")
+        .action(async () => {
+        throw roleUnsupported(getVenue("variational"), "withdraw");
+    });
+    // GRVT: read-only (market data) in this version.
+    supportsDryRun(withdraw.command("grvt [amount]"))
+        .description("Not available: GRVT is read-only (market data) in this version — refused, also with --dry-run")
+        .option("--to <address>", "Ignored")
+        .action(async () => {
+        throw roleUnsupported(getVenue("grvt"), "withdraw");
+    });
+    // Extended: market data only in this version.
+    supportsDryRun(withdraw.command("extended [amount]"))
+        .description("Not available: Extended is market data only in this version — refused, also with --dry-run")
+        .option("--to <address>", "Ignored")
+        .action(async () => {
+        throw roleUnsupported(getVenue("extended"), "withdraw");
+    });
     for (const venueId of ["arcus"]) {
         const def = getVenue(venueId);
         const asset = withdrawAssetOf(def);
@@ -1128,7 +1195,7 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
             }
         });
     }
-    // ── QFEX (design §14.6, §14.12 #8) — custodial; deposit = address display, withdraw = banker POST
+    // ── QFEX — custodial; deposit = address display, withdraw = banker POST
     //    gated by settings.withdraw.qfex inside QfexAdapter.withdraw(); switched off (QFEX_WITHDRAW_ENABLED). ──
     /** QFEX adapter for the active network — the default imported key, or the one named by --agent. */
     const qfexAdapterFor = async (agentName) => {
@@ -1206,6 +1273,31 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
             throw err;
         }
     });
+    supportsDryRun(deposit.command("risex [amount]"))
+        .description(`Not available: RISEx deposits are done in the RISEx app (${RISEX_APP_URL}) — refused, also with --dry-run`)
+        .action(async () => {
+        throw unsupported("risex", "deposit", RISEX_FUNDS_APP_ONLY.reason, RISEX_FUNDS_APP_ONLY.remediation);
+    });
+    supportsDryRun(deposit.command("txflow [amount]"))
+        .description("Not available: TxFlow is market data only in perp-cli (unofficial read-only API) — refused")
+        .action(async () => {
+        throw roleUnsupported(getVenue("txflow"), "deposit");
+    });
+    supportsDryRun(deposit.command("variational [amount]"))
+        .description("Not available: Variational is read-only (market data) in perp-cli — refused")
+        .action(async () => {
+        throw roleUnsupported(getVenue("variational"), "deposit");
+    });
+    supportsDryRun(deposit.command("grvt [amount]"))
+        .description("Not available: GRVT is read-only (market data) in this version — refused, also with --dry-run")
+        .action(async () => {
+        throw roleUnsupported(getVenue("grvt"), "deposit");
+    });
+    supportsDryRun(deposit.command("extended [amount]"))
+        .description("Not available: Extended is market data only in this version — refused, also with --dry-run")
+        .action(async () => {
+        throw roleUnsupported(getVenue("extended"), "deposit");
+    });
     supportsDryRun(deposit.command("qfex"))
         .description("Show the QFEX deposit address for USDC on Arbitrum One (perp-cli sends nothing — transfer from your own wallet; supports --dry-run)")
         // --chain, not --network: the root -n/--network (mainnet | testnet) would swallow a subcommand --network.
@@ -1258,6 +1350,14 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
         if (isNaN(amountNum) || amountNum <= 0)
             throw new Error("Invalid amount");
         const exchangeOpt = program.opts().exchange;
+        // -e names a venue this command cannot move funds on: refuse instead of transferring on Hyperliquid.
+        if (exchangeOpt !== undefined) {
+            const def = getVenue(exchangeOpt);
+            if (!def.roles.includes("account"))
+                throw roleUnsupported(def, "transfer");
+            if (def.id === "risex")
+                throw unsupported("risex", "transfer", RISEX_FUNDS_APP_ONLY.reason, RISEX_FUNDS_APP_ONLY.remediation);
+        }
         if (exchangeOpt !== undefined && getVenue(exchangeOpt).id === "qfex") {
             if (isDryRun()) {
                 return printFundsPlan({ action: "transfer", venue: "qfex", network: getNetwork(), asset: "USDC", amount, from: opts.from ?? "the key's account", destination });
@@ -1349,6 +1449,11 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
                     qfex: { chain: "Arbitrum", token: "USDC", min: null, method: "address display only: perp funds deposit qfex, then send USDC from your wallet" },
                     aster: { chain: "BNB Chain (default) / Arbitrum", token: "USDT (default) / USDC", min: null, gas: "BNB / Arbitrum ETH", method: "approve + vault depositFor(token, forAddress, amount, broker 1) (mainnet only)", command: "perp funds deposit aster <amount> [--chain bsc|arbitrum] [--asset USDT|USDC]" },
                     ondo: { chain: "Arbitrum (default) / Ethereum", token: "USDC", min: null, gas: "ETH", method: "USDC transfer to the account's funding address (mainnet only)", command: "perp funds deposit ondo <amount> [--chain arbitrum|ethereum] [--probe <amount>]" },
+                    risex: { supported: false, note: `${RISEX_FUNDS_APP_ONLY.reason} — ${RISEX_FUNDS_APP_ONLY.remediation}`, testnet: getVenue("risex").roles.includes("trading") ? "perp -n testnet funds faucet risex (1000 test USDC, once)" : null },
+                    txflow: { supported: false, note: "TxFlow is market data only in perp-cli (unofficial read-only API)" },
+                    variational: { supported: false, note: VARIATIONAL_READ_ONLY_REMEDIATION },
+                    grvt: { supported: false, note: "GRVT is read-only (market data) in this version; trading is planned for a later release" },
+                    extended: { supported: false, note: EXTENDED_READ_ONLY_REMEDIATION },
                 },
                 withdraw: {
                     pacifica: { chain: "Solana", token: "USDC", speed: "~10s", fee: "none" },
@@ -1360,6 +1465,11 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork, g
                         ? { chain: chainLabel(QFEX_WITHDRAW_NETWORK), token: "USDC", command: "perp funds withdraw qfex <amount> --to <allowlisted address>", gate: "settings withdraw.qfex (allowlist, maxPerTx, maxPerDay)", note: "needs a key with the \"Deposit and withdraw\" permission" }
                         : { supported: false, note: `${QFEX_WITHDRAW_DISABLED.reason} — ${QFEX_WITHDRAW_DISABLED.remediation}` },
                     arcus: { chain: "Robinhood Chain", token: "USDG", command: "perp funds withdraw arcus <amount>" },
+                    risex: { supported: false, note: `${RISEX_FUNDS_APP_ONLY.reason} — ${RISEX_FUNDS_APP_ONLY.remediation}` },
+                    txflow: { supported: false, note: "TxFlow is market data only in perp-cli (unofficial read-only API)" },
+                    variational: { supported: false, note: VARIATIONAL_READ_ONLY_REMEDIATION },
+                    grvt: { supported: false, note: "GRVT is read-only (market data) in this version; trading is planned for a later release" },
+                    extended: { supported: false, note: EXTENDED_READ_ONLY_REMEDIATION },
                     aster: { chain: "BNB Chain (default) / Arbitrum", token: "USDT (default) / USDC", command: "perp funds withdraw aster <amount> [--chain bsc|arbitrum] [--asset USDT|USDC]", fee: "POST /fapi/v3/aster/user-withdraw-info (taken from the amount)", requires: "mainnet; API wallet approved with --can-withdraw --ip-whitelist; destination = the account's own address" },
                 },
             }));

package/dist/commands/init.d.ts

@@ -47,7 +47,7 @@ export interface SetupSettingsChange {
 export declare function applySetupSettings(change: SetupSettingsChange): Settings;
 /** Real follow-up commands for the configured venues (all exist in this CLI). */
 export declare function nextStepCommands(venues: VenueId[], network: Network): string[];
-/** Plain-language slippage explanation (design §13.2, §13.10 #3). */
+/** Plain-language slippage explanation. */
 export declare function slippageExplanation(venues: VenueId[]): string[];
 export type AgentStepResult = {
     venue: VenueId;

package/dist/commands/init.js

@@ -9,8 +9,9 @@ import { PerpError, classifyError } from "../errors.js";
 import { jsonOk, jsonError, printJson } from "../utils.js";
 import { resolvePassphrase } from "../agent-wallet/passphrase.js";
 import { loadOws } from "../signer/ows-loader.js";
-import { getVenue, listVenuesWithRole, networkConfig, tryResolveVenueId } from "../exchanges/venue.js";
+import { getVenue, listVenuesWithRole, networkConfig, roleUnsupported, tryResolveVenueId } from "../exchanges/venue.js";
 import "../exchanges/venues/index.js";
+import { VARIATIONAL_READ_ONLY_REMEDIATION } from "../exchanges/venues/variational.js";
 import { maxDefaultSlippageBps, parseSlippageSettingBps } from "../exchanges/slippage.js";
 import { agentApproveUnsupportedReason, approveVenueAgent, assertLighterSlot, isLighterFamilyVenue, deprecatedPassphraseOption, printApproveOutcome, promptHidden, verifyVenueAgent, warnDeprecatedPassphrase, } from "./agent.js";
 import { importOwsWallet } from "./wallet.js";
@@ -127,7 +128,11 @@ export function setupVenues() {
 /** Resolve one venue id/alias for setup: must be a trading venue with an environment on `network`. */
 export function resolveSetupVenue(input, network) {
     const id = tryResolveVenueId(input.trim());
-    if (id === null || !getVenue(id).roles.includes("trading")) {
+    // A registered venue without the trading role (release-gated RISEx, market-data-only TxFlow /
+    // Variational / GRVT) is a capability refusal, not an unknown name.
+    if (id !== null && !getVenue(id).roles.includes("trading"))
+        throw roleUnsupported(getVenue(id), "setup");
+    if (id === null) {
         throw new PerpError("INVALID_PARAMS", `Unknown trading venue "${input}"`, {
             remediation: `Use one of: ${setupVenues().map(v => v.id).join(", ")}`,
         });
@@ -177,7 +182,7 @@ export function applySetupSettings(change) {
 }
 /** Agent names already registered for `venue` on `network` in settings. */
 function registeredAgentNames(venue, network) {
-    if (venue === "ondo" || venue === "arcus" || venue === "qfex") {
+    if (venue === "ondo" || venue === "arcus" || venue === "qfex" || venue === "risex") {
         const map = loadSettings().agents?.[venue];
         return map ? Object.values(map).filter(m => m.network === network).map(m => m.agentName) : [];
     }
@@ -186,11 +191,11 @@ function registeredAgentNames(venue, network) {
 function rotateHint(venue) {
     if (venue === "qfex")
         return "perp wallet agent import qfex --replace";
-    return venue === "ondo" || venue === "arcus"
+    return venue === "ondo" || venue === "arcus" || venue === "risex"
         ? `perp wallet agent approve ${venue} --rotate`
         : `perp wallet agent rotate ${venue}`;
 }
-/** Why the wizard cannot register an agent for `venue` on `network`; null when it can (uniform wording, design §13.6). */
+/** Why the wizard cannot register an agent for `venue` on `network`; null when it can (uniform wording). */
 function approveBlocker(venue, network) {
     const reason = agentApproveUnsupportedReason(venue, network, "approve");
     return reason === null ? null : `${getVenue(venue).displayName} agent management on ${network} not supported — ${reason}`;
@@ -215,7 +220,7 @@ export function nextStepCommands(venues, network) {
     cmds.push("perp settings show");
     return cmds;
 }
-/** Plain-language slippage explanation (design §13.2, §13.10 #3). */
+/** Plain-language slippage explanation. */
 export function slippageExplanation(venues) {
     const lines = [
         "Market orders are sent as immediate-or-cancel (IOC) limit orders. The limit price is the",
@@ -260,6 +265,19 @@ function signingSummary(p, master) {
             return ["No signature. Your Ondo API key is stored encrypted in ~/.perp/ondo-agents/ and checked with one read-only account request."];
         case "qfex":
             return ["No signature. Your QFEX API key is stored encrypted in ~/.perp/qfex-agents/ and checked with read-only requests."];
+        case "risex":
+            return [
+                `EIP-712 RegisterSigner signed by master EVM ${master.evm} (+ VerifySigner by the new signer): registers a session signer (${expiry}).`,
+                `Then the new signer signs DisablePermission for every permission except trading, and ${master.evm} sends those transactions ON-CHAIN on RISE chain (needs RISE-chain ETH for gas): the signer can trade but never move funds, and only the master could re-enable a permission.`,
+            ];
+        case "txflow":
+            return ["Nothing — TxFlow is market data only (unofficial read-only API)."];
+        case "variational":
+            return [`Nothing — ${VARIATIONAL_READ_ONLY_REMEDIATION}.`];
+        case "grvt":
+            return ["Nothing — GRVT is read-only (market data) in this version; trading is planned for a later release."];
+        case "extended":
+            return ["Nothing — Extended is read-only (market data) in this version; trading is planned for a later release."];
     }
 }
 function failed(venue, err) {
@@ -944,7 +962,9 @@ export async function runNonInteractiveSetup(opts) {
         let defaultVenue = null;
         if (defaultRaw !== undefined) {
             const id = tryResolveVenueId(defaultRaw);
-            if (id === null || !getVenue(id).roles.includes("trading")) {
+            if (id !== null && !getVenue(id).roles.includes("trading"))
+                throw roleUnsupported(getVenue(id), "setup");
+            if (id === null) {
                 throw new PerpError("INVALID_PARAMS", `Invalid --default-venue "${defaultRaw}"`, {
                     remediation: `Use one of: ${(venues.length > 0 ? venues : setupVenues().map(v => v.id)).join(", ")}`,
                 });