perp-cli 0.14.2 → 0.15.0

package/dist/ws/pacifica-instrument.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pacifica GET /info `instrument_type` (docs.pacifica.fi get-market-info; live: "perpetual" / "spot").
+ * The one perp rule for every Pacifica surface (WS directory, CLI adapter, funding, arb): only
+ * "perpetual" rows are perps — spot (SOL-USDC) and any other / future type are not.
+ */
+export declare function isPacificaPerpetual(row: {
+    instrument_type?: unknown;
+}): boolean;

package/dist/ws/pacifica-instrument.js

@@ -0,0 +1,8 @@
+/**
+ * Pacifica GET /info `instrument_type` (docs.pacifica.fi get-market-info; live: "perpetual" / "spot").
+ * The one perp rule for every Pacifica surface (WS directory, CLI adapter, funding, arb): only
+ * "perpetual" rows are perps — spot (SOL-USDC) and any other / future type are not.
+ */
+export function isPacificaPerpetual(row) {
+    return row.instrument_type === "perpetual";
+}

package/dist/ws-cli/credentials.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CredentialProvider for perp-cli/ws backed by the CLI's existing stores (plan ws-0.14.4 §5.1).
+ * Node only (not part of perp-cli/ws). Identifiers come from the active OWS wallet and the registered
+ * venue agents in ~/.perp/settings.json; the Lighter auth token is created in memory by the same path
+ * the CLI uses (agent keystore → WASM signer). Never reads argv or env, never prompts: a keystore that
+ * needs a passphrase → PASSPHRASE_REQUIRED (the stream reports WS_AUTH_FAILED). Keys never leave this
+ * module; only the short-lived token is handed to the stream.
+ */
+import { getAgentForNetwork } from "../agent-wallet/store.js";
+type Network = "mainnet" | "testnet";
+type UserRef = {
+    venue: "hyperliquid";
+    address: `0x${string}`;
+} | {
+    venue: "pacifica";
+    account: string;
+} | {
+    venue: "lighter" | "lighter-rh";
+    accountIndex: number;
+} | {
+    venue: "arcus";
+    address: `0x${string}`;
+    subaccount: number | null;
+};
+export interface CliCredentialProvider {
+    /** Non-fatal notes about the resolved identity (e.g. Arcus all-subaccounts agent → subaccount 0). */
+    readonly warnings: string[];
+    user(): Promise<UserRef>;
+    authToken?(req: {
+        purpose: string;
+        maxTtlSec: number;
+    }): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+}
+export type CliWsVenue = "hyperliquid" | "pacifica" | "lighter" | "lighter-rh" | "arcus";
+type LighterAgentMeta = NonNullable<ReturnType<typeof getAgentForNetwork>> & {
+    accountIndex: number;
+    apiKeyIndex: number;
+};
+/** Mints Lighter auth tokens; holds the agent key inside its WASM signer for the provider's lifetime. */
+export interface LighterTokenSigner {
+    createAuthToken(deadlineSec: number): Promise<string>;
+}
+/** Injectable for tests; the defaults are the CLI's own stores and signer. */
+export interface CliCredentialDeps {
+    owsAddresses(): {
+        evm: string;
+        solana: string;
+    };
+    lighterAgent(venue: "lighter" | "lighter-rh", network: Network): LighterAgentMeta;
+    arcusAgent(network: Network): {
+        ownerAddress: `0x${string}`;
+        accountIndex: number;
+    } | null;
+    /** Decrypt the agent key with the empty passphrase (never prompts). */
+    loadLighterKey(venue: "lighter" | "lighter-rh", network: Network, meta: LighterAgentMeta): Promise<string>;
+    makeLighterSigner(venue: "lighter" | "lighter-rh", network: Network, meta: LighterAgentMeta, key: string): Promise<LighterTokenSigner>;
+}
+export declare function createCliCredentialProvider(venue: CliWsVenue, network: Network, deps?: Partial<CliCredentialDeps>): CliCredentialProvider;
+export {};

package/dist/ws-cli/credentials.js

