perp-cli 0.12.17 → 0.14.1

package/dist/withdraw-gate.js

@@ -0,0 +1,131 @@
+/**
+ * Withdraw gate for venues whose withdrawals are authorized by an API key alone — no owner
+ * signature (settings.withdraw.<venue>; today: qfex). Design §14.12 #8.
+ *
+ * Before such a withdrawal is sent it must pass, locally:
+ *   1. a gate is configured at all (absent → refused);
+ *   2. the destination is on the allowlist;
+ *   3. amount ≤ maxPerTx;
+ *   4. today's total (UTC day, from this machine's ledger) + amount ≤ maxPerDay.
+ * The adapter enforces it inside withdraw(), so no caller can skip it.
+ *
+ * What it is NOT: a defence against key theft. Someone holding the key file does not use this
+ * CLI. That defence is a trading key WITHOUT the withdraw permission (a separate key for
+ * funding). The gate limits mistakes and misdirected automation: its allowlist can only be
+ * changed with an interactive terminal confirmation (confirmWithdrawGateChange), never under
+ * --json, a pipe, the MCP server or a job.
+ *
+ * Ledger: ~/.perp/withdraw-ledger.json — amounts and addresses only (no secrets, Rule #3).
+ * An attempt is recorded BEFORE it is sent and removed only on a definite refusal, so an
+ * unknown outcome counts against the day.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { writeKeystoreAtomic } from "./agent-wallet/venue-keystore.js";
+import { PerpError } from "./errors.js";
+function ledgerPath() {
+    const home = process.env["HOME"];
+    if (!home)
+        throw new PerpError("INVALID_PARAMS", "HOME is not set; cannot locate ~/.perp/withdraw-ledger.json");
+    return resolve(home, ".perp", "withdraw-ledger.json");
+}
+function readLedger() {
+    const path = ledgerPath();
+    if (!existsSync(path))
+        return []; // nothing withdrawn from this machine yet
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (e) {
+        throw new PerpError("INVALID_PARAMS", `Invalid ${path}: not valid JSON (${e instanceof Error ? e.message : String(e)})`, {
+            remediation: `The daily withdraw total cannot be computed, so withdrawals are refused. Inspect ${path}; move it aside only after checking today's withdrawals on the venue`,
+        });
+    }
+    if (!Array.isArray(parsed) || parsed.some(e => e === null || typeof e !== "object" || typeof e.id !== "string" || typeof e.venue !== "string"
+        || typeof e.network !== "string" || typeof e.amount !== "string" || !Number.isFinite(Number(e.amount)) || typeof e.to !== "string" || !Number.isFinite(Date.parse(e.at)))) {
+        throw new PerpError("INVALID_PARAMS", `Invalid ${path}: not a list of withdraw entries`, {
+            remediation: `The daily withdraw total cannot be computed, so withdrawals are refused. Inspect ${path}`,
+        });
+    }
+    return parsed;
+}
+function writeLedger(entries) {
+    const path = ledgerPath();
+    const dir = resolve(path, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeKeystoreAtomic(path, JSON.stringify(entries, null, 2));
+}
+function utcDay(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+/** Sum of the amounts attempted for venue + network on the UTC day of `nowMs`. */
+export function withdrawnOnDay(venue, network, nowMs) {
+    const day = utcDay(nowMs);
+    return readLedger()
+        .filter(e => e.venue === venue && e.network === network && e.at.slice(0, 10) === day)
+        .reduce((sum, e) => sum + Number(e.amount), 0);
+}
+function denied(venue, why, remediation, details) {
+    return new PerpError("POLICY_DENIED", `${venue} withdraw refused by the local withdraw gate: ${why}`, { exchange: venue, ...details, remediation });
+}
+/**
+ * Throws POLICY_DENIED unless the withdrawal passes `gate`. Nothing is sent before this returns.
+ * `gate` null = settings.withdraw.<venue> is not configured.
+ */
+export function assertWithdrawAllowed(venue, network, amount, to, gate, nowMs) {
+    const setHint = `Configure it in an interactive terminal: perp settings set withdraw.${venue} <address[+address…]>,<maxPerTx>,<maxPerDay>`;
+    if (gate === null) {
+        throw denied(venue, `settings.withdraw.${venue} is not configured — API-key withdrawals are off until you set an allowlist and limits`, setHint, {});
+    }
+    const n = Number(amount);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new PerpError("INVALID_PARAMS", `Withdraw amount must be a positive decimal (got "${amount}")`);
+    if (!gate.allowlist.includes(to.toLowerCase())) {
+        throw denied(venue, `destination ${to} is not on the allowlist`, `Withdraw to an allowlisted address, or change the allowlist yourself. ${setHint}`, { allowlist: gate.allowlist });
+    }
+    if (n > gate.maxPerTx) {
+        throw denied(venue, `amount ${amount} exceeds maxPerTx ${gate.maxPerTx}`, `Withdraw at most ${gate.maxPerTx} USDC per transaction, or raise the limit. ${setHint}`, { maxPerTx: gate.maxPerTx });
+    }
+    const today = withdrawnOnDay(venue, network, nowMs);
+    if (today + n > gate.maxPerDay) {
+        throw denied(venue, `amount ${amount} plus ${today} already attempted today (UTC) exceeds maxPerDay ${gate.maxPerDay}`, `Wait for the next UTC day or raise the limit. ${setHint}`, { maxPerDay: gate.maxPerDay, withdrawnToday: today });
+    }
+}
+/** Record an attempt (call BEFORE sending). Returns its id for forgetWithdrawAttempt. */
+export function recordWithdrawAttempt(venue, network, amount, to, nowMs) {
+    const entries = readLedger();
+    const id = randomUUID();
+    entries.push({ id, venue, network, amount, to: to.toLowerCase(), at: new Date(nowMs).toISOString() });
+    writeLedger(entries);
+    return id;
+}
+/** Remove an attempt the venue DEFINITELY refused (nothing left the account). */
+export function forgetWithdrawAttempt(id) {
+    writeLedger(readLedger().filter(e => e.id !== id));
+}
+/**
+ * Confirmation for creating or changing settings.withdraw.<venue>. Only an interactive
+ * terminal can confirm: --json, a non-TTY stdin/stdout (pipes, the MCP server, jobs) are
+ * refused, and there is no --yes.
+ */
+export async function confirmWithdrawGateChange(venue, gate, json) {
+    const what = `withdraw.${venue}: allow withdrawals to ${gate.allowlist.join(", ")} — up to ${gate.maxPerTx} USDC per transaction, ${gate.maxPerDay} USDC per UTC day`;
+    if (json || process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        throw new PerpError("POLICY_DENIED", `Changing the withdraw gate needs an interactive terminal confirmation (${what})`, {
+            remediation: `Run it yourself in a terminal, without --json: perp settings set withdraw.${venue} <address[+address…]>,<maxPerTx>,<maxPerDay>`,
+        });
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const a = (await rl.question(`  ${what}.\n  Anyone who can run perp on this machine can then withdraw to these addresses. Type the venue name (${venue}) to confirm: `)).trim().toLowerCase();
+        if (a !== venue)
+            throw new PerpError("INVALID_PARAMS", `withdraw.${venue} not changed — cancelled, nothing was saved`);
+    }
+    finally {
+        rl.close();
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "perp-cli",
-  "version": "0.12.17",
-  "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster",
+  "version": "0.14.1",
+  "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus",
   "bin": {
     "perp": "dist/index.js",
     "perp-mcp": "dist/mcp-server.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "vendor/lighter-signer"
   ],
   "type": "module",
   "scripts": {
@@ -18,6 +19,9 @@
     "test": "vitest run --exclude '**/integration/**'",
     "test:integration": "vitest run -c vitest.integration.config.ts",
     "test:all": "vitest run",
+    "e2e": "tsx scripts/e2e/run.ts",
+    "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"
   },
@@ -25,6 +29,12 @@
     "pacifica",
     "hyperliquid",
     "lighter",
+    "aster",
+    "lighter-rh",
+    "robinhood-chain",
+    "ondo",
+    "ondo-perps",
+    "arcus",
     "solana",
     "perps",
     "dex",
@@ -56,11 +66,9 @@
     "commander": "^13.1.0",
     "dotenv": "^16.5.0",
     "ethers": "^6.13.2",
-    "hyperliquid": "^1.7.7",
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-table": "^3.1.0",
-    "lighter-ts-sdk": "1.0.10",
     "react": "^19.2.4",
     "tweetnacl": "^1.0.3",
     "ws": "^8.19.0",
@@ -70,10 +78,11 @@
   "devDependencies": {
     "@types/node": "^25.3.3",
     "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.1.6",
     "ts-morph": "^27.0.2",
     "tsup": "^8.4.0",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.6"
   }
 }

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, HyperEVM, funding arb, or U-tokens (UBTC/UETH/USOL). Covers Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), and Aster (BNB 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, 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)."
 license: MIT
-allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
-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 wallet keys configured via 'perp wallet set EXCHANGE KEY' (Solana base58 / EVM hex / Aster API key). Skill is portable across Claude Code, Claude.ai, Cursor, Codex, and Gemini CLI — no platform-specific features."
+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.12.17"
+  version: "0.14.1"
 ---
 
 # perp-cli
 
-Multi-DEX perpetual futures CLI + MCP server for Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), and Aster (BNB Chain).
+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.
 
 ## Instructions
 
@@ -25,7 +25,7 @@ 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, arb, funds, wallet, risk, history, strategy, background, alerts, settings, backtest)
+- `references/commands.md` — full command tree for every group (market, account, trade, outcome, 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)
 
@@ -33,40 +33,70 @@ Also bundled under `scripts/`: `preflight.sh`, `arb-monitor.sh`, `funding-analys
 
 ### Critical rules
 
-1. **Always pass `--json`.** Without it, output is human-formatted and hard to parse.
-2. **Always run `--dry-run` first** for any mutating trade (open / close / bridge / withdraw). Show the result, get user confirmation, then execute without `--dry-run`.
-3. **Always use `--fields`** when you only need specific data — saves tokens.
-4. **NEVER run `perp setup`, `perp init`, or `perp wallet setup`.** All three are interactive and will hang the agent. Use `perp wallet set <exchange> <key>` instead.
-5. **NEVER trade without explicit user confirmation.** A dry-run is not consent.
-6. **NEVER read `~/.perp/.env` or other key files.** The CLI reads them — you should not.
-7. **NEVER manually add `-PERP` suffix** to symbols. Use bare names (`BTC`, `SOL`, `ICP`); the CLI resolves exchange-specific naming.
+1. **Always pass `--json`.** Without it, output is human-formatted and hard to parse. `ok:false` also exits 1.
+2. **Always pass `-e <venue>`** on venue-scoped commands. The default is `settings.defaultExchange`, else `pacifica` — never rely on it.
+3. **Always run `--dry-run` first** for any mutating command that supports it (`--help` says "supports --dry-run"). Show the result, get user confirmation, then execute without `--dry-run`. Commands without dry-run support refuse `--dry-run` with `INVALID_PARAMS` (see "Safety rules").
+4. **Always use `--fields`** when you only need specific data — saves tokens.
+5. **Avoid bare `perp setup` / `perp init` / `perp wallet setup`** — they prompt and will hang an agent. Use `printf '%s' "$KEY" | OWS_PASSPHRASE=<pp> perp --json wallet set <exchange>` for key registration (key on stdin; a key on argv or `-k` is rejected), or `perp --json setup --non-interactive --wallet <ows-wallet> --venues <list> [--default-venue <v>] [--slippage-bps <n>] [--slippage <venue>=<bps>]` (new wallet: `--wallet-name <name>` with the passphrase in `OWS_PASSPHRASE`; agent registration only with `--approve-agents --yes`, after user confirmation) (and `OWS_PASSPHRASE=<pp> perp wallet setup --name <n> --max-tx-usd <usd> --max-daily-usd <usd>`) when the wizard is required. The passphrase goes in `OWS_PASSPHRASE` or stdin — the root `--passphrase` flag is deprecated (visible in `ps`).
+6. **NEVER trade without explicit user confirmation.** A dry-run is not consent.
+7. **NEVER read `~/.perp/.env` or other key files.** The CLI reads them — you should not.
+8. **NEVER manually add `-PERP` suffix** to symbols. Use bare names (`BTC`, `SOL`, `ICP`); the CLI resolves exchange-specific naming.
+9. **NEVER resubmit after `ORDER_PENDING`** (or any unknown outcome). See "Safety rules".
 
 ### Step 1: Verify install + version
 
 ```bash
