perp-cli 0.12.15 → 0.14.0

package/skills/perp-cli/SKILL.md

@@ -1,219 +1,423 @@
 ---
 name: perp-cli
-description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), Lighter (Ethereum), and Aster (BNB Chain). Use when user asks to: trade perps, check funding rates, scan arbitrage (perp-perp or spot-perp), delta-neutral strategies, bridge USDC, manage positions/orders, deposit/withdraw, spot+perp hedge, HIP-3 DEX trading, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, Aster, HyperEVM, funding arb, U-token (UBTC/UETH/USOL)."
-allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y 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)."
 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.12.15"
+  version: "0.14.0"
 ---
 
-# perp-cli Agent Guide
+# perp-cli
 
-Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), 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.
 
-[![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)
+## Instructions
 
-## MCP Server
+### When to use this skill
 
-18 tools, 3 resources, 2 prompts. No API keys required for market data — explore prices, orderbooks, funding rates, and arb opportunities without setup.
+Activate whenever the user wants to do anything against perp-cli, including: scanning funding-rate arbitrage, executing perp-perp or spot+perp legs, running long-running strategy bots, moving USDC between chains/exchanges, checking account/portfolio state, configuring wallets, or troubleshooting any of the above.
 
-```json
-{
-  "mcpServers": {
-    "perp-cli": {
-      "command": "npx",
-      "args": ["-y", "-p", "perp-cli", "perp-mcp"]
-    }
-  }
-}
-```
+**Do NOT** answer trading questions from memory — always run the actual CLI command and parse its JSON output.
+
+### Reference files (load only when needed)
+
+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/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)
+
+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.
 
-## Rules
+### Critical rules
+
+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 || npx -y perp-cli@latest --version   # must be >= 0.14.0
+```
 
-1. **Always use `--json`** on every command.
-2. **Always use `--dry-run`** before any mutating trade (then execute without it after user confirms).
-3. **Always use `--fields`** to reduce output when you only need specific data (saves tokens).
-4. **NEVER use `perp setup`** (alias: `perp init`) — interactive, will hang.
-5. **NEVER trade without user confirmation.**
-6. **NEVER read ~/.perp/.env or key files.**
+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`.
 
-## Install
+### Step 2: Verify wallet + balance
 
 ```bash
-perp --version 2>/dev/null  # check if exists (must be >= 0.12.15)
-npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
+perp --json wallet show               # confirms configured exchanges
+perp --json portfolio -e <venue-id>   # per-exchange USDC available; full id (hyperliquid, not hl) — portfolio rejects aliases
 ```
 
-Use `perp` if global install works, otherwise `npx -y perp-cli@latest` as prefix.
+If any required exchange is missing, register it (user supplies the key):
 
-## Global Flags
+```bash
+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)
+```
 
-`--json` (required) | `-e hl/pac/lt/aster` (exchange) | `--dex <name>` (HIP-3) | `-w <wallet>` | `--dry-run` | `--fields <f1,f2>` | `--ndjson`
+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`.
 
-## Wallet Setup
+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 set pac <SOLANA_KEY>   # Pacifica
-perp --json wallet set hl <EVM_KEY>       # Hyperliquid
-perp --json wallet set lt <EVM_KEY>       # Lighter (API key auto-generated)
-perp --json wallet set aster <API_KEY>    # Aster (BNB Chain)
-perp --json wallet show                   # verify
+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
 ```
 