@@ -0,0 +1,126 @@
+/**
+ * CredentialProvider for perp-cli/ws backed by the CLI's existing stores (plan ws-0.14.4 §5.1).
+ * Node only (not part of perp-cli/ws). Identifiers come from the active OWS wallet and the registered
+ * venue agents in ~/.perp/settings.json; the Lighter auth token is created in memory by the same path
+ * the CLI uses (agent keystore → WASM signer). Never reads argv or env, never prompts: a keystore that
+ * needs a passphrase → PASSPHRASE_REQUIRED (the stream reports WS_AUTH_FAILED). Keys never leave this
+ * module; only the short-lived token is handed to the stream.
+ */
+import { PerpError } from "../errors.js";
+import { loadSettings } from "../settings.js";
+import { loadOws } from "../signer/ows-loader.js";
+import { getAgentForNetwork, getVenueAgentForNetwork } from "../agent-wallet/store.js";
+function activeOwsAddresses() {
+    const name = loadSettings().owsActiveWallet;
+    if (!name) {
+        throw new PerpError("NO_SIGNER_AVAILABLE", "No active OWS wallet", { remediation: "Run: perp wallet use <name>" });
+    }
+    const w = loadOws().getWallet(name);
+    const evm = w.accounts.find(a => a.chainId.startsWith("eip155:"))?.address;
+    const solana = w.accounts.find(a => a.chainId.startsWith("solana:"))?.address;
+    if (evm === undefined || solana === undefined) {
+        throw new PerpError("NO_SIGNER_AVAILABLE", `OWS wallet "${name}" has no EVM or Solana account`, { remediation: "Run: perp wallet show" });
+    }
+    return { evm, solana };
+}
+function lighterAgent(venue, network) {
+    const meta = getAgentForNetwork(venue, network);
+    if (!meta || typeof meta.accountIndex !== "number" || typeof meta.apiKeyIndex !== "number") {
+        throw new PerpError("AGENT_NOT_REGISTERED", `No ${venue} agent registered on ${network}`, { remediation: `Run: perp -e ${venue} wallet agent approve` });
+    }
+    return meta;
+}
+const DEFAULT_DEPS = {
+    owsAddresses: activeOwsAddresses,
+    lighterAgent,
+    arcusAgent: (network) => getVenueAgentForNetwork("arcus", network),
+    async loadLighterKey(venue, network, meta) {
+        const { loadLighterFamilyKey } = await import("../agent-wallet/lighter-keystore.js");
+        return loadLighterFamilyKey(venue, network, meta.accountIndex, meta.apiKeyIndex, "");
+    },
+    async makeLighterSigner(venue, network, meta, key) {
+        const { LighterAdapter } = await import("../exchanges/lighter.js");
+        const adapter = LighterAdapter.forVenue(venue, "", network === "testnet");
+        adapter.setAgentSigner(meta, key);
+        if (meta.userEvmAddress)
+            adapter.setAddress(meta.userEvmAddress);
+        await adapter.init();
+        return { createAuthToken: async (deadlineSec) => (await adapter.signer.createAuthToken(deadlineSec)).authToken };
+    },
+};
+/**
+ * Keystore decrypt failures with the empty passphrase mean "this keystore has a passphrase" →
+ * PASSPHRASE_REQUIRED. Every other keystore error keeps its code with a generic message (no path,
+ * no crypto detail, no key material).
+ */
+function keystoreError(venue, e) {
+    const code = e instanceof PerpError ? e.structured.code : "UNKNOWN";
+    const msg = e instanceof Error ? e.message : "";
+    if (code === "SIGNATURE_FAILED" && /LIGHTER_KEYSTORE_DECRYPT_FAILED: (?!corrupt JSON|unsupported)|Keystore decrypt failed/.test(msg)) {
+        return new PerpError("PASSPHRASE_REQUIRED", `${venue} agent keystore needs a passphrase (not prompted for a stream)`, {
+            remediation: "Use a keystore without a passphrase for streaming, or pass your own CredentialProvider.authToken",
+        });
+    }
+    const remediation = e instanceof PerpError ? e.structured.remediation : undefined;
+    return new PerpError(code, `${venue} agent keystore could not be read (${code})`, remediation === undefined ? undefined : { remediation });
+}
+export function createCliCredentialProvider(venue, network, deps = {}) {
+    const d = { ...DEFAULT_DEPS, ...deps };
+    const warnings = [];
+    let signer = null;
+    const provider = {
+        warnings,
+        async user() {
+            switch (venue) {
+                case "hyperliquid":
+                    return { venue, address: d.owsAddresses().evm };
+                case "pacifica":
+                    return { venue, account: d.owsAddresses().solana };
+                case "lighter":
+                case "lighter-rh":
+                    return { venue, accountIndex: d.lighterAgent(venue, network).accountIndex };
+                case "arcus": {
+                    const a = d.arcusAgent(network);
+                    if (a === null)
+                        throw new PerpError("AGENT_NOT_REGISTERED", `No arcus agent registered on ${network}`, { remediation: "Run: perp -e arcus wallet agent approve" });
+                    if (a.accountIndex === 255) {
+                        // 255 = an API key for ALL subaccounts; a stream follows one account → the venue default (0).
+                        const w = "arcus agent covers all subaccounts (255): streaming subaccount 0 (the venue default); pass your own CredentialProvider.user() for another subaccount";
+                        if (!warnings.includes(w))
+                            warnings.push(w);
+                        return { venue, address: a.ownerAddress, subaccount: null };
+                    }
+                    return { venue, address: a.ownerAddress, subaccount: a.accountIndex };
+                }
+            }
+        },
+    };
+    if (venue === "lighter" || venue === "lighter-rh") {
+        // One signer per provider: the agent key is decrypted once and lives only inside the WASM signer
+        // until the provider is dropped. A failed creation is not cached (the next call retries).
+        const getSigner = () => {
+            if (signer === null) {
+                signer = (async () => {
+                    const meta = d.lighterAgent(venue, network);
+                    let key;
+                    try {
+                        key = await d.loadLighterKey(venue, network, meta);
+                    }
+                    catch (e) {
+                        throw keystoreError(venue, e);
+                    }
+                    return d.makeLighterSigner(venue, network, meta, key);
+                })();
+                signer.catch(() => { signer = null; });
+            }
+            return signer;
+        };
+        provider.authToken = async ({ maxTtlSec }) => {
+            const s = await getSigner();
+            const deadlineSec = Math.floor(Date.now() / 1000) + maxTtlSec;
+            const token = await s.createAuthToken(deadlineSec);
+            return { token, expiresAt: deadlineSec * 1000 };
+        };
+    }
+    return provider;
+}

package/package.json