-perp --version 2>/dev/null  # must be >= 0.12.17
-npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
+perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.14.1
 ```
 
-If `perp` is not on PATH, prefix every command with `npx -y perp-cli@latest`.
+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`.
 
 ### Step 2: Verify wallet + balance
 
 ```bash
 perp --json wallet show               # confirms configured exchanges
-perp --json -e <ex> account balance   # per-exchange USDC available
+perp --json portfolio -e <venue-id>   # per-exchange USDC available; full id (hyperliquid, not hl) — portfolio rejects aliases
 ```
 
 If any required exchange is missing, register it (user supplies the key):
 
 ```bash
-perp --json wallet set pac   <SOLANA_BASE58_KEY>     # Pacifica
-perp --json wallet set hl    <EVM_HEX_KEY>           # Hyperliquid
-perp --json wallet set lt    <EVM_HEX_KEY>           # Lighter (auto-generates API key, default index 4)
-perp --json wallet set aster <ASTER_API_KEY>         # Aster (BNB Chain)
+printf '%s' "$EVM_HEX_KEY" | OWS_PASSPHRASE=<pp> perp --json wallet set hl          # Hyperliquid / Lighter / Aster (EVM)
+printf '%s' "$SOLANA_BASE58_KEY" | OWS_PASSPHRASE=<pp> perp --json wallet set pac   # Pacifica (Solana)
 ```
 
