perp-cli 0.14.3 → 0.15.0

package/dist/cli-program.js

@@ -6,13 +6,15 @@ import { Command } from "commander";
 import { cliCredentialOptsFrom, hasCredentials, resolveCredentials } from "./config.js";
 import { PacificaAdapter } from "./exchanges/pacifica.js";
 import { HyperliquidAdapter } from "./exchanges/hyperliquid.js";
-import { getVenue, listVenues, resolveVenueId, READ_ONLY_CREDENTIALS } from "./exchanges/venue.js";
+import { getVenue, listVenues, resolveVenueId, roleUnsupported, tryResolveVenueId, READ_ONLY_CREDENTIALS } from "./exchanges/venue.js";
 import { registerAdapterNetwork } from "./exchanges/adapter-network.js";
 import "./exchanges/venues/index.js";
 import { PerpError } from "./errors.js";
 import { registerMarketCommands } from "./commands/market.js";
 import { registerAccountCommands } from "./commands/account.js";
 import { registerOutcomeCommands } from "./commands/outcome.js";
+import { registerOptionsCommands } from "./commands/options.js";
+import { registerPacificaEarnCommands } from "./commands/pacifica-earn.js";
 import { registerTradeCommands } from "./commands/trade.js";
 // manage commands now register under `wallet manage ...` via registerWalletCommands.
 // stream commands removed — WS feeds still used by dashboard/event-stream internally