@@ -1,12 +1,40 @@
 {
   "name": "perp-cli",
-  "version": "0.14.2",
-  "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus",
+  "version": "0.15.0",
+  "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus, QFEX, RISEx (read-only), TxFlow (market data, unofficial API)",
   "bin": {
     "perp": "dist/index.js",
     "perp-mcp": "dist/mcp-server.js",
     "perp-guardrail": "dist/guardrail/perp-guardrail.js"
   },
+  "exports": {
+    "./ws": {
+      "types": "./dist/ws/index.d.ts",
+      "import": "./dist/ws/index.js",
+      "default": "./dist/ws/index.js"
+    },
+    "./ws/node": {
+      "types": "./dist/ws/node.d.ts",
+      "import": "./dist/ws/node.js",
+      "default": "./dist/ws/node.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "ws": [
+        "dist/ws/index.d.ts"
+      ],
+      "ws/node": [
+        "dist/ws/node.d.ts"
+      ]
+    }
+  },
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/mcp-server.js",
+    "./dist/guardrail/perp-guardrail.js"
+  ],
   "files": [
     "dist",
     "skills",
@@ -14,7 +42,7 @@
   ],
   "type": "module",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsup --config tsup.ws.config.ts && tsup --config tsup.perp-ws.config.ts",
     "dev": "tsc --watch",
     "test": "vitest run --exclude '**/integration/**'",
     "test:integration": "vitest run -c vitest.integration.config.ts",
@@ -23,7 +51,7 @@
     "e2e:typecheck": "tsc -p scripts/e2e/tsconfig.json",
     "typecheck:test": "tsc -p tsconfig.test.json",
     "sync-skill-version": "node scripts/sync-skill-version.mjs",
-    "prepublishOnly": "node scripts/sync-skill-version.mjs && pnpm run build"
+    "prepublishOnly": "node scripts/sync-skill-version.mjs --check && node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && pnpm run build"
   },
   "keywords": [
     "pacifica",
@@ -35,6 +63,12 @@
     "ondo",
     "ondo-perps",
     "arcus",
+    "qfex",
+    "risex",
+    "rise-chain",
+    "txflow",
+    "variational",
+    "grvt",
     "solana",
     "perps",
     "dex",
@@ -55,28 +89,28 @@
     "node": "^20.0.0 || ^22.0.0 || ^24.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@msgpack/msgpack": "^3.1.3",
     "@open-wallet-standard/core": "1.3.2",
-    "@solana/web3.js": "^1.98.0",
-    "@types/react": "^19.2.14",
+    "@solana/web3.js": "^1.99.0",
     "bs58": "^6.0.0",
     "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
     "dotenv": "^16.5.0",
-    "ethers": "^6.13.2",
+    "ethers": "^6.17.0",
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-table": "^3.1.0",
     "react": "^19.2.4",
     "tweetnacl": "^1.0.3",
-    "ws": "^8.19.0",
-    "yaml": "^2.8.2",
+    "ws": "^8.22.0",
+    "yaml": "^2.9.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
+    "@types/react": "^19.2.14",
     "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.6",
     "ts-morph": "^27.0.2",
@@ -84,5 +118,19 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.6"
+  },
+  "pnpm": {
+    "overrides": {
+      "hono@<4.13.7": "^4.13.13",
+      "@hono/node-server@<1.19.15": "^1.19.15",
+      "fast-uri@<3.1.8": "^3.1.8",
+      "proxy-addr@<2.0.8": "^2.0.8",
+      "path-to-regexp@>=8.0.0 <8.4.0": "^8.4.2",
+      "ip-address@<=10.7.0": "^10.7.4",
+      "qs@<6.16.0": "^6.16.0",
+      "body-parser@>=2.0.0 <2.3.0": "^2.3.0",
+      "ws@>=7.0.0 <7.5.11": "^7.5.13",
+      "uuid@>=11.0.0 <11.1.1": "^11.1.1"
+    }
   }
 }

package/skills/perp-cli/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: perp-cli
-description: "Multi-DEX perpetual futures trading via the perp-cli command-line tool. Use when user asks to: trade perps, check funding rates, scan/execute arbitrage (perp-perp or spot-perp), run delta-neutral strategies, bridge USDC across chains, manage positions/orders/leverage, deposit/withdraw, hedge spot+perp, trade HIP-3 DEXes, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus, HyperEVM, funding arb, or U-tokens (UBTC/UETH/USOL). Covers Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), Aster (BNB Chain), Lighter RH and Arcus (Robinhood chain) and Ondo Perps (off-chain)."
+description: "Multi-DEX perpetual futures trading via the perp-cli command-line tool. Use when user asks to: trade perps, check funding rates, scan/execute arbitrage (perp-perp or spot-perp), run delta-neutral strategies, bridge USDC across chains, manage positions/orders/leverage, deposit/withdraw, hedge spot+perp, trade HIP-3 DEXes, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus, QFEX, RISEx, TxFlow, Variational, GRVT, HyperEVM, funding arb, or U-tokens (UBTC/UETH/USOL). Covers Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), Aster (BNB Chain), Lighter RH and Arcus (Robinhood chain), Ondo Perps and QFEX (off-chain), RISEx (RISE chain), TxFlow (market data only, UNOFFICIAL API) Variational Omni (market data only, official API) and GRVT (market data only for now, official API)."
 license: MIT
 allowed-tools: "Bash(perp:*), Bash(npx -y perp-cli:*), Bash(bash scripts/preflight.sh:*), Bash(bash scripts/arb-monitor.sh:*), Bash(bash scripts/funding-analysis.sh:*), Bash(bash scripts/spot-perp-scan.sh:*), Bash(bash scripts/validate-arb.sh:*)"
 compatibility: "Requires Node.js 20 or newer and the perp-cli npm package (global install or npx). Network access required for exchange APIs and bridge providers. Mutating commands need a wallet key imported into the OWS vault via 'perp wallet set EXCHANGE' (key on stdin or hidden prompt — never argv). Skill is portable across Claude Code, Claude.ai, Cursor, Codex, and Gemini CLI — no platform-specific features."
 metadata:
   author: hypurrquant