-The same EVM key works for both Hyperliquid and Lighter.
+The key is read from stdin (never argv — an argv key is rejected) and imported into the OWS vault; the imported wallet becomes `owsActiveWallet`, which serves every venue. The same EVM key works for Hyperliquid, Lighter and Aster. Lighter trading additionally needs `perp wallet agent approve lighter`.
+
+Lighter RH / Ondo Perps / Arcus have no `wallet set` path — register an agent / API key (user runs it; Ondo reads key id + secret from stdin):
+
+```bash
+perp --json wallet agent approve lighter-rh
+printf '%s\n%s\n' "$KEY_ID" "$SECRET" | perp --json wallet agent approve ondo
+perp --json wallet agent approve arcus --master <ows-wallet>   # address must be on the Arcus access whitelist
+```
+
+**No master wallet on this computer?** The user can create the agent / API key on the exchange website and import it — key on stdin only, verified against the venue before it is stored (`verification.status` is `"unverified"` only for Pacifica, which lists bindings master-signed only):
+
+```bash
+printf '%s' "$AGENT_KEY" | perp --json wallet agent import hyperliquid               # master read from HL
+printf '%s' "$AGENT_KEY" | perp --json wallet agent import aster --master-address 0x…  # also Aster testnet
+printf '%s' "$AGENT_KEY" | perp --json wallet agent import pacifica --master-address <SOL>
+printf '%s' "$API_KEY" | perp --json wallet agent import lighter --account-index <n> --api-key-index <slot>
+printf '%s' "$ED25519_KEY" | perp --json wallet agent import arcus --master-address 0x…
+```
+
+Imported keys trade; `funds deposit|withdraw|transfer|bridge`, `wallet manage referral set` and `wallet agent approve` need the master → `NO_SIGNER_AVAILABLE` (tell the user to do it on the website or `perp wallet import` the master). `wallet agent revoke` of an imported key needs `--local-only` and does NOT revoke it on the exchange; `rotate` is refused (new key on the website → `import --replace`).
+
+**QFEX** (`-e qfex`, testnet = QFEX UAT): keys are created on the QFEX website and imported by the USER (`perp wallet agent import qfex [--account-id <uuid>]` — the resolved account UUID must be confirmed). Rules an agent must follow:
+- Works: market / IOC reduce-only closes (`trade close/close-all/flatten/reduce`), reduce-only stop-market orders (`trade stop`, `trade tpsl` TP/SL legs, `--tp/--sl` as separate stops after the verified fill; cancel with `trade cancel <S> <id>` or `trade cancel-stop`), `trade edit` of a plain LIMIT / ALO (the venue assigns a new order id; the client id is kept).
+- Refused with `CAPABILITY_UNSUPPORTED` (do not work around): resting reduce-only limits (GTC / ALO / FOK, `scale-tp`), stop-limit and opening stops, amend of a reduce-only order, `--client-id`, non-USD-quoted markets, unattended automation (bots / plans / TWAP / DCA / grid / background jobs), QFEX as a funding-arb / funding-bot leg.
+- After a close, reduce-only / stop orders left on a now-flat symbol are listed as a WARNING (the venue does not cancel them) — cancel them, or use `trade flatten`, which cancels them.
+- Limit GTC / ALO returns `status: accepted, finality: pending` after the ACK; `open` only via `perp --json trade status c:<id> --symbol <S> -e qfex`.
+- `ORDER_PENDING` = outcome unknown: NEVER resubmit; check with the `c:<id>` in the remediation.
+- 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.
+
+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)
 