@@ -86,6 +88,11 @@ export function landingData(program, version) {
     return {
         name: program.name(),
         version,
+        // Registry facts only (no reads): an "unofficial" venue is read through an undocumented API.
+        venues: listVenues().map(v => ({
+            id: v.id, displayName: v.displayName, roles: [...v.roles], apiStatus: v.apiStatus.kind,
+            note: v.apiStatus.kind === "unofficial" ? v.apiStatus.note : null,
+        })),
         usage: `${program.name()} [options] <command> [args] (add --json for one JSON document on stdout)`,
         help: `${program.name()} <command> --help`,
         commands: program.commands
@@ -131,9 +138,9 @@ export function buildProgram(opts) {
     });
     let _adapter = null;
     /**
-     * One adapter per `${venueId}:${network}:${wallet}:${hlDex}` (design §3 L1 cache key).
+     * One adapter per `${venueId}:${network}:${wallet}:${hlDex}`.
      * Every adapter is built by the venue definition's create(ctx) — the single
-     * creation path shared with the MCP server (design §10.2).
+     * creation path shared with the MCP server.
      */
     const _adapters = new Map();
     function cliCredentialOpts() {
@@ -147,7 +154,7 @@ export function buildProgram(opts) {
         const wallet = opts.ows ? `ows:${opts.ows}` : (opts.wallet ?? "default");
         return `${venue}:${network}:${wallet}:${hlDex ?? "-"}`;
     }
-    /** restrictedRegions notice: stderr, once per venue per process (design §9.1 #2 — warn, never block). */
+    /** restrictedRegions notice: stderr, once per venue per process (warn, never block). */
     const _restrictedWarned = new Set();
     function warnRestrictedRegions(def) {
         if (def.restrictedRegions.length === 0 || _restrictedWarned.has(def.id))
@@ -167,6 +174,10 @@ export function buildProgram(opts) {
                 remediation: `${def.id} is market-data only — use the funding/market public commands (e.g. perp arb scan)`,
             });
         }
+        // A market-data-only venue (TxFlow: unofficial read-only API) never gets a credentialed adapter:
+        // every account / trading / funds / bot path refuses here, before any credential or request.
+        if (!publicOnly && !def.roles.includes("account"))
+            throw roleUnsupported(def, "account");
         const network = currentNetwork();
         const hlDex = def.id === "hyperliquid" ? dex : null;
         const key = publicOnly ? `${def.id}:${network}:public:${hlDex ?? "-"}` : adapterCacheKey(def.id, network, hlDex);
@@ -246,6 +257,8 @@ export function buildProgram(opts) {
     registerMarketCommands(program, getPublicAdapter, isJson, getPublicAdapterForExchange, getAdapter);
     registerAccountCommands(program, getAdapter, isJson, getAdapterForExchange);
     registerOutcomeCommands(program, getAdapterForExchange, isJson);
+    registerOptionsCommands(program, isJson);
+    registerPacificaEarnCommands(program, getAdapterForExchange, isJson);
     registerTradeCommands(program, getAdapter, isJson, isDryRunFlag, getAdapterForExchange);
     // manage tree wired inside registerWalletCommands below.
     // stream commands removed
@@ -273,7 +286,15 @@ export function buildProgram(opts) {
     // registerFundsCommands above.
     // Background processes & strategies
     registerBackgroundCommands(program, isJson, getAdapterForExchange);
-    registerStrategyCommands(program, getAdapter, getAdapterForExchange, isJson);
+    // Every strategy command (bots, plans, TWAP / DCA / grid, `strategy run`, `--exchanges` legs,
+    // config-file venues) builds its adapters through these: a venue without the trading role
+    // (TxFlow, release-gated RISEx) is refused here, before any key is opened — also under --dry-run.
+    const strategyVenueGate = (venue) => {
+        const def = getVenue(venue);
+        if (!def.roles.includes("trading"))
+            throw roleUnsupported(def, "automation");
+    };
+    registerStrategyCommands(program, async () => { strategyVenueGate(getExchange()); return getAdapter(); }, async (exchange) => { strategyVenueGate(exchange); return getAdapterForExchange(exchange); }, isJson);
     // Agent-friendly commands
     registerRiskCommands(program, getAdapterForExchange, isJson);
     registerHistoryCommands(program, isJson, getAdapterForExchange);
@@ -286,7 +307,12 @@ export function buildProgram(opts) {
     registerPortfolioCommand(program, getAdapterForExchange, isJson, version, getHLAdapterForDex);
     registerInitCommand(program);
     registerAlertCommands(program, isJson);
+    installNestedHelp(program);
+    installMissingSubcommandError(program);
     // Switch shared API URLs if --network testnet is used
+    // A venue without the trading role (market-data-only TxFlow, release-gated RISEx) refuses every
+    // trading command before anything else — also under --dry-run, whose plans skip the adapter.
+    program.hook("preAction", (_root, actionCommand) => assertCommandVenueRole(actionCommand, program.opts().exchange));
     // Validates -n and enforces default-deny --dry-run before any action runs.
     installDryRunGuard(program);
     // Secrets on argv (review L10): -k is rejected outright; --passphrase still works but warns loudly.
@@ -301,3 +327,97 @@ export function buildProgram(opts) {
     program.hook("preAction", () => setQuarantineNetwork(networkOf(program)));
     return { program, getAdapterForExchange, isJson };
 }
+/** `perp trade <leaf>` commands that only read (order status, fills, P&L tracking, spot reads). */
+const TRADE_READ_COMMANDS = new Set(["status", "fills", "pnl-track", "spot-orders", "spot-balance"]);
+/**
+ * The trading-role gate at command resolution: `perp -e <venue> trade <write>`, every
+ * `perp trade multi <venue>:…` leg and `perp wallet agent approve|import|revoke|rotate <venue>`
+ * (revoke --force / --local-only excepted: local cleanup only) and every `strategy … --exchanges` leg refuse with roleUnsupported() (CAPABILITY_UNSUPPORTED) when the venue has no trading role. Runs
+ * before the dry-run guard and before any action, so a dry-run plan can never present a gated
+ * venue as tradable. Unknown venue names are left to the command's own UNKNOWN_VENUE handling.
+ */
+export function assertCommandVenueRole(actionCommand, exchangeOpt) {
+    const path = commandPath(actionCommand).split(" ");
+    const leaf = path[path.length - 1];
+    let venueArgs;
+    let feature;
+    if (leaf === "multi" && (path[0] === "trade" || path.length === 1)) {
+        venueArgs = actionCommand.args.map(leg => leg.split(":")[0]);
+        feature = "trading";
+    }
+    else if (path[0] === "strategy" && typeof actionCommand.opts().exchanges === "string") {
+        // `--exchanges` legs (strategy run / funding-arb / quick-arb / delta-neutral, incl. their defaults):
+        // refused before the first leg's adapter is built. The -e venue is gated by the strategy adapter factory.
+        venueArgs = String(actionCommand.opts().exchanges).split(",").map(v => v.trim()).filter(v => v !== "");
+        feature = "automation";
+    }
+    else if (path[0] === "trade" && path.length === 2 && !TRADE_READ_COMMANDS.has(leaf)) {
+        venueArgs = [exchangeOpt];
+        feature = "trading";
+    }
+    else if (path[0] === "wallet" && path[1] === "agent" && ["approve", "import", "revoke", "rotate"].includes(path[2] ?? "")) {
+        // `revoke --force` / `--local-only` only clears local records (nothing signed or sent): allowed.
+        const o = actionCommand.opts();
+        if (path[2] === "revoke" && (o.force === true || o.localOnly === true))
+            return;
+        venueArgs = actionCommand.args.slice(0, 1);
+        feature = path[2] === "import" ? "agentImport" : `agent ${path[2]}`;
+    }
+    else {
+        return;
+    }
+    for (const v of venueArgs) {
+        const id = tryResolveVenueId(v);
+        if (id !== null && !getVenue(id).roles.includes("trading"))
+            throw roleUnsupported(getVenue(id), feature);
+    }
+}
+/** `perp a b c` path of a command (root name excluded). */
+function commandPath(cmd) {
+    const names = [];
+    for (let c = cmd; c !== null && c.parent !== null; c = c.parent)
+        names.unshift(c.name());
+    return names.join(" ");
+}
+/**
+ * `perp help <group> <leaf> ...` shows the help of the deepest named command. Commander's built-in
+ * root help command resolves only its first operand, so `perp help market list` printed the
+ * `market` group help. Groups keep their own built-in `help` subcommand (`perp market help list`).
+ */
+function installNestedHelp(program) {
+    program.helpCommand(false);
+    program
+        .command("help [command...]")
+        .description("display help for command (any depth: perp help trade limit)")
+        .action((names) => {
+        let cmd = program;
+        for (const name of names) {
+            const sub = cmd.commands.find(c => c.name() === name || c.aliases().includes(name));
+            if (sub === undefined) {
+                const where = cmd === program ? "perp" : `perp ${commandPath(cmd)}`;
+                throw new PerpError("INVALID_PARAMS", `Unknown command '${name}' under '${where}'`, {
+                    remediation: `Available: ${cmd.commands.map(c => c.name()).join(", ")} — see: ${where} --help`,
+                });
+            }
+            cmd = sub;
+        }
+        cmd.help();
+    });
+}
+/**
+ * A command group run without a subcommand (`perp history`): Commander prints the group's help as
+ * an error. In --json mode that reached stdout as a CLI_ERROR whose message was the usage text;
+ * it is now one INVALID_PARAMS document naming the subcommands, with remediation (exit 1).
+ * Human mode keeps the usage listing on stderr.
+ */
+function installMissingSubcommandError(program) {
+    program.on("beforeAllHelp", (ctx) => {
+        if (!ctx.error || program.opts().json !== true)
+            return;
+        const path = `perp ${commandPath(ctx.command)}`.trim();
+        const subs = ctx.command.commands.map(c => c.name()).filter(n => n !== "help");
+        throw new PerpError("INVALID_PARAMS", `'${path}' needs a subcommand: ${subs.join(", ")}`, {
+            remediation: `Run one of them, e.g. ${path} ${subs[0]} — list them with: ${path} --help`,
+        });
+    });
+}

package/dist/commands/agent-import.d.ts

@@ -90,6 +90,13 @@ export declare function importSecretLineCount(venue: VenueId): number;
 export declare function importSecretFromLines(venue: VenueId, lines: string[]): ImportSecret;
 /** Read the secret: hidden TTY prompt, else piped stdin (ondo: 2 lines key id + secret; others: 1 line). */
 export declare function readImportSecret(venue: VenueId): Promise<ImportSecret>;
+/**
+ * Venues whose keys cannot be imported. TxFlow: market-data-only (unofficial read-only API).
+ * RISEx: perp-cli trades only with a signer it registered itself and then restricted ON-CHAIN to
+ * the trading permission; a signer created in the RISEx app keeps every permission (including
+ * deposit / withdraw), so it is never stored here.
+ */
+export declare function assertImportSupported(venue: VenueId, network: Network): void;
 /** Venues whose import cannot be checked against the venue (stored as "unverified"). */
 export declare const UNVERIFIED_IMPORT_VENUES: readonly VenueId[];
 /**

package/dist/commands/agent-import.js

@@ -24,7 +24,8 @@
 import chalk from "chalk";
 import { PerpError, classifyError } from "../errors.js";
 import { acquireLock, releaseLock, getAgent, setAgent, deleteAgent, listAgents, agentNetworkOf, agentSourceOf, getVenueAgent, setVenueAgent, deleteVenueAgent, } from "../agent-wallet/store.js";
-import { getVenue, networkConfig } from "../exchanges/venue.js";
+import { getVenue, networkConfig, roleUnsupported } from "../exchanges/venue.js";
+import { unsupported } from "../exchanges/trading-v2.js";
 import { LIGHTER_RH_RESERVED_KEY_INDEXES } from "../exchanges/venues/lighter-family.js";
 import { loadOws } from "../signer/ows-loader.js";
 import { defaultAgentName, isLighterFamilyVenue, parseExpiresIn, promptHidden, qfexWithdrawKeyWarning } from "./agent.js";
@@ -67,6 +68,11 @@ export function importSecretLabel(venue) {
         case "arcus": return "Arcus API key private key (Ed25519)";
         case "ondo": return "Ondo API secret";
         case "qfex": return "QFEX API secret";
+        case "risex": return "RISEx signer private key";
+        case "txflow": return "TxFlow key (not supported)";
+        case "variational": return "Variational key (not supported)";
+        case "grvt": return "GRVT key (not supported)";
+        case "extended": return "Extended key (not supported)";
     }
 }
 /**
@@ -154,6 +160,20 @@ function redacted(err, secrets, venue) {
         details.remediation = scrub(e.remediation, forms);
     return new PerpError(e.code, scrub(e.message, forms), details);
 }
+/**
+ * Venues whose keys cannot be imported. TxFlow: market-data-only (unofficial read-only API).
+ * RISEx: perp-cli trades only with a signer it registered itself and then restricted ON-CHAIN to
+ * the trading permission; a signer created in the RISEx app keeps every permission (including
+ * deposit / withdraw), so it is never stored here.
+ */
+export function assertImportSupported(venue, network) {
+    const def = getVenue(venue);
+    if (!def.roles.includes("trading"))
+        throw roleUnsupported(def, "agentImport");
+    if (venue === "risex") {
+        throw unsupported("risex", "agentImport", "perp-cli only uses RISEx signers it registered and restricted on-chain to trading-only permissions; an app-created signer keeps deposit / withdraw permissions", `Register a restricted signer with your master wallet: perp${network === "testnet" ? " -n testnet" : ""} wallet agent approve risex --master <ows-wallet>`);
+    }
+}
 /** Venues whose import cannot be checked against the venue (stored as "unverified"). */
 export const UNVERIFIED_IMPORT_VENUES = ["pacifica"];
 /**
@@ -722,6 +742,8 @@ async function importQfex(p, agentName, s, replacing) {
  * appears in a thrown error.
  */
 export async function importVenueAgent(p) {
+    // Refused before the secret is even inspected (nothing read, stored or sent).
+    assertImportSupported(p.venue, p.network);
     const secrets = secretsOf(p.secret);
     if (secrets.some(x => x.trim().length === 0))
         throw new PerpError("INVALID_PARAMS", "Empty key — nothing was imported");
@@ -751,6 +773,13 @@ export async function importVenueAgent(p) {
             case "lighter":
             case "lighter-rh":
                 return await importLighter(p, p.venue, agentName, key, replacing);
+            case "risex":
+            case "txflow":
+            case "variational":
+            case "grvt":
+            case "extended":
+                // Unreachable: assertImportSupported() refused these before the lock.
+                throw new PerpError("CAPABILITY_UNSUPPORTED", `${p.venue} keys cannot be imported`);
         }
     }
     catch (err) {

package/dist/commands/agent.d.ts

@@ -1,5 +1,5 @@
 import { Command, Option } from "commander";
-import { loadSettings, type OndoAgentMeta, type ArcusAgentMeta, type QfexAgentMeta } from "../settings.js";
+import { loadSettings, type OndoAgentMeta, type ArcusAgentMeta, type QfexAgentMeta, type RisexAgentMeta } from "../settings.js";
 import "../exchanges/venues/index.js";
 import type { Network, VenueId } from "../exchanges/venue-types.js";
 import { type LighterVenueId } from "../exchanges/venues/lighter-family.js";
@@ -27,7 +27,7 @@ export interface VerifyResult {
 /** Extract the agent list from a Pacifica /agent/list envelope; throws on an unrecognized shape. */
 export declare function parsePacAgentList(json: unknown): unknown[];
 /**
- * Confirmation of the account a QFEX key was resolved to (design §14.12 #9). In a terminal: a
+ * Confirmation of the account a QFEX key was resolved to. In a terminal: a
  * y/N prompt showing the UUID. Without one (piped stdin, --json): only an explicit --account-id
  * that equals the resolved account counts — the resolved UUID is printed on stderr either way.
  */
@@ -94,6 +94,9 @@ export type ApproveAgentOutcome = {
 } | {
     venue: "arcus";
     meta: ArcusAgentMeta;
+} | {
+    venue: "risex";
+    meta: RisexAgentMeta;
 } | {
     venue: LighterVenueId;
     agentName: string;
@@ -131,7 +134,7 @@ export declare function qfexWithdrawKeyWarning(meta: Pick<QfexAgentMeta, "agentN
 /** Venues `wallet agent rotate` (and `approve --rotate`) can rotate. */
 type RotatableVenue = "aster" | "hyperliquid" | "pacifica" | LighterVenueId;
 type RotatedAgentOutcome = Exclude<ApproveAgentOutcome, {
-    venue: "ondo" | "arcus";
+    venue: "ondo" | "arcus" | "risex";
 }>;
 export interface RotateAgentParams {
     exchange: RotatableVenue;

package/dist/commands/agent.js

@@ -9,7 +9,8 @@ import chalk from "chalk";
 import bs58 from "bs58";
 import { loadSettings } from "../settings.js";
 import { getAgent, setAgent, deleteAgent, listAgents, acquireLock, releaseLock, getVenueAgent, getVenueAgentForNetwork, setVenueAgent, deleteVenueAgent, listVenueAgents, agentNetworkOf, recordedAgentNetworkOf, assertAgentNetwork, getAgentForNetwork, agentSourceOf, } from "../agent-wallet/store.js";
-import { getVenue, networkConfig, resolveVenueId } from "../exchanges/venue.js";
+import { getVenue, networkConfig, resolveVenueId, roleUnsupported } from "../exchanges/venue.js";
+import { RISEX_APP_URL } from "../exchanges/venues/risex.js";
 import { listConfiguredAccountVenues } from "../config.js";
 import "../exchanges/venues/index.js";
 import { LIGHTER_RH_RESERVED_KEY_INDEXES } from "../exchanges/venues/lighter-family.js";
@@ -114,7 +115,7 @@ function readPipedStdin() {
     });
 }
 /**
- * Ondo API key id + secret, from stdin only (design §10.4 — never flags).
+ * Ondo API key id + secret, from stdin only (never flags).
  * TTY: key id prompt, then hidden secret prompt. Piped: line 1 = key id, line 2 = secret.
  */
 /** Lighter ChangePubKey settlement window when confirming a slot (docs example: 30 s, 1 s apart; kept under the 60 req/min budget). */
@@ -445,7 +446,7 @@ async function verifyQfex(network, opts) {
     };
 }
 /**
- * Confirmation of the account a QFEX key was resolved to (design §14.12 #9). In a terminal: a
+ * Confirmation of the account a QFEX key was resolved to. In a terminal: a
  * y/N prompt showing the UUID. Without one (piped stdin, --json): only an explicit --account-id
  * that equals the resolved account counts — the resolved UUID is printed on stderr either way.
  */
@@ -471,6 +472,40 @@ export function confirmImportAccount(explicitAccountId, json) {
         }
     };
 }
+/** RISEx: session-key status on the venue and the on-chain permission bitmap (read-only). */
+async function verifyRisex(network, opts) {
+    const meta = opts.agentName !== undefined ? getVenueAgent("risex", opts.agentName) : getVenueAgentForNetwork("risex", network);
+    // Read-only release (trading role gated): approve / revoke are refused, so point to the RISEx app.
+    const tradingGated = !getVenue("risex").roles.includes("trading");
+    if (!meta) {
+        throw new PerpError("AGENT_NOT_REGISTERED", `No RISEx signer registered for ${network}`, {
+            remediation: tradingGated
+                ? `RISEx is read-only in this perp-cli release (trading in a later release): manage signers in the RISEx app (${RISEX_APP_URL})`
+                : `perp${network === "testnet" ? " -n testnet" : ""} wallet agent approve risex --master <ows-wallet>`,
+        });
+    }
+    const { verifyRisexAgent } = await import("../exchanges/risex/agent.js");
+    const v = await verifyRisexAgent(meta);
+    const warnings = [];
+    if (!v.active)
+        warnings.push(`RISEx signer ${meta.signerAddress} status is ${String(v.status)} (1 = Active)`);
+    if (v.expired)
+        warnings.push(`RISEx signer ${meta.signerAddress} expired at ${meta.expiresAt}`);
+    if (v.active && (!v.tradingOnly || meta.permissions.tradingOnly !== true)) {
+        // An active signer that can do more than trade is a failure, never ok:true.
+        throw new PerpError("POLICY_DENIED", `RISEx signer ${meta.signerAddress} ("${meta.agentName}") is NOT restricted to trading-only (on-chain ${JSON.stringify(v.permissions)}, bitmap ${String(v.bitmap)}; recorded tradingOnly=${String(meta.permissions.tradingOnly)})${v.reason !== null ? ` — ${v.reason}` : ""}`, {
+            exchange: "risex", signer: meta.signerAddress, permissions: v.permissions, bitmap: v.bitmap,
+            remediation: tradingGated
+                ? `Revoke it in the RISEx app (${RISEX_APP_URL}); then remove the local record: perp${network === "testnet" ? " -n testnet" : ""} wallet agent revoke risex ${meta.agentName} --force`
+                : `Revoke it: perp${network === "testnet" ? " -n testnet" : ""} wallet agent revoke risex ${meta.agentName}, then approve a new one`,
+        });
+    }
+    return {
+        registered: v.active, count: 1,
+        items: [{ agentName: meta.agentName, signer: meta.signerAddress, account: meta.accountAddress, network: meta.network, status: v.status, permissions: v.permissions, tradingOnly: v.tradingOnly, expiresAt: meta.expiresAt }],
+        warnings: warnings.length > 0 ? warnings : undefined,
+    };
+}
 /** Dispatch a verify to the venue-specific implementation. */
 async function verifyVenue(ex, network, opts) {
     if (ex === "aster")
@@ -487,8 +522,10 @@ async function verifyVenue(ex, network, opts) {
         return verifyArcus(network, opts);
     if (ex === "qfex")
         return verifyQfex(network, opts);
+    if (ex === "risex")
+        return verifyRisex(network, opts);
     throw new PerpError("NOT_IMPLEMENTED", `${ex} has no agents to verify`, {
-        remediation: "perp wallet agent verify <aster|hyperliquid|pacifica|lighter|lighter-rh|ondo|arcus|qfex> [agentName]",
+        remediation: "perp wallet agent verify <aster|hyperliquid|pacifica|lighter|lighter-rh|ondo|arcus|qfex|risex> [agentName]",
     });
 }
 /**
@@ -509,6 +546,9 @@ export function agentApproveUnsupportedReason(venue, network, op) {
 }
 /** Throws the uniform CAPABILITY_UNSUPPORTED error when agentApproveUnsupportedReason() is non-null. */
 export function assertAgentApproveSupported(venue, network, op) {
+    const def = getVenue(venue);
+    if (!def.roles.includes("trading"))
+        throw roleUnsupported(def, `agent ${op}`);
     if (venue === "qfex") {
         // Programmatic key creation needs a website session (SIWE + MFA) — not a CLI path.
         throw unsupported("qfex", "agentApprove", "API keys are created (and revoked) on the QFEX website, behind 2FA", `Create the key in QFEX Developer Settings, then import it: perp${network === "testnet" ? " -n testnet" : ""} wallet agent import qfex`);
@@ -540,6 +580,11 @@ export function defaultAgentName(venue, network) {
         case "ondo": return `perp-cli-ondo${suffix}`;
         case "arcus": return `perp-cli-arcus${suffix}`;
         case "qfex": return `perp-cli-qfex${suffix}`;
+        case "risex": return `perp-cli-risex${suffix}`;
+        case "txflow": return `perp-cli-txflow${suffix}`;
+        case "variational": return `perp-cli-variational${suffix}`;
+        case "grvt": return `perp-cli-grvt${suffix}`;
+        case "extended": return `perp-cli-extended${suffix}`;
     }
 }
 /**
@@ -622,7 +667,7 @@ function requirePassphrase(passphrase) {
 export async function approveVenueAgent(p) {
     assertAgentApproveSupported(p.venue, p.network, "approve");
     const agentName = p.agentName ?? defaultAgentName(p.venue, p.network);
-    // Ondo: HMAC key entered on stdin only (design §10.4)
+    // Ondo: HMAC key entered on stdin only
     if (p.venue === "ondo") {
         assertVenueAgentNameFree("ondo", agentName, p.network);
         if (getVenueAgent("ondo", agentName) && !p.rotate) {
@@ -636,7 +681,7 @@ export async function approveVenueAgent(p) {
         setVenueAgent("ondo", meta);
         return { venue: "ondo", meta };
     }
-    // Arcus: OWS Ed25519 agent + EIP-712 createApiKey (design §10.4)
+    // Arcus: OWS Ed25519 agent + EIP-712 createApiKey
     if (p.venue === "arcus") {
         const masterName = requireMaster(p.master);
         assertVenueAgentNameFree("arcus", agentName, p.network);
@@ -660,6 +705,53 @@ export async function approveVenueAgent(p) {
             releaseLock("arcus");
         }
     }
+    // RISEx: master-signed RegisterSigner, then an on-chain restriction to trading-only.
+    if (p.venue === "risex") {
+        const masterName = requireMaster(p.master);
+        assertVenueAgentNameFree("risex", agentName, p.network);
+        if (p.canWithdraw || p.canSpot) {
+            throw new PerpError("INVALID_PARAMS", "RISEx signers registered by perp-cli are always restricted to trading only (no fund movement, no spot)", {
+                remediation: "Drop --can-withdraw / --can-spot",
+            });
+        }
+        const expiresAt = parseExpiresInParam(p.expiresIn);
+        const { approveRisexAgent, revokeRisexAgent, risexAgentWalletName, risexRotatePreflight, risexSignerStatus } = await import("../exchanges/risex/agent.js");
+        acquireLock("risex");
+        try {
+            const existing = getVenueAgent("risex", agentName);
+            if (existing !== null) {
+                if (!p.rotate) {
+                    throw new PerpError("INVALID_PARAMS", `RISEx signer "${agentName}" already exists`, {
+                        remediation: `Replace it (revoke the old signer, register a fresh one): perp${p.network === "testnet" ? " -n testnet" : ""} wallet agent approve risex --rotate — or choose another --agent-name`,
+                    });
+                }
+                // Rotate: the new signer's checks (pins, maintenance, master gas) pass first, then a
+                // venue-confirmed revoke of the old signer, then drop its key, then approve.
+                await risexRotatePreflight(masterName, p.passphrase, p.network);
+                // A kept record whose signer never registered (or is already revoked) has nothing to
+                // revoke on the venue: it is only forgotten locally. An Active one is revoked first.
+                const status = await risexSignerStatus(existing);
+                if (status === 1)
+                    await revokeRisexAgent({ meta: existing, masterOwsWallet: masterName, passphrase: p.passphrase });
+                try {
+                    loadOws().deleteWallet(existing.agentWalletName);
+                }
+                catch { /* already gone */ }
+                deleteVenueAgent("risex", agentName);
+            }
+            else if (p.rotate && loadOws().listWallets().some((w) => w.name === risexAgentWalletName(masterName, p.network))) {
+                throw new PerpError("INVALID_PARAMS", `OWS wallet "${risexAgentWalletName(masterName, p.network)}" exists but no RISEx signer record uses it`, {
+                    remediation: `If no RISEx signer uses its key, delete it (ows wallet delete ${risexAgentWalletName(masterName, p.network)}) and re-run the approve`,
+                });
+            }
+            const meta = await approveRisexAgent({ agentName, masterOwsWallet: masterName, passphrase: p.passphrase, network: p.network, expiresAt });
+            setVenueAgent("risex", meta);
+            return { venue: "risex", meta };
+        }
+        finally {
+            releaseLock("risex");
+        }
+    }
     const expiresAt = parseExpiresInParam(p.expiresIn);
     const masterName = requireMaster(p.master);
     const expiresAtIso = expiresAt.toISOString();
@@ -993,6 +1085,16 @@ export function printApproveOutcome(outcome) {
             console.log(`  Valid Until:   ${chalk.cyan(outcome.meta.validUntil)}`);
             console.log();
             return;
+        case "risex":
+            console.log(chalk.green.bold("\n  RISEx signer registered and restricted to trading-only!\n"));
+            console.log(`  Name:        ${chalk.cyan(outcome.meta.agentName)}`);
+            console.log(`  Signer:      ${chalk.cyan(outcome.meta.signerAddress)}`);
+            console.log(`  Account:     ${chalk.cyan(outcome.meta.accountAddress)}`);
+            console.log(`  Expires:     ${chalk.cyan(outcome.meta.expiresAt)}`);
+            console.log(`  Permissions: ${chalk.cyan("trading only")} ${chalk.gray(`(on-chain; disabled ${outcome.meta.permissions.disabled.join(", ")}; verified ${outcome.meta.permissions.verifiedAt})`)}`);
+            console.log(chalk.gray("  Deposits / withdrawals: RISEx app only (perp-cli never moves RISEx funds)."));
+            console.log();
+            return;
         case "lighter":
         case "lighter-rh":
             console.log(chalk.green.bold(`\n  ${getVenue(outcome.venue).displayName} Agent approved successfully!\n`));
@@ -1043,7 +1145,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
     // ── agent approve <exchange> ── register an agent wallet ──────────────────
     agent
         .command("approve <exchange>")
-        .description("Register an agent wallet / API key for an exchange (aster, hyperliquid, pacifica, lighter, lighter-rh, ondo, arcus)")
+        .description("Register an agent wallet / API key for an exchange (aster, hyperliquid, pacifica, lighter, lighter-rh, ondo, arcus, risex — risex: a trading-only session signer, restricted on-chain)")
         .option("--master <name>", "Master OWS wallet name")
         .option("--agent-name <name>", "Agent name (default: perp-cli-aster)")
         .option("--expires-in <duration>", "Expiry: 30d, 90d, 180d, 1y, or ISO-8601 datetime (default: 90d)")
@@ -1087,7 +1189,8 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                 assertAgentApproveSupported(venue, network, "approve");
             let master = opts.master ?? null;
             let agentName = opts.agentName ?? null;
-            let expiresIn = opts.expiresIn ?? "90d";
+            // RISEx signers default to 30 days (owner decision; the venue maximum is not documented).
+            let expiresIn = opts.expiresIn ?? (venue === "risex" ? "30d" : "90d");
             let canPerp = opts.canPerp ?? true;
             let canSpot = opts.canSpot ?? false;
             let canWithdraw = opts.canWithdraw ?? false;
@@ -1218,6 +1321,9 @@ Examples:
             }
             const network = networkOf(command);
             const venue = resolveVenueId(exchange);
+            // TxFlow (market data only) / RISEx (perp-cli-registered, restricted signers only): refused before any stdin read.
+            const { assertImportSupported } = await import("./agent-import.js");
+            assertImportSupported(venue, network);
             const int = (flag, raw) => {
                 if (raw === undefined)
                     return null;
@@ -1296,14 +1402,14 @@ Examples:
         for (const { exchange: ex, meta } of listVenueAgents()) {
             if (venueFilter !== null && venueFilter !== ex)
                 continue;
-            const expiresAt = meta.kind === "arcus" ? meta.validUntil : null;
+            const expiresAt = meta.kind === "arcus" ? meta.validUntil : meta.kind === "risex" ? meta.expiresAt : null;
             const status = expiresAt !== null && expiresAt !== "" && new Date(expiresAt).getTime() < now ? "expired" : "active";
             rows.push({
                 name: meta.agentName,
                 exchange: ex,
                 network: meta.network,
                 source: agentSourceOf(ex, meta),
-                evmAddress: meta.kind === "arcus" ? meta.ownerAddress : "",
+                evmAddress: meta.kind === "arcus" ? meta.ownerAddress : meta.kind === "risex" ? meta.signerAddress : "",
                 // Ondo keys carry no expiry; shown as "—".
                 expiresAt: expiresAt ?? "",
                 status,
@@ -1373,9 +1479,11 @@ Examples:
             network = networkOf(command);
             // An imported key is only ever removed locally, so it needs no venue support for revoke
             // (e.g. an imported Aster testnet key).
-            const rec = exchange === "ondo" || exchange === "arcus" || exchange === "qfex" ? getVenueAgent(exchange, agentName) : getAgent(exchange, agentName);
+            const rec = exchange === "ondo" || exchange === "arcus" || exchange === "qfex" || exchange === "risex" ? getVenueAgent(exchange, agentName) : getAgent(exchange, agentName);
             // QFEX keys only exist as imports: a missing record is "already removed", never an approve-capability error.
-            if (exchange !== "qfex" && (rec === null || agentSourceOf(exchange, rec) !== "imported"))
+            // A release-gated venue (RISEx in 0.15.0) still lets --force / --local-only clear local state: nothing is signed or sent.
+            const localCleanupOfGated = localOnly && getVenue(exchange).gatedRoles !== null;
+            if (exchange !== "qfex" && !localCleanupOfGated && (rec === null || agentSourceOf(exchange, rec) !== "imported"))
                 assertAgentApproveSupported(exchange, network, "revoke");
         }
         catch (e) {
@@ -1425,6 +1533,46 @@ Examples:
                     console.log(chalk.green(`Agent "${agentName}" on qfex removed locally.`) + chalk.yellow(`\n  ${note}`));
                 return;
             }
+            // ── RISEx: RevokeSigner signed by the master wallet (gasless REST); then the key is deleted ──
+            if (exchange === "risex") {
+                const risexMeta = getVenueAgent("risex", agentName);
+                if (!risexMeta) {
+                    if (useJson)
+                        printJson({ ok: true, data: { alreadyRevoked: true } });
+                    else
+                        console.log(`Agent "${agentName}" on risex not found locally — already revoked.`);
+                    return;
+                }
+                if (risexMeta.network !== network) {
+                    throw new PerpError("AGENT_NOT_REGISTERED", `RISEx signer "${agentName}" is registered on ${risexMeta.network}, not ${network}`, {
+                        remediation: risexMeta.network === "mainnet" ? "Run without -n testnet to revoke it" : "Run with -n testnet to revoke it",
+                    });
+                }
+                let txHash = null;
+                if (!localOnly) {
+                    const masterName = opts.master ?? loadSettings().owsActiveWallet;
+                    if (!masterName) {
+                        throw new PerpError("INVALID_PARAMS", "Master wallet name is required to revoke a RISEx signer", {
+                            remediation: "Use --master <name>, or --force to clear local state only (then revoke it in the RISEx app)",
+                        });
+                    }
+                    const passphrase = await resolvePassphrase({ flag: passphraseFlag });
+                    const { revokeRisexAgent } = await import("../exchanges/risex/agent.js");
+                    txHash = (await revokeRisexAgent({ meta: risexMeta, masterOwsWallet: masterName, passphrase })).txHash;
+                }
+                try {
+                    loadOws().deleteWallet(risexMeta.agentWalletName);
+                }
+                catch { /* already gone */ }
+                deleteVenueAgent("risex", agentName);
+                if (useJson)
+                    printJson(jsonOk({ revoked: !localOnly, local: localOnly, txHash }));
+                else
+                    console.log(localOnly
+                        ? chalk.yellow(`Agent "${agentName}" on risex removed locally only — revoke signer ${risexMeta.signerAddress} in the RISEx app.`)
+                        : chalk.green(`Agent "${agentName}" on risex revoked successfully.`));
+                return;
+            }
             // ── Arcus: EIP-712 RevokeApiKey signed by the master wallet ──
             if (exchange === "arcus") {
                 const arcusMeta = getVenueAgent("arcus", agentName);

package/dist/commands/arb/index.js

@@ -420,7 +420,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
         };
         // Collect spot balances per exchange
         const spotBalancesByExchange = new Map();
-        // Bot/arb spot scope (§12.4 #3): configured venues with a separate spot balance + transfer.
+        // Bot/arb spot scope: configured venues with a separate spot balance + transfer.
         const configuredVenues = new Set(await listConfiguredAccountVenues());
         for (const def of listBotSpotVenues()) {
             if (!configuredVenues.has(def.id))
@@ -802,7 +802,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
             await dropStaleStateEntry(sym, opts.yes === true, dryRun);
             return;
         }
-        // Global quarantine (design §12.3): an unknown / unhedged outcome was recorded for
+        // Global quarantine: an unknown / unhedged outcome was recorded for
         // this symbol. A human may still close it, but only knowingly (--force).
         const quarantined = quarantineEntryFor(sym, (m) => console.error(chalk.red(m)));
         if (quarantined !== null) {
@@ -846,7 +846,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                 console.log(chalk.cyan(`  [DRY-RUN] Would close spot-perp ${sym}: sell spot on ${spotExch} + buy back the perp short on ${perpExch}`));
                 return;
             }
-            // One implementation for spot-perp close (fill-checked legs, §12.4 #5): arb-auto's handler.
+            // One implementation for spot-perp close (fill-checked legs): arb-auto's handler.
             if (handleSpotClose === undefined)
                 throw new Error("spot-perp close handler is not registered (registerArbAutoCommands not called)");
             await handleSpotClose(sym, { spotExch, perpExch }, getAdapterForExchange, isJson);
@@ -982,7 +982,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
         // Close the legs sequentially (long, then short), reduce-only and verified, each
         // sized from the venue's own position size. No retries: a definite failure of the
         // long close changes nothing; an unknown outcome or a leg left open after the
-        // other closed quarantines the symbol (design §12.3).
+        // other closed quarantines the symbol.
         const results = [];
         const closeRes = await closePerpPairVerified({
             source: "arb-close", sym,