-  version: "0.14.2"
+  version: "0.15.0"
 ---
 
 # perp-cli
 
-Multi-DEX perpetual futures CLI + MCP server for Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), Aster (BNB Chain), Lighter RH (`lighter-rh`, Robinhood chain, USDG), Ondo Perps (`ondo`), QFEX (`qfex`, custodial TradFi perps — import-only API key; resting reduce-only limits and automation are refused for now, see "QFEX" below), Arcus (`arcus`, Robinhood chain, USDG). v0.13.0+ also supports Hyperliquid Outcome markets (HIP-4) — fully-collateralized binary/range contracts; each outcome's quote token comes from `outcomeMeta.quoteToken` (USDC on every listed outcome as of 2026-10-12), minimum order value 10 quote tokens.
+Multi-DEX perpetual futures CLI + MCP server for Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), Aster (BNB Chain), Lighter RH (`lighter-rh`, Robinhood chain, USDG), Ondo Perps (`ondo`), QFEX (`qfex`, custodial TradFi perps — import-only API key; resting reduce-only limits and automation are refused for now, see "QFEX" below), Arcus (`arcus`, Robinhood chain, USDG), RISEx (`risex|rise`, RISE chain, USDC — READ-ONLY in this release: market data + account reads; trading is planned for a later perp-cli release, see "RISEx" below), TxFlow (`txflow|txf`, MARKET DATA ONLY through an UNOFFICIAL API — no official API exists; it may break without notice, see "TxFlow" below), Variational Omni (`variational|var|omni`, MARKET DATA ONLY through its official read-only API — RFQ venue, no public trading API yet, see "Variational" below), GRVT (`grvt|grv`, MARKET DATA ONLY in this version through its official API — trading is planned for a later release, see "GRVT" below), Extended (`extended|ext|x10`, Starknet, formerly X10 — MARKET DATA ONLY in this version through its official public API, see "Extended" below). v0.13.0+ also supports Hyperliquid Outcome markets (HIP-4) — fully-collateralized binary/range contracts; each outcome's quote token comes from `outcomeMeta.quoteToken` (USDC on every listed outcome as of 2026-10-12), minimum order value 10 quote tokens.
 
 ## Instructions
 
@@ -25,9 +25,10 @@ Activate whenever the user wants to do anything against perp-cli, including: sca
 
 This skill uses progressive disclosure. Read these on demand:
 
-- `references/commands.md` — full command tree for every group (market, account, trade, outcome, arb, funds, wallet, risk, history, strategy, background, alerts, settings, backtest)
+- `references/commands.md` — full command tree for every group (market, account, trade, outcome, options, print, vault, arb, funds, wallet, risk, history, strategy, background, alerts, settings, backtest)
 - `references/agent-operations.md` — non-interactive setup flows, idempotency rules, error codes, common mistakes
 - `references/strategies.md` — funding-arb decision framework + risk-management playbook (read before designing arb strategy)
+- `references/ws-library.md` — WebSocket library (0.15.0, @experimental), published standalone as **`@hypurrquant/perp-ws`** (zero dependencies; recommended for integrators — `npm install @hypurrquant/perp-ws`) and inside perp-cli as `perp-cli/ws` (same code, use it when perp-cli is already installed): build a live dashboard / funding comparison / account feed in the browser or Node (streams, events, nullability, comparator, user channels, errors, capability matrix). Cross-venue subscriptions use `canonicals` (e.g. `{ kind: "allMarkets", canonicals: ["BTC"] }`), never `symbols` (those are per-venue directory symbols); always surface `ready` rejections — an `idle` venue is not "fine"
 
 Also bundled under `scripts/`: `preflight.sh`, `arb-monitor.sh`, `funding-analysis.sh`, `spot-perp-scan.sh`, `validate-arb.sh`. Use these for repeatable multi-step diagnostics.
 
@@ -46,7 +47,7 @@ Also bundled under `scripts/`: `preflight.sh`, `arb-monitor.sh`, `funding-analys
 ### Step 1: Verify install + version
 
 ```bash
-perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.14.2
+perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.15.0
 ```
 
 If it is missing or older, ask the user before installing/upgrading (`npm install -g perp-cli@latest`) — never install on your own. If `perp` is not on PATH, prefix every command with `npx -y perp-cli@latest`.
@@ -96,6 +97,37 @@ Imported keys trade; `funds deposit|withdraw|transfer|bridge`, `wallet manage re
 - Funding rates on QFEX are unverified: excluded everywhere unless `perp --json arb scan --rates --include-unverified` (display only).
 - Withdrawals are disabled in perp-cli for now: `funds withdraw qfex` → `CAPABILITY_UNSUPPORTED` (also under `--dry-run`). Withdraw in the QFEX web app. Ondo Perps has no API withdrawals either.
 