@@ -86,13 +116,30 @@ perp --json arb scan --live --interval 60         # continuous monitoring
 
 Common knobs: `--min <pct>`, `--top <n>`, `--hold-days <n>`, `--bridge-cost <usd>`, `--size <usd>`.
 
+#### HIP-3 dexes (part of Hyperliquid, not a separate venue)
+
+HIP-3 dexes are selected on the Hyperliquid venue with the root `--dex <name>` flag; every market / account / trade command works the same way. Same account and wallet as native Hyperliquid perps.
+
+```bash
+perp --json -e hyperliquid market hip3                               # list deployed dexes (name, markets)
+perp --json -e hyperliquid --dex xyz market list                     # markets on dex "xyz"
+perp --json -e hyperliquid --dex xyz market info GOLD                # symbols WITHOUT the "xyz:" prefix
+perp --json -e hyperliquid --dex xyz account positions               # positions on that dex only
+perp --json -e hyperliquid --dex xyz --dry-run trade market GOLD buy 0.01
+```
+
+- `--dex` with any other `-e` venue → `INVALID_PARAMS` (never ignored).
+- A dex symbol without `--dex` (e.g. `-e hyperliquid market mid xyz:GOLD`) → `SYMBOL_NOT_FOUND` with remediation `--dex xyz`; it is never read from the native dex.
+- `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.
+
 ### Step 4: Validate before mutating
 
 For arb:
 
 ```bash
-perp --json -e <longEx>  account balance              # check available USDC
-perp --json -e <shortEx> account balance              # check available USDC
+perp --json portfolio -e <longEx>                     # check available USDC (long leg)
+perp --json portfolio -e <shortEx>                    # check available USDC (short leg)
 perp --json --dry-run arb exec <SYM> <longEx> <shortEx> <USD>
 ```
 
@@ -104,6 +151,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`.
 
 Show the dry-run output to the user. Wait for confirmation.
 
@@ -112,10 +161,12 @@ Show the dry-run output to the user. Wait for confirmation.
 After explicit user confirmation:
 
 ```bash
-# Perp-perp arb (auto-matches both legs)
-perp --json arb exec <SYM> <longEx> <shortEx> <USD> --smart --reconcile
+# Perp-perp arb: legs are SEQUENTIAL — long first, then the short sized to the verified long fill;
+# reconcile is always on (the long is trimmed reduce-only to the short's verified fill).
+# An unconfirmed leg quarantines the symbol (see "Safety rules").
+perp --json arb exec <SYM> <longEx> <shortEx> <USD> --smart
 
-# Spot+perp arb (spot has 0 funding cost; spot exchanges: hl, lt)
+# Spot+perp arb (spot has 0 funding cost; spot:<venue> = hl, lt, lrh, aster, ondo)
 perp --json arb exec <SYM> spot:hl hl <USD>
 perp --json arb exec <SYM> spot:lt pac <USD>
 
@@ -147,6 +198,8 @@ perp --json arb close <SYM>                                     # perp-perp arb
 perp --json arb close <SYM> --pair <longEx>:<shortEx>           # disambiguate
 perp --json arb close <SYM> --spot-exch hl --perp-exch hl       # spot+perp
 perp --json arb close <SYM> --smart                             # IOC limits
+perp --json arb close <SYM> --force                             # quarantined symbol — only after the user checked positions
+perp --json arb close <SYM> --state-only --yes                  # drop a stale state entry (arb status staleStateEntries); sends no order
 
 # Single trade
 perp --json -e <ex> trade close <SYM>                           # close one symbol
@@ -164,27 +217,37 @@ perp --json funds deposit hyperliquid 100
 perp --json funds deposit pacifica 100
 perp --json funds deposit lighter ethereum 100              # L1 direct
 perp --json funds deposit lighter cctp arbitrum 100         # via CCTP
-perp --json funds withdraw hyperliquid 100
-perp --json funds transfer 100 <ADDRESS>                    # HL internal (instant)
+perp --json funds withdraw hyperliquid 100 [--chain arbitrum|ethereum|base]   # CCTP to your own wallet
+perp --json funds transfer 100 <ADDRESS>                    # HL internal (instant) — allowlisted destinations only
 
 # Cross-chain bridge (auto-cheapest cctp/relay/debridge)
 perp --json funds bridge quote --from solana --to arbitrum --amount 100
 perp --json funds bridge send  --from solana --to arbitrum --amount 100
 perp --json funds bridge status <orderId>                   # poll until success
 
-# Inter-exchange rebalance (orchestrated withdraw → bridge → deposit)
+# Inter-exchange rebalance
 perp --json funds rebalance check
 perp --json funds rebalance plan
-perp --json funds rebalance execute --auto-bridge
+perp --json --dry-run funds rebalance execute --auto-bridge   # status "simulated" (moves[].status "dry_run"), or "balanced" (nothing to move)
+perp --json funds rebalance execute --auto-bridge             # withdraw → bridge ONLY; no deposit
 ```
 
 Always run `funds bridge quote` before `funds bridge send` so the user sees fees + ETA.
 