-## Core Workflow: Arb
+**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…
 ```
-1. perp --json arb scan                    # scan opportunities (perp-perp + spot-perp + HIP-3)
-2. perp --json account balance             # check balances across all exchanges
-3. perp --json --dry-run arb exec <SYM> <longEx> <shortEx> <$>   # dry-run (auto-sizes)
-4. [show result to user, get confirmation]
-5. perp --json arb exec <SYM> <longEx> <shortEx> <$>             # execute
-6. perp --json arb status                  # monitor PnL + funding income
-7. perp --json arb close <SYM>            # close both legs
+
+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 need `settings.withdraw.qfex` (allowlist + limits), which only the user can set in an interactive terminal — an agent cannot set or change it. `perp --json --dry-run funds withdraw qfex <amt> --to <addr>` shows the gate verdict.
+
+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)
+
+```bash
+perp --json arb scan                              # all modes (perp-perp + spot-perp), default --min 10 (% annual)
+perp --json arb scan --mode perp-perp --top 10
+perp --json arb scan --mode spot-perp --top 10
+perp --json arb scan --rates                      # raw funding rates
+perp --json arb scan --basis [<symbol>]           # cross-exchange basis
+perp --json arb scan --gaps                       # cross-exchange price gaps
+perp --json arb scan --hip3                       # HIP-3 cross-dex spreads
+perp --json arb scan --history <symbol>           # historical funding
+perp --json arb scan --compare <symbol>           # one symbol across all exchanges
+perp --json arb scan --positions                  # funding impact on open positions
+perp --json arb scan --live --interval 60         # continuous monitoring
 ```
 
-### Scan Modes
+Common knobs: `--min <pct>`, `--top <n>`, `--hold-days <n>`, `--bridge-cost <usd>`, `--size <usd>`.
 
-| Flag | Description |
-|------|-------------|
-| _(default)_ | All modes combined (perp-perp + spot-perp) |
-| `--rates` | Funding rates across exchanges |
-| `--basis [symbol]` | Cross-exchange basis/price diff |
-| `--gaps` | Price gaps |
-| `--hip3` | HIP-3 on-chain dex opportunities |
-| `--history [symbol]` | Historical funding data |
-| `--compare <symbol>` | Compare symbol across exchanges |
-| `--positions` | Existing position exit signals |
-| `--live` | Continuous monitoring |
+### Step 4: Validate before mutating
 
-### Spot+Perp Arb
+For arb:
 
-Spot has 0 funding cost. Use `spot:<exch>` prefix for the long leg:
+```bash
+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>
+```
+
+For a single trade:
 
 ```bash
-perp --json arb exec ETH spot:hl hl 100    # spot buy(HL) + perp short(HL)
-perp --json arb exec BTC spot:lt pac 50     # spot buy(LT) + perp short(PAC)
-perp --json arb close ETH                   # sells spot + buys back perp
+perp --json -e <ex> trade check <SYM> <SIDE> <SIZE> --leverage <N>
+perp --json --dry-run -e <ex> trade buy <SYM> <SIZE> --smart
 ```
 
-Spot exchanges: HL, LT. Pacifica and Aster are perp-only.
+> `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.
+
+### Step 5: Execute
 
-## Strategy Engine (19 bot algorithms + nested scripted plans)
+After explicit user confirmation:
 
 ```bash
-perp strategy list-strategies                         # list all 19 strategies
-perp strategy run <strategy> [symbol]                 # run any registered strategy
-perp strategy run funding-auto                        # multi-exchange funding arb
-perp strategy apex [symbol]                           # APEX orchestrator (Radar+Pulse+Guard)
-perp strategy reflect                                 # performance analysis (win rate, fees, PnL)
-perp strategy preset-list                             # list strategy presets
-perp strategy preset <name> [symbol]                  # run from preset
-perp strategy start <config.yaml>                     # start from YAML/JSON config
-perp strategy quick-grid <symbol>                     # quick grid bot
-perp strategy quick-dca <symbol> <side> <amount> <interval>
-perp strategy quick-arb                               # quick funding arb
+# 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:<venue> = hl, lt, lrh, aster, ondo)
+perp --json arb exec <SYM> spot:hl hl <USD>
+perp --json arb exec <SYM> spot:lt pac <USD>
+
+# Single trade
+perp --json -e <ex> trade buy  <SYM> <SIZE> --smart
+perp --json -e <ex> trade sell <SYM> <SIZE> --smart
+perp --json -e <ex> trade split <SYM> buy <USD> --max-slippage 0.5
+```
+
+HL spot uses U-tokens (`BTC→UBTC`, `ETH→UETH`, `SOL→USOL`) — auto-resolved.
 
-# Scripted plans (one-shot multi-step execution)
-perp strategy plan example                            # show plan format
-perp --json strategy plan validate <file>             # validate before run
-perp --json strategy plan execute <file> --dry-run    # dry-run plan
+### Step 6: Monitor
 