+**RISEx** (`-e risex`, testnet = `-n testnet`, official API): **READ-ONLY in this perp-cli release** — RISEx trading is planned for a later release. Rules an agent must follow:
+- Works: market data (`market list|prices|info|book|trades|kline|funding -e risex`), `perp health`, RISEx rows in `perp --json arb scan` / `arb scan --rates` (funding is hourly and verified), MCP market-data tools, and account reads with only the master address selected (`portfolio`, `account positions|orders|history|trades|funding-history -e risex` — public by address, nothing is signed). `wallet agent verify risex` (read-only) still checks a signer registered by an earlier build.
+- Refused with `CAPABILITY_UNSUPPORTED` ("RISEx trading is planned for a later perp-cli release; in this version RISEx is read-only") before any key is read or request is sent — also under `--dry-run`: every `trade …` write (market / buy / sell / limit / cancel / cancel-all / leverage / close / stop / tpsl / edit / twap / …), `trade multi` legs, `arb exec|auto` legs, every `strategy …` command (bots, plans, TWAP / grid / DCA, `--exchanges` legs), `wallet agent approve|import|revoke|rotate risex` (`revoke --force` only clears the local record), `perp setup --venues risex`, `funds faucet risex`, and the MCP `trade_preview` / `trade_execute` / `trade_close` tools. Never try to trade RISEx through perp-cli — the user trades in app.rise.trade. `arb scan --basis` lists trading venues only, so RISEx is not in it; in `arb scan` a pair with a RISEx leg is `executable: false` (`readOnlyLegs`) — data only.
+- Deposits and withdrawals are app-only: `funds deposit|withdraw risex` → `CAPABILITY_UNSUPPORTED` (also under `--dry-run`), remediation app.rise.trade.
+- Funding: hourly, `current_funding_rate` = the last settled hourly print (verified against funding payments).
+
+**TxFlow** (`-e txflow`): UNOFFICIAL — TxFlow has no official API; perp-cli reads the undocumented API its web app uses, READ-ONLY. It may change or be blocked at any time; every JSON row says `venueApi: "unofficial"` (`apiStatus` in mixed tables, MCP meta), human output carries a footnote. Rules an agent must follow:
+- Works: `market list|prices|info|book|trades|kline -e txflow`, and TxFlow rows in `perp --json arb scan --rates --include-unverified` (display only). Funding is percent per hour on the venue, shown as a FRACTION per hour, and is UNVERIFIED (a live estimate) — never rank or trade on it.
+- Refused with `CAPABILITY_UNSUPPORTED` before any request: every trade / account / portfolio / funds / agent / builder / bot command, and funding history (`market funding`). Never try to trade TxFlow through perp-cli; the user trades on the TxFlow website.
+- A blocked read (`EXCHANGE_ERROR` "unofficial API refused …") is not retried and has no fallback; there is no testnet.
+
+**Variational** (`-e variational`, aliases `var`, `omni`): Variational Omni, read-only (market data) in perp-cli through its OFFICIAL documented API (`GET /metadata/v2/stats`, one call for all ~575 markets, cached ~5 s; venue limit 10 requests / 10 s per IP). Variational has no public trading API yet. It is an RFQ venue: one market maker (the OLP) quotes every trade — there is no order book.
+- Works: `market list|prices|info|funding|book -e variational`, `perp health` (official), and Variational rows in `perp --json arb scan --rates --include-unverified` / `--compare <sym> --include-unverified` only — display only, never ranked or traded: funding is UNVERIFIED (a moving predicted rate, not checked against settled payments). `US500-PERP` is the SPDR S&P 500 ETF, compared as `SPY`; SPX (SPX6900) and QNT (Quant) are never matched.
+- `market book` shows the OLP's INDICATIVE RFQ quotes at fixed notionals (min order, $1k, $100k, $1M when published; `kind: "rfqQuotes"`), never order-book levels; they may be up to 600 s old (`updatedAt`). `market mid|trades|kline` are refused (`CAPABILITY_UNSUPPORTED`).
+- Funding: the interval is PER MARKET (1h / 4h / 8h perps; `fundingHours` on each row), positive = longs pay. `fundingRate` is the fraction for one interval; `market funding <sym>` shows the current terms (`kind: "currentFunding"`: per interval, hourly, APR %, next time) — there is no funding history. `rateKind` is `predicted`: the rate for the window ending at `nextFundingTime`, recomputed during the window.
+- Perp symbols are the base (`BTC`); swaps keep their suffix (`XAU-SWAP`): daily-funded TradFi swaps with separate long / short rates, `fundingRate` null and never matched across venues. Open interest is published in USD, single-sided (`openInterestUsd`); base-unit `openInterest` is null. No index price, tick, lot or leverage is published (null).
+- Refused with `CAPABILITY_UNSUPPORTED` before any request: every trade / account / portfolio / funds / agent / builder / bot command (also with `--dry-run`). The user trades on omni.variational.io. No testnet. Variational's terms exclude US / Canada persons and sanctioned regions (perp-cli only warns).
+
+**GRVT** (`-e grvt`, testnet = `-n testnet`): official Market Data API (api-docs.grvt.io), READ-ONLY in this version. Rules an agent must follow:
+- Works: `market list|prices|info|book|trades|funding|kline -e grvt`, `perp health` (counted among the official venues), and GRVT rows in `perp --json arb scan --rates --include-unverified` (display only).
+- Symbols are the base ticker (`BTC`, `KPEPE`, `XAU`, `AAPL`; `BTC_USDT_Perp` also accepted); `venueSymbol` is GRVT's instrument name. Unknown symbols → `SYMBOL_NOT_FOUND`. Pre-IPO markets (OPENAI, ANTHROPIC, SPACEX) are never matched across venues.
+- Funding interval is PER MARKET (8 h or 4 h — `fundingHours`); rates are fractions per that interval (GRVT publishes percent). `market list|prices|info` rows carry the INDICATIVE rate of the running interval (`fundingRateKind: "predicted"`, moves until `nextFundingTime`); `market funding` is the settled history (`rateKind: "lastSettled"`, `intervalHours` per row). Funding is UNVERIFIED (not yet checked against settled payments) — never rank or trade on it.
+- `stepSize` is null (GRVT publishes a minimum size, `minSize`, but no lot step); `maxLeverage` / `marginTiers` come from GRVT's margin rules and are filled by `market list|prices|info` only (cached up to 6 h — `leverageAsOf` says when they were read) — MCP `get_markets` / `get_prices` rows have them null (price-only path). Equities match other venues only when reviewed; an unreviewed new GRVT equity has `canonical: null`.
+- Refused with `CAPABILITY_UNSUPPORTED` before any request (also under `--dry-run`): every trade / account / portfolio / funds / agent / builder / bot command and `setup` venue selection — remediation "GRVT is read-only (market data) in this version; trading is planned for a later release". GRVT trading needs KYC and is banned in restricted jurisdictions (US, CA, SG, HK, …) — relevant once trading lands.
+
+**Extended** (`-e extended`, aliases `ext` / `x10`; testnet = Sepolia via `-n testnet`): official public API (api.docs.extended.exchange), READ-ONLY in this version — counted as an official venue in `perp health`. Rules an agent must follow:
+- Works: `market list|prices|info|book|trades|funding|kline -e extended`, and Extended rows in `perp --json arb scan --rates --include-unverified` (display only — funding is UNVERIFIED: never rank or trade on it). `market list` rows carry `assetClass` (crypto / equity / etf / index / commodity / fx / preIpo; human table "Class" column), `venueSymbol` (wire name, e.g. `TSLA_24_5-USD`), `tickSize`, `minSize`, `tradable` (false while `REDUCE_ONLY` or `isOffHours`), `isRfq`, `tradingHours`.
+- Symbols: `assetName` without the `_24_5` suffix (`TSLA_24_5-USD` → `TSLA`, `SPX500m-USD` → `SPX500M`); `-e extended market book TSLA-USD` and the wire name also resolve. The crypto `SPX` market is SPX6900, not the S&P 500 (index = `SPX500M`). RWA tickers that are also crypto tickers (PURR = Hyperliquid Strategies Inc., QNT, BB, ON, ADI, BOT), XIAOMI and the crypto SPX are never matched across venues.
+- Funding: applied hourly; `fundingRate` in market rows = the current hour's ACCRUING rate (fraction per hour, recomputed every minute, rounded to 6 decimals; `fundingRateKind: "accruing"`, `nextFundingTime`), `market funding` = applied hourly prints (`rateKind: "lastSettled"`, `annualizedPct`). `_24_5` equities print 0 while their underlying is closed (weekends / holidays), so an annualized rate overstates them.
+- Refused with `CAPABILITY_UNSUPPORTED` before any request ("Extended is read-only (market data) in this version; trading is planned for a later release"): every trade / account / portfolio / funds / agent / builder / bot command, also under `--dry-run`. RFQ markets' REST order book is the indicative book.
+
 Venue rules for these: `trade limit` defaults to `--tif GTC` on every venue (arcus maps it to GTT; ondo offers GTC|IOC|ALO; FOK is never emulated → `CAPABILITY_UNSUPPORTED` where not offered); market orders on every venue are bounded by `--slippage-bps <n>` → `settings.slippageBps.<venue>` → `settings.defaultSlippageBps` (shipped default 50). Ondo (US, PA) and Arcus (US, CA, GB) print a one-time restricted-region notice on stderr when used with credentials (warn only, never blocks).
 
 ### Step 3: Discover (read-only)