+- `funds rebalance execute` returns `ok:true` even when a move failed: check EVERY `moves[].status` (`withdrawn`, `bridged`, `same_chain`, `needs_bridge`, `withdraw_failed`, `bridge_failed`). It never deposits — after the bridge arrives, deposit manually (`funds deposit <venue> <amt>`).
+- `funds transfer <amt> <addr>` (HL) and `funds withdraw hyperliquid --to <other address>` require the destination on the `settings withdraw.hyperliquid` allowlist (`POLICY_DENIED` otherwise). Only the user can set it, in an interactive terminal (`--json` / piped → `POLICY_DENIED`). NEVER try to set or change `withdraw.<venue>` yourself.
+- HL withdraw goes over CCTP (native USDC); on Arbitrum a 0.2 USDC forwarding fee is deducted (an amount ≤ the fee → `SIZE_TOO_SMALL`).
+- Bridges: exactly `--amount` leaves the wallet (fees come out of it); a deBridge `nativeFee` is shown separately and is paid in the source chain's native token. Solana-origin deBridge is refused (`NO_BRIDGE_ROUTE`) → `--provider cctp`. `--fast` = fast CCTP finality (higher fee).
+- `funds bridge exchange --from <ex> --to <ex>` bridges the master wallet's OWN USDC between the venues' chains (pacifica → solana, lighter → arbitrum); it does NOT withdraw from / deposit into Pacifica or Lighter. Exception hyperliquid: `--from hyperliquid` spends HyperCore spot USDC, `--to hyperliquid` credits HyperCore perps. HyperCore → Solana is refused (`NO_BRIDGE_ROUTE`).
+
+Relay swaps between assets (`--from-asset` / `--to-asset`, chains `robinhood`, `arbitrum`, `bsc`, `base`, destination `solana`): run `perp --json --dry-run funds bridge send ...` first — it prints the locally verified quote (amount in, expected out, protocol-guaranteed minimum, fees, ETA) and the min-out verdict without loading a key. Stable → native (e.g. USDG → SOL / ETH) needs `--min-out`. The recipient is always the master wallet's own address; an `ORDER_PENDING` result carries the Relay request id — never bridge again before checking it.
+
 ### Strategy engine (20 algorithms + scripted plans)
 
 ```bash
 perp strategy list-strategies                                 # 20 registered
-perp strategy run <strategy> [symbol]                         # run any strategy
+perp strategy run <strategy> [symbol]                         # run any strategy (multi-venue: --exchanges must include the -e venue)
+perp --json --dry-run strategy run <strategy> [symbol]        # simulate: actions logged, never sent
 perp strategy apex [symbol]                                   # APEX orchestrator
 perp strategy reflect                                         # performance analysis
 perp --json strategy plan validate <FILE>                     # validate scripted plan
@@ -196,17 +259,22 @@ perp --json strategy plan execute <FILE> --dry-run            # dry-run scripted
 Background daemon (tmux):
 
 ```bash
+perp --json --dry-run arb auto --min-spread 30 --size 100     # simulate first (--background inherits --dry-run)
 perp --json arb auto --min-spread 30 --size 100 --background
 perp --json background list
 perp --json background logs <id> -f