-# Background process supervisor (tmux)
-perp background list                                  # list running jobs
-perp background stop <id>                             # stop a job
-perp background logs <id> -f                          # follow logs
+```bash
+perp --json arb status                              # open arb positions, PnL, funding earned
+perp --json portfolio                               # cross-exchange equity + risk
+perp --json risk status                             # canTrade, level, violations
+perp --json risk liquidation-distance               # % from liq for ALL positions
 ```
 
-**Strategies:** grid, dca, funding-arb, funding-arb-v2, funding-auto, basis-arb, simple-mm, engine-mm, avellaneda-mm, regime-mm, grid-mm, liquidation-mm, momentum-breakout, mean-reversion, aggressive-taker, hedge-agent, rfq-agent, claude-agent, apex
+If `risk status.canTrade === false`, do NOT open new positions. If liquidation distance falls below the user's `--min-liq-distance`, recommend reducing position size.
 
-**Flags:** `--dry-run` (simulate without executing), `--headless` (no TUI, log only)
+For continuous monitoring, run `bash scripts/arb-monitor.sh --json`.
 
-## Core Workflow: Single Trade
+### Step 7: Close
 
 ```bash
-perp --json -e <EX> trade buy <SYM> <SIZE>              # market buy (SIZE = token units)
-perp --json -e <EX> trade sell <SYM> <SIZE>             # market sell
-perp --json -e <EX> trade buy <SYM> <SIZE> --smart      # IOC limit at best ask
-perp --json -e <EX> trade split <SYM> buy <USD>         # orderbook-aware split
-perp --json -e <EX> trade limit <SYM> buy <PRICE> <SIZE>
-perp --json -e <EX> trade tpsl <SYM> buy --tp <P> --sl <P>
-perp --json -e <EX> trade close <SYM>
-perp --json -e <EX> trade flatten                       # close ALL + cancel ALL
-perp --json -e <EX> trade cancel <SYM>                  # cancel all orders for symbol
+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
+perp --json -e <ex> trade close-all                             # close all positions on this exchange
+perp --json -e <ex> trade flatten                               # close ALL + cancel ALL orders
 ```
 
-## Agent Tools
+### Funds workflow (deposit / withdraw / transfer / bridge / rebalance)
+
+All money movement lives under `perp funds`:
 
 ```bash
-perp --json -e <EX> trade check <SYM> <SIDE> <SIZE>  # pre-validate trade
-perp --json portfolio                              # balances + positions + risk level
-perp --json --fields totalEquity,positions portfolio  # filtered output
+# Exchange in/out
+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 [--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
+perp --json funds rebalance check
+perp --json funds rebalance plan
+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
 ```
 
-## Position Sizing & Safety
+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)
 
-- Single position < **80%** of that exchange's available balance
-- Leverage 1-3x for arb, max 5x
-- `arb exec` auto-matches both legs to the same size
-- ALWAYS follow `longExch`/`shortExch` from scan — NEVER reverse direction
-- NEVER enter if `netSpread <= 0` or `netSpread < estimated round-trip slippage`
-- Check `portfolio.risk.canTrade` — if `false`, do NOT trade
+```bash
+perp strategy list-strategies                                 # 20 registered
+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
+perp --json strategy plan execute <FILE> --dry-run            # dry-run scripted plan
+```
+
+**Strategies:** `grid`, `dca`, `simple-mm`, `engine-mm`, `avellaneda-mm`, `regime-mm`, `grid-mm`, `liquidation-mm`, `momentum-breakout`, `mean-reversion`, `aggressive-taker`, `funding-arb`, `funding-arb-v2`, `funding-auto`, `basis-arb`, `spot-perp-arb`, `hedge-agent`, `rfq-agent`, `claude-agent`, `apex`.
 
-## HIP-3 Support
+Background daemon (tmux):
 
 ```bash
-perp --json -e hl --dex km market list              # dex-specific markets
-perp --json market list --hip3                      # all HIP-3 markets
-perp --json account positions --hip3                # HIP-3 positions
-perp --json arb scan --hip3                         # HIP-3 arb opportunities
+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> [--timeout 90]   # graceful: SIGINT, job cancels its orders, waits, reports what is left on the venue
 ```
 
-## Error Handling
+`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.
 
-Response format: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "code": "...", "retryable": true/false } }`
+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.
 