@@ -133,6 +165,18 @@ perp --json -e hyperliquid --dex xyz --dry-run trade market GOLD buy 0.01
 - `portfolio --dexes xyz,…` adds HIP-3 dex balances; builder fees are never attached on HIP-3.
 - MCP tools cover native Hyperliquid perps only — use the CLI for HIP-3.
 
+#### Options market data (Derive, read-only)
+
+Derive (derive.xyz) options via the official public API — keyless, never trades. Not a perp venue (`-e derive` works only with `perp options`).
+
+```bash
+perp --json -e derive options expiries ETH                              # active expiries
+perp --json -e derive options chain ETH --expiry 2026-12-25 --strikes 10 # calls/puts per strike: bid/ask, mark, IV, greeks, OI
+perp --json -e derive options quote ETH-20261225-3500-P                 # one option
+```
+
+`schema: 1`; decimals are strings; `null` = unknown (empty side, uncomputable IV). Unknown underlying / expiry / instrument → `SYMBOL_NOT_FOUND`. Full reference: `references/commands.md` → "Options market data".
+
 ### Step 4: Validate before mutating
 
 For arb:
@@ -153,6 +197,8 @@ perp --json --dry-run -e <ex> trade buy <SYM> <SIZE> --smart
 > `trade check` does NOT read exchange-set leverage. Always pass `--leverage` explicitly.
 >
 > `--smart` (IOC at best bid/ask ± 1 tick) exists only on pacifica / hyperliquid / lighter / aster, and is refused (`CAPABILITY_UNSUPPORTED`) together with `--tp`/`--sl` or `--client-id`/`--auto-id`.