-perp --json background stop <id>
+perp --json background stop <id> [--timeout 90]   # graceful: SIGINT, job cancels its orders, waits, reports what is left on the venue
 ```
 
+`strategy funding-arb` is monitor-only unless `--auto-execute`. Bots: `equity` is `null` when a balance read fails — arb strategies then skip new entries and the bot stops after 10 consecutive unknown ticks; `ordersPlaced` counts orders sent, `fills` only venue-reported fills — a resting order is placed, not filled.
+
+Background jobs inherit the parent's `-n`, `--dry-run`, `-e`, `--ows`, `-w`, `--no-agent`, `--dex`, and never receive key material (argv/env): they resolve credentials from the OWS vault / agent keystores / `~/.perp/.env` themselves. `--background` with `-k`, `--passphrase`, `--ows-key` or a shell-exported key / `OWS_PASSPHRASE` → `INVALID_PARAMS` — register an agent (`perp wallet agent approve <venue>`), which signs without the master passphrase.
+
 ### Position sizing & safety
 
 - Single position notional < **80%** of that exchange's available balance.
 - Leverage 1–3x for arb; never above 5x for arb positions.
-- `arb exec` auto-matches both legs to the same size; pass `--reconcile` to trim mismatches.
+- `arb exec` sizes the short to the verified long fill and always reconciles; still check `arb status` (`unconfirmedPairs`, `staleStateEntries`) afterwards.
 - ALWAYS follow `longExch`/`shortExch` from `arb scan` — NEVER reverse direction.
 - NEVER enter if `netSpread <= 0` or `netSpread < estimated round-trip slippage`.
 - Capital that's mid-bridge is "at risk" and unhedged — factor it in.
@@ -222,8 +290,8 @@ For deeper risk-management framework, read `references/strategies.md`.
 perp --json arb scan --min 10 --top 10
 # 2. Show top 3 to user; ask which to evaluate
 # 3. Check balances on the two exchanges
-perp --json -e <longEx> account balance
-perp --json -e <shortEx> account balance
+perp --json portfolio -e <longEx>
+perp --json portfolio -e <shortEx>
 # 4. Recommend size + dry-run
 perp --json --dry-run arb exec BTC <longEx> <shortEx> 100
 # 5. After user confirmation:
@@ -265,16 +333,13 @@ perp --json funds bridge status <orderId>             # poll until completed
 perp --json funds deposit hyperliquid 500
 ```
 