-| Error | Action |
-|-------|--------|
-| `RATE_LIMITED` | wait 5s, retry (max 3). Lighter: space 3s+ apart |
-| `EXCHANGE_UNREACHABLE` | wait 10s, retry. 3x fail → skip exchange |
-| `INSUFFICIENT_BALANCE` | reduce size or bridge funds |
-| `SYMBOL_NOT_FOUND` | `market list` to verify symbol |
-| `SIZE_TOO_SMALL` | `market info <SYM>` for min size |
-| `DUPLICATE_ORDER` | already submitted — check positions |
-| Lighter `invalid signature` | `perp wallet agent approve lighter` to regenerate |
+### 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` 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.
+
+For deeper risk-management framework, read `references/strategies.md`.
 
 ## Examples
 
-**"Find arb opportunities"**
+### Example 1: "Find funding-rate arb opportunities"
+
 ```bash
+# 1. Discover
 perp --json arb scan --min 10 --top 10
-perp --json account balance
-# → show results, recommend best, ask confirmation
+# 2. Show top 3 to user; ask which to evaluate
+# 3. Check balances on the two exchanges
+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:
+perp --json arb exec BTC <longEx> <shortEx> 100 --smart
+perp --json arb status
 ```
 
-**"ETH spot-perp arb, $100"**
+### Example 2: "ETH spot+perp arb, $100"
+
 ```bash
 perp --json --dry-run arb exec ETH spot:hl hl 100
 # → show dry-run, ask confirmation
 perp --json arb exec ETH spot:hl hl 100
 perp --json arb status
+# Later, to close both legs:
+perp --json arb close ETH --spot-exch hl --perp-exch hl
 ```
 
-**"Long SOL 0.5 on HL"**
+### Example 3: "Long SOL 0.5 on Hyperliquid with 2x leverage"
+
 ```bash
-perp --json -e hl trade check SOL buy 0.5
+perp --json -e hl wallet manage margin SOL isolated   # use isolated margin for new trade
+perp --json -e hl trade leverage SOL 2 --isolated
+perp --json -e hl trade check SOL buy 0.5 --leverage 2
 perp --json --dry-run -e hl trade buy SOL 0.5 --smart
-# → ask confirmation
+# → show dry-run, ask confirmation
 perp --json -e hl trade buy SOL 0.5 --smart
+perp --json -e hl account positions
+```
+
+### Example 4: "Move 500 USDC from Pacifica to Hyperliquid"
+
+```bash
+perp --json funds withdraw pacifica 500
+perp --json funds bridge quote --from solana --to arbitrum --amount 500
+# → show fee, ETA, ask confirmation
+perp --json funds bridge send  --from solana --to arbitrum --amount 500
+perp --json funds bridge status <orderId>             # poll until completed
+perp --json funds deposit hyperliquid 500
+```
+
+`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
+# To stop:
+perp --json background stop <id>
+```
+
+## Troubleshooting
+
+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 |
+|---|---|---|
+| `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
+
+- **Forgetting `--json`** → output becomes unparseable human text. The very first thing to check when parsing fails.
+- **Using legacy command names** — `arb rates`/`arb prices`/`arb dex`/`arb spot-exec`/`arb spot-close` are removed. Use `arb scan --rates|--gaps|--hip3` and `arb exec spot:<exch>` / `arb close <SYM> --spot-exch <ex>`.
+- **Calling `trade check` without `--leverage`** → cost estimate doesn't match what the exchange applies.
+- **Retrying a non-idempotent trade** without checking `account positions` → opens a duplicate position.
+- **Bridging without quoting first** → user sees no fee/ETA and can't approve cleanly.
+- **Treating `bridge send` as instant** → always `funds bridge status <orderId>` before depositing on the destination.
+- **Manually adding `-PERP` suffix** → CLI auto-resolves; let it.
+
+For a full troubleshooting + non-interactive flow guide, read `references/agent-operations.md`.
+
+## Referrals (optional, ask once per setup)
+
+```bash
+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)
 ```
 
-## Referrals (Optional)
+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 settings referrals on    # enable (opt-in, no extra fees)
-perp --json settings referrals off   # disable anytime
+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 setting up wallets for the first time, 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 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
+{
+  "mcpServers": {
+    "perp-cli": {
+      "command": "npx",
+      "args": ["-y", "-p", "perp-cli", "perp-mcp"]
+    }
+  }
+}
+```
+
+[![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)