+>
+> Pacifica basket (pair trade): `perp --json --dry-run -e pacifica trade atomic --long BTC:50 --short ETH:50 --usd 1000` — one batch of market orders, NOT all-or-nothing (a leg can fill while another is refused → `ORDER_PARTIAL`; an unconfirmed leg → `ORDER_PENDING` + quarantine). A batch failure other than HTTP 400 / 429 quarantines every leg. Pacifica's Chase / OCO / Trailing Stop / Swarm / Trigger Swarm / Conditional orders have no documented API / SDK path (as of 2026-10-19); nearest here: `trade twap` (≈ Swarm) and `trade tpsl` (≈ OCO bracket exit).
 
 Show the dry-run output to the user. Wait for confirmation.
 
@@ -207,6 +253,13 @@ perp --json -e <ex> trade close-all                             # close all posi
 perp --json -e <ex> trade flatten                               # close ALL + cancel ALL orders
 ```
 
+### Pacifica Print and vaults (`perp print`, `perp vault`)
+
+Pacifica-only, details in `references/commands.md`. Reads first (`print games`, `print quote`, `print positions`, `vault list|info|positions`); every write is `--dry-run` first and needs the user's confirmation:
+- **Print** (`print deposit <game> long|short <usd> --strike <px> --leverage <n> [--cycles 1-1000]`) locks the deposit until a fill or until a cancel settles at the END of the running cycle (up to 30 days on `BTC_1M`). Before asking, show the user: cycle length, `--cycles`, leverage, `maxLoss` (deposit + premiums), and that `docsLiquidationPrice` is only an outer bound (a liquidation was observed earlier in one live case; the venue trigger is unpublished). Checkpoint-only evaluation applies while resting; after a fill it is an ordinary position in the main account (continuous liquidation, nets with an existing position) — `account positions`. The premium is not quoted by perp-cli. `print cancel` uses an UNOFFICIAL endpoint: live runs need `--unverified-endpoint`.
+- **Vaults** (`vault deposit <vault> <usd>`, `vault withdraw <vault> <shares>|--all`): third-party trading pools (can lose the whole deposit); every deposit restarts the lock-up for the whole balance; withdrawals only go to the own account, inside the vault's window. **`vault deposit` is master-only** (never an agent key). Pass the vault ADDRESS and confirm the shown manager with the user — nicknames are not unique (an ambiguous one is refused with the candidates).
+- `ORDER_PENDING` on any of them → NEVER resubmit with a new key; check `print positions` / `vault positions` against `error.details.before`. The only safe retry is the same command with `--idempotency-key <reported key>` (dedupe window unverified).
+
 ### Funds workflow (deposit / withdraw / transfer / bridge / rebalance)
 
 All money movement lives under `perp funds`:
@@ -367,7 +420,7 @@ Every response is `{ "ok": true, "data": ... }` or `{ "ok": false, "error": { "c
 | `PASSPHRASE_REQUIRED` | Vault passphrase needed | Ask the user to provide `OWS_PASSPHRASE` (or stdin); never put it on argv. |
 | `LOCK_HELD` | Another perp process holds a state lock | Wait ~5s and retry once; check `background list`. |
 | `NO_BRIDGE_ROUTE` | No supported bridge route (e.g. deBridge from Solana, HyperCore → Solana) | Use the route in `remediation` (e.g. `--provider cctp`). |
-| `RATE_LIMITED` / `EXCHANGE_UNREACHABLE` | Throttled / API down (reads) | Wait 5–10s, retry once; then skip that venue. |
+| `RATE_LIMITED` / `EXCHANGE_UNREACHABLE` | Throttled / API down (reads) | Wait 5–10s (or `retryAfterMs` when present — Pacifica sets it from its credit headers), retry once; then skip that venue. |
 | `INSUFFICIENT_BALANCE` | Not enough collateral on that venue | Reduce size or move funds first (user-confirmed). |
 | `SYMBOL_NOT_FOUND` | Not listed on this venue | `market list`. Don't add `-PERP`. |
 | `SIZE_TOO_SMALL` | Below venue minimum (HL TWAP: $100 total) | Compute `size × price`; raise size. |
@@ -377,8 +430,8 @@ Every response is `{ "ok": true, "data": ... }` or `{ "ok": false, "error": { "c
 ## Safety rules
 
 - **Unknown outcome (`ORDER_PENDING`) on ANY write** — orders, cancels, edits, leverage, withdraw / deposit / bridge / transfer: do NOT resubmit. Check `perp --json -e <ex> trade status c:<id> --symbol <S>` (the id in `remediation`), `account orders` / `account positions` / `portfolio`, and the tx hash / request id in `error.details` (`funds bridge status <id>` for bridges). Report to the user.
-- **Quarantine**: an unknown or unhedged outcome (arb, bots, `trade close`, `trade multi`) quarantines the symbol — global per symbol, scoped by network. It blocks opening orders, `arb exec`, `arb auto` and bots (`RISK_VIOLATION`); reduce-only orders pass. List: `perp --json strategy quarantine`. Clear only after the USER has verified the positions on the venues: `perp --json strategy quarantine-clear <SYM>`. `arb close` on a quarantined symbol needs `--force`.
-- **Risk gate**: `trade market / buy / sell / limit / split / market --split / scale-in / twap / multi / stop --no-reduce-only` check `~/.perp/risk.json` (`perp risk limits ...`); reduce-only is exempt. `--force` bypasses the limits (never quarantine) — only with explicit user consent.
+- **Quarantine**: an unknown or unhedged outcome (arb, bots, `trade close`, `trade multi`, `trade atomic`) quarantines the symbol — global per symbol, scoped by network. It blocks opening orders, `arb exec`, `arb auto` and bots (`RISK_VIOLATION`); reduce-only orders pass. List: `perp --json strategy quarantine`. Clear only after the USER has verified the positions on the venues: `perp --json strategy quarantine-clear <SYM>`. `arb close` on a quarantined symbol needs `--force`.
+- **Risk gate**: `trade market / buy / sell / limit / split / market --split / scale-in / twap / multi / atomic / stop --no-reduce-only` check `~/.perp/risk.json` (`perp risk limits ...`); reduce-only is exempt. `--force` bypasses the limits (never quarantine) — only with explicit user consent.
 - **Stops** (`trade stop`, `tpsl`) are reduce-only by default; `--no-reduce-only` is refused on ondo and qfex. `trade tpsl <SYM> long|short` = the OPEN position's side; legs are sized to the live position.
 - **Dry-run is default-deny**: commands that cannot simulate refuse `--dry-run` with `INVALID_PARAMS` (e.g. `trade twap`, `trade multi`, `trade cancel-stop`, `trade cancel-twap`, `strategy start / preset / grid / dca / quick-* / funding-arb`, `wallet agent approve`, `wallet rotate`). Simulate bots with `perp --json --dry-run strategy run <strategy>` / `perp --json --dry-run arb auto`.
 - **A dry-run is not a full venue check**: it validates arguments, the risk gate and quarantine, but some venue rules are enforced only on the live send — e.g. an off-grid limit price (`INVALID_TICK`) or `--no-reduce-only` on ondo / qfex (`CAPABILITY_UNSUPPORTED`). Those refusals happen before anything is sent.
@@ -422,7 +475,7 @@ qfex: `builder.qfex <uuid>` is a fee share (no extra fee, no approval; mainnet o
 
 ## MCP Server
 
-The package also ships a 22-tool MCP server (no API keys required for read-only market data — `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `get_outcome_markets`, `get_outcome_view`, `get_outcome_book`, plus 15 account/advisor tools):
+The package also ships a 29-tool MCP server (no API keys required for read-only market data — `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `get_outcome_markets`, `get_outcome_view`, `get_outcome_book`, `get_option_expiries`, `get_option_chain`, `get_option_quote` (Derive options), the read-only Pacifica Print / vault tools `pacifica_print_products`, `pacifica_print_quote`, `pacifica_print_positions`, `pacifica_vaults`, plus 15 account/advisor tools):
 
 MCP network: `PERP_NETWORK=mainnet|testnet` (validated; unset = mainnet); every result's `meta.network` says which. The only write tools, `trade_execute` / `trade_close`, run the same local risk gate as `perp trade` (no override over MCP), refuse non-reduce-only orders on quarantined symbols, and log every order.
 

package/skills/perp-cli/references/agent-operations.md

@@ -141,6 +141,11 @@ printf '%s' "$KEY" | OWS_PASSPHRASE=<pp> perp --json wallet set hl
 | `ondo` \| `ondo-perps` | off-chain (USDC deposits from Arbitrum / Ethereum) | API key id + secret (stdin) |
 | `arcus` | Robinhood Chain (USDG) | Ed25519 API key (`wallet agent approve arcus --master <w>` / `import`) |
 | `qfex` \| `qf` | custodial (USDC on Arbitrum One) | website key, imported by the user only (`wallet agent import qfex`) |
+| `risex` \| `rise` | RISE chain (USDC; deposit / withdraw in the RISEx app only) | none for market data; master address only for account reads. READ-ONLY in this release: trading is planned for a later release — every trade / agent / bot write → `CAPABILITY_UNSUPPORTED` |
+| `txflow` \| `txf` | — | none: MARKET DATA ONLY through an UNOFFICIAL API (every write → `CAPABILITY_UNSUPPORTED`) |
+| `variational` \| `var` \| `omni` | — | none: MARKET DATA ONLY through the official read-only API; no public trading API yet (every write → `CAPABILITY_UNSUPPORTED`) |
+| `grvt` \| `grv` | — (USDT; off-chain matching) | none: MARKET DATA ONLY in this version, official API (every write → `CAPABILITY_UNSUPPORTED`; trading planned) |
+| `extended` \| `ext` \| `x10` | Starknet | none: MARKET DATA ONLY in this version, official API (every write → `CAPABILITY_UNSUPPORTED`; trading planned) |
 
 Default `-e` = `settings.defaultExchange`, else `pacifica` — always pass `-e`.
 
@@ -168,6 +173,8 @@ perp --json funds deposit lighter ethereum 100        # L1 direct (min 1 USDC)
 perp --json funds deposit lighter cctp arbitrum 100   # via CCTP from Arbitrum (min 5 USDC)
 ```
 
+RISEx: deposits are app-only (`funds deposit risex` → `CAPABILITY_UNSUPPORTED`, remediation app.rise.trade). RISEx is read-only in this release (trading in a later release), so `funds faucet risex` is refused too.
+
 ### Withdraw from Exchange (`funds withdraw`)
 ```bash
 perp --json --dry-run funds withdraw hyperliquid 100   # plan first (every withdraw supports --dry-run)