-Or use the orchestrated path:
-
-```bash
-perp --json funds rebalance plan
-perp --json funds rebalance execute --auto-bridge
-```
+`funds rebalance execute --auto-bridge` only withdraws and bridges — check every `moves[].status`, then deposit by hand (`funds deposit hyperliquid <amt>`) after the bridge arrives.
 
 ### Example 5: "Run a delta-neutral funding bot in background"
 
 ```bash
+perp --json --dry-run arb auto --min-spread 30 --close-spread 5 --size 100 --max-positions 5
+# → show the simulation, ask confirmation
 perp --json arb auto --min-spread 30 --close-spread 5 --size 100 --max-positions 5 --background
 perp --json background list
 perp --json background logs <id> -f
@@ -284,17 +349,40 @@ perp --json background stop <id>
 
 ## Troubleshooting
 
-Every response is `{ "ok": true, "data": ... }` or `{ "ok": false, "error": { "code": "...", "retryable": true|false } }`. Always check `ok` first.
+Every response is `{ "ok": true, "data": ... }` or `{ "ok": false, "error": { "code": "...", "retryable": true|false, "remediation"?: "..." } }`; `ok:false` exits 1. Always check `ok` first and follow `error.remediation`. `retryable: true` → wait and retry ONCE, and only for read-only commands — a write is never blindly retried.
 
 | Error code | Meaning | Action |
 |---|---|---|
-| `RATE_LIMITED` | Exchange throttled the request | Wait 5s, retry up to 3 times. For Lighter, space calls 3s+ apart. |
-| `EXCHANGE_UNREACHABLE` | API down or network issue | Wait 10s, retry. After 3 failures, skip that exchange and continue. |
-| `INSUFFICIENT_BALANCE` | Not enough USDC on that exchange | Reduce size or `funds bridge`/`funds rebalance` first. |
-| `SYMBOL_NOT_FOUND` | Symbol not listed on this exchange | Run `market list` to verify. Don't add `-PERP` suffix manually. |
-| `SIZE_TOO_SMALL` | Below exchange minimum (HL is $10 notional) | Compute `size × price` before submitting; raise size. |
-| `DUPLICATE_ORDER` | Same `--client-id` already submitted | Already executed — check `account positions` instead of retrying. |
-| `INVALID_SIGNATURE` (Lighter) | API key drift / not approved | `perp wallet agent approve lighter --master <wallet>` to regenerate. |
+| `ORDER_PENDING` | A write was sent, outcome unknown | NEVER resubmit. See "Safety rules". |
+| `ORDER_PARTIAL` | Part of a multi-leg / close succeeded | Don't retry; check positions per venue, close residuals by hand (may be quarantined). |
+| `ORDER_REJECTED` / `ACTION_REJECTED` | Definitely not placed / not executed | Fix the cause from `error.message`; a new attempt is a new decision (ask the user). |
+| `RISK_VIOLATION` | Local risk limit breached, or symbol quarantined | Report to the user. `--force` only with explicit user consent, and never bypasses quarantine. |
+| `CAPABILITY_UNSUPPORTED` | Venue/feature combination not offered | Do NOT work around it (no emulation via other orders/venues); tell the user. |
+| `INVALID_TICK` | Limit/trigger price off the venue grid (HL: ≤ 5 significant figures) | Refused, never rounded — re-price on the grid and confirm with the user. |
+| `INVALID_PARAMS` | Bad argument (incl. strict sizes: `1,000` / `1e3` / `10abc` refused; `--dry-run` on a command without dry-run) | Fix the argument. |
+| `CLI_ERROR` | Command parse error (unknown command / missing option) | Check `<cmd> --help`. |
+| `NO_SIGNER_AVAILABLE` | No key that may sign this (e.g. imported agent key for a master-only action) | User does it on the website, or `perp wallet import`s the master. |
+| `AGENT_NOT_REGISTERED` / `AGENT_EXPIRED` | Agent key missing, on the other network, or expired | Follow `remediation`: master on this computer → `perp wallet agent approve <venue> [--rotate]` (master-signed: user consent); imported key → new key on the website, `wallet agent import <venue> --replace`. |
+| `POLICY_DENIED` | Local withdraw gate / OWS policy refused | Never change `withdraw.<venue>` — only the user can, in a terminal. |
+| `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. |
+| `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. |
+
+`--client-id` (`trade market/buy/sell/limit`): an id already recorded in `~/.perp/client-ids.jsonl` (and not marked failed) returns `ok:true` with `data.duplicate: true` and sends nothing — local tracking only, not a venue check (it is NOT a `DUPLICATE_ORDER` error). Formats: Pacifica a full UUID, Hyperliquid `0x` + 32 hex; QFEX refuses `--client-id` (use `--auto-id`); `--smart` + client id → `CAPABILITY_UNSUPPORTED`.
+
+## 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.
+- **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.
+- **`wallet rotate`** creates a new wallet and transfers assets, with no dry-run — only on the user's explicit request.
 
 ### Common mistakes
 
@@ -311,16 +399,32 @@ For a full troubleshooting + non-interactive flow guide, read `references/agent-
 ## Referrals (optional, ask once per setup)
 
 ```bash
-perp --json settings referrals on    # opt-in (no extra fees — exchange rebates only)
-perp --json settings referrals off
+perp --json --dry-run -e hyperliquid wallet manage referral set   # preview (nothing signed)
+perp --json -e hyperliquid wallet manage referral set [code]      # signs + sends ONE referral action
+perp --json -e lighter wallet manage referral set [code]          # Lighter (needs an agent key)
+```
+
+Referral codes are never applied implicitly (adapter creation signs nothing). When the user first sets up a wallet, ask:
+> "perp-cli development is supported by optional referrals. Apply the referral code? It signs one referral action on the venue; no extra fees — only exchange rebates are used."
+
+## Builder fees (OFF by default — never enable on your own)
+
+Builder fees are extra fees on the USER's perp orders, paid to a third-party builder. perp-cli attaches none unless the user explicitly set `settings builder.<venue>` AND the venue approval is confirmed. Do not configure or approve a builder unless the user asks for it.
+
+```bash
+perp --json wallet builder status [venue]                 # support, config, approval, attaches?
+perp --json --dry-run wallet builder approve <venue>      # plan only — show it to the user
+perp --json wallet builder approve <venue> --yes          # only after explicit user consent (master-signed)
+perp --json --no-builder -e <ex> trade market BTC buy 0.1   # one run without the fee
 ```
 
-When the user first sets up a wallet, ask:
-> "perp-cli development is supported by optional referrals. Enable? No extra fees — only exchange rebates are used."
+qfex: `builder.qfex <uuid>` is a fee share (no extra fee, no approval; mainnet only). Unsupported: lighter, lighter-rh, arcus (`CAPABILITY_UNSUPPORTED`). An order whose approval is missing or unknown is sent without the fee (`execution.notes`); `execution.builderFee` records what was attached.
 
 ## MCP Server
 
-The package also ships a 18-tool MCP server (no API keys required for read-only market data):
+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):
+
+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.
 
 ```json
 {