perp-cli 0.12.15 → 0.14.0

package/skills/perp-cli/references/commands.md

@@ -2,74 +2,183 @@
 
 All commands support `--json` for structured output. Always use `--json` when calling from an agent.
 
+## Global Flags
+
+`--json` (required for agents) | `-e <venue>` | `-n mainnet|testnet` | `--dry-run` (only commands whose `--help` says "supports --dry-run"; others refuse with `INVALID_PARAMS`) | `--fields <f1,f2>` | `--ndjson` | `-w, --wallet <name>` | `--ows <name>` (OWS wallet) | `--no-agent` (skip agent-key routing) | `--no-builder` | `--dex <name>` (HIP-3, Hyperliquid)
+
+Venues (`-e`, id | aliases): `pacifica|pac`, `hyperliquid|hl`, `lighter|lt`, `lighter-rh|lrh|rh`, `aster|ast`, `ondo|ondo-perps`, `arcus`, `qfex|qf`. Default = `settings.defaultExchange`, else `pacifica` — always pass `-e`.
+`-k <key>` is rejected (keys only via stdin / OWS vault). `--passphrase` is deprecated → `OWS_PASSPHRASE` env or stdin.
+
 ## Market Data (read-only, safe)
 ```bash
-perp --json market list                    # all markets with prices, funding, volume
-perp --json market prices                  # cross-exchange price comparison
-perp --json market mid <SYMBOL>            # mid price (fast)
-perp --json market info <SYMBOL>           # mark/index price, funding, volume, OI, max leverage
-perp --json market book <SYMBOL>           # orderbook (bids/asks)
-perp --json market trades <SYMBOL>         # recent trades
-perp --json market funding <SYMBOL>        # funding rate history
-perp --json market kline <SYM> <INTERVAL>  # OHLCV candles (1m,5m,15m,1h,4h,1d)
-perp --json market hip3                    # list HIP-3 deployed perp dexes (Hyperliquid only)
+perp --json -e <EX> market list                # all markets with prices, funding, volume
+perp --json market prices                      # cross-exchange price comparison
+perp --json -e <EX> market mid <SYMBOL>        # mid price (fast)
+perp --json -e <EX> market info <SYMBOL>       # mark/index price, funding, volume, OI, max leverage
+perp --json -e <EX> market book <SYMBOL>       # orderbook (bids/asks)
+perp --json -e <EX> market trades <SYMBOL>     # recent trades
+perp --json -e <EX> market funding <SYMBOL>    # funding rate history
+perp --json -e <EX> market kline <SYM> <INT>   # OHLCV candles (1m,5m,15m,1h,4h,1d)
+perp --json market hip3                        # list HIP-3 deployed perp dexes (Hyperliquid)
 ```
 
 ## Account (read-only, safe)
 ```bash
-perp --json account balance                # perp balance + spot holdings + 24h funding (alias: account balance)
-perp --json account positions              # open positions
-perp --json account orders                 # open/pending orders
-perp --json account history                # order history
-perp --json account trades                 # trade fill history
-perp --json account funding-history        # funding payments
-perp --json account pnl                    # profit & loss
-perp --json account margin <SYMBOL>        # position margin info
-perp --json portfolio                      # cross-exchange unified view
+perp --json portfolio -e <VENUE_ID>            # perp balance + spot holdings + 24h funding; full venue id only (hl → INVALID_PARAMS)
+perp --json -e <EX> account positions          # open positions
+perp --json -e <EX> account orders             # open/pending orders
+perp --json -e <EX> account history            # order history
+perp --json -e <EX> account trades             # trade fill history
+perp --json -e <EX> account funding-history    # funding payments
+perp --json -e <EX> account settings           # per-market leverage & margin mode
+perp --json -e <EX> account margin <SYMBOL>    # position margin info
+perp --json -e <EX> account pnl                # realized + unrealized + funding
+perp --json -e <EX> account twap-orders        # active TWAP orders
+perp --json portfolio                          # cross-exchange unified view
+perp --json portfolio --arb                    # full dashboard with arb top 5
 ```
 
 ## Trading (requires user confirmation)
 ```bash
 # Market orders
-perp --json trade market <SYMBOL> <buy|sell> <SIZE>
-perp --json trade buy <SYMBOL> <SIZE>       # shorthand market buy
-perp --json trade sell <SYMBOL> <SIZE>      # shorthand market sell
+perp --json -e <EX> trade market <SYMBOL> <buy|sell> <SIZE>
+perp --json -e <EX> trade buy <SYMBOL> <SIZE>           # shorthand market buy
+perp --json -e <EX> trade sell <SYMBOL> <SIZE>          # shorthand market sell
+perp --json -e <EX> trade buy <SYM> <SIZE> --smart      # IOC limit at best ask + 1 tick — pacifica/hyperliquid/lighter/aster only; not with --tp/--sl or a client id
+perp --json -e <EX> trade buy <SYM> <SIZE> --client-id <id>   # reused id → ok:true, data.duplicate:true (local ~/.perp/client-ids.jsonl; nothing sent)
+#   id formats: pacifica full UUID; hyperliquid 0x+32 hex; lighter(-rh) integer; qfex refuses --client-id (use --auto-id)
+# Opening orders: --force bypasses the local risk limits (user consent only; never quarantine)
 
-# Limit orders
-perp --json trade limit <SYMBOL> <buy|sell> <PRICE> <SIZE>
+# Split execution (orderbook-aware, for large orders)
+perp --json -e <EX> trade split <SYMBOL> <buy|sell> <USD>
+perp --json -e <EX> trade split <SYM> buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000 --min-slice 200
+perp --json -e <EX> trade market <SYM> buy <SIZE> --split   # split via flag
 
-# Stop orders
-perp --json trade stop <SYMBOL> <SIDE> <STOP_PRICE> <SIZE>
-perp --json trade tpsl <SYMBOL> <SIDE> --tp <PRICE> --sl <PRICE>
+# Limit / stop / TPSL
+perp --json -e <EX> trade limit <SYMBOL> <buy|sell> <PRICE> <SIZE> [--tif GTC|IOC|FOK|ALO]   # default GTC on every venue; off-grid price → INVALID_TICK (never rounded)
+perp --json -e <EX> trade stop <SYMBOL> <SIDE> <SIZE> <STOP_PRICE>   # reduce-only by default; --no-reduce-only to open (refused on ondo / qfex)
+perp --json -e <EX> trade tpsl <SYMBOL> <long|short> --tp <P> --sl <P>   # positionSide = the open position's side
+perp --json -e <EX> trade buy <SYMBOL> <SIZE> --tp <P> --sl <P>         # entry protected by TP/SL (verified fill)
 
 # Order management
-perp --json trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>
-perp --json trade cancel <SYMBOL> <ORDER_ID>
-perp --json trade cancel-all
-perp --json trade check <SYMBOL> <SIDE> <SIZE>    # pre-flight validation (no execution)
-perp --json trade check <SYM> <SIDE> <SIZE> --leverage 3  # check with specific leverage
+perp --json -e <EX> trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>
+perp --json -e <EX> trade cancel <SYMBOL_OR_ORDER_ID> [orderId]
+perp --json -e <EX> trade cancel-all
+perp --json -e <EX> trade cancel-stop <SYMBOL> <STOP_ORDER_ID>   # pacifica / qfex only; other venues: trade cancel
+perp --json -e <EX> trade cancel-twap <SYMBOL> <TWAP_ORDER_ID>
+perp --json -e <EX> trade status <ORDER_ID|c:<CLIENT_ID>> [--symbol <SYM>]
+#   --symbol required on ondo / arcus / qfex, and for c:<id> on lighter / lighter-rh / aster
+perp --json -e <EX> trade fills [SYMBOL]                # recent fills
+
+# Pre-flight validation
+perp --json -e <EX> trade check <SYMBOL> <SIDE> <SIZE>
+perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage 3
 # NOTE: trade check does NOT read exchange-set leverage. Always pass --leverage explicitly.
 
 # Position management
-perp --json trade close <SYMBOL>            # close single position
-perp --json trade close-all                 # close all positions
-perp --json trade flatten                   # cancel all orders + close all positions
-perp --json trade reduce <SYMBOL> <PCT>     # reduce position by percentage
-perp --json trade leverage <SYMBOL> <N>     # set leverage
+perp --json -e <EX> trade close <SYMBOL>                # close single position
+perp --json -e <EX> trade close-all                     # close all positions
+perp --json -e <EX> trade flatten                       # cancel all orders + close all positions
+perp --json -e <EX> trade reduce <SYMBOL> <PCT>         # reduce by percentage
+perp --json -e <EX> trade leverage <SYMBOL> <N> [--isolated]
 
 # Advanced orders
-perp --json trade scale-tp <SYMBOL> --levels '<PRICE1>:<PCT>,<PRICE2>:<PCT>'
-perp --json trade scale-in <SYMBOL> <SIDE> --levels '<PRICE1>:<SIZE>,<PRICE2>:<SIZE>'
-perp --json trade pnl-track                 # real-time PnL tracker
+perp --json -e <EX> trade scale-tp <SYMBOL> --levels '<P1>:<PCT>,<P2>:<PCT>'
+perp --json -e <EX> trade scale-in <SYMBOL> <SIDE> --levels '<P1>:<PCT>,<P2>:<PCT>' (--size-usd <USD> | --size <BASE>)   # percents sum to 100
+perp --json -e <EX> trade pnl-track                     # real-time PnL tracker
+perp --json -e <EX> trade twap <SYMBOL> <SIDE> <SIZE> <DURATION>   # Pacifica: seconds (native), HL: minutes (native, min $100); others client-side: --background [--slices <n>]
+
+# Spot helpers (any venue with spot)
+perp --json -e <EX> trade spot-buy <SYMBOL> <SIZE>
+perp --json -e <EX> trade spot-sell <SYMBOL> <SIZE>
+perp --json -e <EX> trade spot-limit <SYMBOL> <SIDE> <PRICE> <SIZE> [--tif <tif>]
+perp --json -e <EX> trade spot-cancel <SYMBOL> <ORDER_ID>
+perp --json -e <EX> trade spot-orders [SYMBOL]
+perp --json -e <EX> trade spot-transfer <to-spot|to-perp> <AMOUNT>
+perp --json -e <EX> trade spot-balance
 
-# Split execution (orderbook-aware)
-perp --json trade split <SYMBOL> <buy|sell> <USD>   # split large order into depth-based slices
-perp --json trade split <SYM> buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000 --min-slice 200
-perp --json trade market <SYM> buy <SIZE> --split   # split via market command flag
-perp --json trade market <SYM> buy <SIZE> --split --max-slippage 0.5
+# Multi-leg execution (legs exchange:symbol:side:size; failed legs rolled back; unconfirmed leg → quarantined; no --dry-run)
+perp --json trade multi <legs...>
 ```
 
-## Funds (Deposit, Withdraw, Transfer, Bridge, Rebalance)
+## Outcome Markets (Hyperliquid HIP-4)
+
+Fully-collateralized binary/range contracts on Hyperliquid. Each outcome's quote token comes from `outcomeMeta.quoteToken` (`outcome list` shows it; USDC on every listed outcome as of 2026-10-12), held on Hyperliquid spot. No leverage / no liquidation. Minimum order value 10 quote tokens (price × shares ≥ 10). Sizes are whole shares.
+
+```bash
+# List active outcome markets — parses the description string into
+# class / underlying / expiry / targetPrice / period and lists each side
+# with mid + assetId.
+perp --json outcome list
+
+# COMBINED VIEW — all sides' books in parallel + underlying mark price
+# (HL perp mid for `description.underlying`) + gap vs targetPrice + ms
+# until expiry + per-side implied probability. For a binary market the
+# symmetric structure means Yes BID + No ASK ≈ 1.0; this is the
+# preferred entry point for agents that need a single snapshot.
+perp --json outcome view <outcome> [--depth N=10]
+
+# Orderbook for ONE side only (use `view` if you want both at once).
+# <side> accepts: 0/1, Yes/No, or #<enc> / +<enc> (the encoded form
+# must match the outcome arg — mismatch throws INVALID_PARAMS).
+perp --json outcome book <outcome> <side> [--depth N=10]
+
+# Holdings + open orders.
+perp --json outcome positions
+perp --json outcome orders
+
+# Place orders. ALWAYS dry-run first. [usd] = notional in the quote token, or --size <shares>; sell also --all.
+perp --json --dry-run outcome buy  <outcome> <side> <usd>
+perp --json --dry-run outcome sell <outcome> <side> --all
+
+# Live execution. --limit makes it GTC; without --limit it's IoC at best ask +5% (cap 1) / best bid -5%.
+perp --json outcome buy  <outcome> <side> [<usd> | --size <shares>] [--limit <px>] [--tif gtc|ioc|alo]
+perp --json outcome sell <outcome> <side> [<usd> | --size <shares> | --all] [--limit <px>] [--tif gtc|ioc|alo]
+
+# Cancel a resting order.
+perp --json outcome cancel <outcome> <side> <oid>
+```
+
+### Identifier model
+
+Same outcome side can be referenced 5 ways — the CLI normalises:
+
+| Form | Example (BTC daily Yes) |
+|---|---|
+| `<outcome>, <side>` integer | `1, 0` |
+| `<outcome>, <side>` name | `1, yes` |
+| `#<enc>` (l2Book / candle / allMids coin) | `#10` |
+| `+<enc>` (spotClearinghouseState balance coin) | `+10` |
+| asset id (HL `/exchange` payload) | `100000010` |
+
+Encoding formula: `enc = 10 * outcome + side`; asset id = `100,000,000 + enc`.
+
+### Foot-guns enforced (Rule #2)
+
+- **Min notional:** `price * size < 10` quote tokens → `INVALID_PARAMS`. Enforced in dry-run too. A trade leaving a remainder worth < 10 warns (it cannot be sold alone — use `sell --all`); selling more than held → `SIZE_TOO_LARGE`.
+- **Encoded-side mismatch:** `outcome buy 2 #10` (where `#10` decodes to outcome=1) → `INVALID_PARAMS`, never silently routes to outcome 2.
+- **Insufficient quote token:** pre-checked before order send → `INSUFFICIENT_BALANCE` (hold the outcome's quote token on Hyperliquid spot).
+- **Venue rejection:** HL returns HTTP 200 with `statuses[0].error` even when an order is rejected; the CLI raises `ORDER_REJECTED` (or `INSUFFICIENT_BALANCE`) so a "placed" message never masks a failure.
+
+### Agent workflow recommendation
+
+```
+1. perp --json outcome list                       # discover markets, parse description
+2. perp --json outcome view <outcome>             # full snapshot: both books +
+                                                  # underlying mark + gap vs target +
+                                                  # implied probabilities + time to expiry
+3. perp --json --dry-run outcome buy <outcome> <side> <usd>
+                                                  # validate notional, get user approval
+4. perp --json outcome buy <outcome> <side> <usd> [--limit <px>] [--tif ...]
+                                                  # execute (only after explicit user OK)
+5. perp --json outcome positions                  # confirm fill / monitor
+```
+
+`outcome view` replaces the old multi-call pattern (separate `book` + `market mid` lookups). One round-trip returns everything an agent needs to decide direction.
+
+Settlement at `expiryMs` is venue-side: winning side → 1 quote token per share, losing → 0. Decide before expiry whether to self-close or let the venue settle.
+
+## Funds (deposit, withdraw, transfer, bridge, rebalance)
 
 All fund movement lives under `perp funds`.
 
@@ -80,126 +189,360 @@ perp --json funds deposit hyperliquid <AMOUNT>
 perp --json funds deposit lighter ethereum <AMOUNT>         # L1 direct (min 1 USDC)
 perp --json funds deposit lighter cctp arbitrum <AMOUNT>    # CCTP (min 5 USDC)
 perp --json funds deposit lighter info                      # all Lighter deposit routes
-perp --json funds withdraw pacifica <AMOUNT>
-perp --json funds withdraw hyperliquid <AMOUNT>
-perp --json funds withdraw lighter <AMOUNT>
-perp --json funds transfer <AMOUNT> <ADDRESS>               # HL internal transfer (instant)
+perp --json funds withdraw pacifica <AMOUNT>              # to your own Solana wallet
+perp --json funds withdraw hyperliquid <AMOUNT> [--chain arbitrum|ethereum|base] [--to <allowlisted addr>]
+#   CCTP (native USDC) to your wallet (default arbitrum; 0.2 USDC forwarding fee on Arbitrum).
+#   --to another address only if it is on settings withdraw.hyperliquid (else POLICY_DENIED).
+perp --json funds withdraw lighter <AMOUNT>                 # -e lighter: USDC → Ethereum; -e lighter-rh: USDG → Robinhood Chain
+perp --json funds deposit lighter-rh <AMOUNT>               # USDG on Robinhood Chain (min 1, mainnet only)
+perp --json funds withdraw ondo <AMOUNT> --to <ADDRESS>     # USDC → Ethereum (address-book destination)
+perp --json funds withdraw arcus <AMOUNT>                   # USDG → the account owner (min 1)
+perp --json funds deposit qfex                              # prints the USDC / Arbitrum One deposit address (sends nothing)
+perp --json --dry-run funds withdraw qfex <AMOUNT> --to <0x>  # plan + local gate verdict (settings withdraw.qfex; user-only, terminal)
+perp --json -e qfex funds transfer <AMOUNT> primary --from <account-uuid>   # between your QFEX accounts
+perp --json funds deposit aster <AMOUNT> [--chain bsc|arbitrum] [--asset USDT|USDC]   # vault approve + deposit (mainnet; default BNB Chain USDT)
+perp --json funds withdraw aster <AMOUNT> [--chain bsc|arbitrum] [--asset USDT|USDC]   # → the account's own address (default USDT; mainnet; agent approved with --can-withdraw --ip-whitelist)
+perp --json funds deposit ondo <AMOUNT> [--chain arbitrum|ethereum] [--probe <AMT>]   # USDC transfer to the account's funding address (mainnet)
+perp --json funds address-book add ondo <MASTER_ADDRESS>    # SIWE challenge → Ondo withdrawal address book (own address only)
+perp --json funds transfer <AMOUNT> <ADDRESS>               # HL internal transfer (instant); destination must be on settings withdraw.hyperliquid
+# settings withdraw.<venue> (allowlist + limits) is set ONLY by the user in an interactive terminal
+# (--json / piped → POLICY_DENIED). Agents never set or change it.
 perp --json funds info                                      # combined routes & limits
 ```
 
 ### Cross-chain bridge (multi-provider router: cctp / relay / debridge — auto-cheapest)
 ```bash
-perp --json funds bridge chains                   # supported chains
+perp --json funds bridge chains                             # supported chains
 perp --json funds bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT>
-perp --json funds bridge send --from <CHAIN> --to <CHAIN> --amount <AMT>           # auto-cheapest
-perp --json funds bridge send --from <CHAIN> --to <CHAIN> --amount <AMT> --provider cctp
-perp --json funds bridge exchange --from <EX> --to <EX> --amount <AMT>             # between exchanges
+perp --json funds bridge send --from <CHAIN> --to <CHAIN> --amount <AMT>
+perp --json funds bridge send --from <CHAIN> --to <CHAIN> --amount <AMT> --provider cctp [--fast]
+#   exactly --amount leaves the wallet; deBridge nativeFee (ETH/SOL) is shown separately;
+#   Solana-origin deBridge → NO_BRIDGE_ROUTE (use --provider cctp)
+# Relay swaps (chains: robinhood, arbitrum, bsc, base, solana as destination; EVM origin; OWS master signs; recipient = your own address)
+perp --json --dry-run funds bridge send --from robinhood --to arbitrum --from-asset USDG --to-asset USDC --amount <AMT>   # verified quote only
+perp --json funds bridge send --from robinhood --to solana --from-asset USDG --to-asset SOL --amount <AMT> --min-out <SOL>  # stable → native needs --min-out
+perp --json funds bridge send --from arbitrum --to robinhood --from-asset ETH --to-asset ETH --amount <ETH>                # native gas to Robinhood Chain
+perp --json funds bridge exchange --from <EX> --to <EX> --amount <AMT>   # pacifica|hyperliquid|lighter
+#   wallet → wallet: bridges the master's OWN USDC between the venues' chains (pacifica → solana,
+#   lighter → arbitrum); no venue withdraw/deposit. hyperliquid: --from spends HyperCore spot USDC,
+#   --to credits HyperCore perps. HyperCore → Solana → NO_BRIDGE_ROUTE.
 perp --json funds bridge status <ORDER_ID>
 ```
 
-### Inter-exchange rebalance (orchestrated withdraw → bridge → deposit)
+### Inter-exchange rebalance (withdraw → bridge; deposit is manual)
 ```bash
 perp --json funds rebalance check                            # balances across exchanges
 perp --json funds rebalance plan                             # compute optimal moves
-perp --json funds rebalance execute --auto-bridge            # withdraw → bridge → deposit
+perp --json --dry-run funds rebalance execute --auto-bridge  # status "simulated" (moves[].status "dry_run") or "balanced"
+perp --json funds rebalance execute --auto-bridge            # withdraw → bridge only (NO deposit)
 perp --json funds rebalance execute --withdraw-only          # only withdraw, manual rest
 ```
+`ok:true` even if a move failed — check every `moves[].status`: `withdrawn` | `bridged` | `same_chain` | `needs_bridge` | `withdraw_failed` | `bridge_failed`. Then deposit by hand after arrival (`funds deposit <venue> <amt>`).
 
 ## Arbitrage
+
+All scan modes are routed through `arb scan`. Legacy aliases (`arb rates`, `arb prices`, `arb dex`, `arb spot-exec`, `arb spot-close`) are removed.
+
 ```bash
-# Perp-Perp arb
-perp --json arb scan --min <BPS>            # find opportunities (>N bps spread) — PRIMARY command
-perp --json arb exec <SYM> <longEx> <shortEx> <$>  # execute perp-perp arb
-perp --json arb close <SYM>                 # close perp-perp arb
-perp --json arb status                      # monitor open arb positions
-perp --json arb funding-earned              # actual funding payments
+# Scan (read-only, safe)
+perp --json arb scan                                        # default --mode all (perp-perp + spot-perp)
+perp --json arb scan --mode perp-perp --min 10              # perp-only with min annual %
+perp --json arb scan --mode spot-perp --min 10              # spot+perp only
+perp --json arb scan --rates                                # funding rates across exchanges
+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>                     # compare a symbol across exchanges
+perp --json arb scan --positions                            # position funding impact
+perp --json arb scan --live --interval 60                   # continuous monitoring
+perp --json arb scan --top 10 --hold-days 7 --bridge-cost 0 --size 100  # cost-aware filtering
+perp --json arb scan --rates --include-unverified           # also show QFEX (unverified funding; display only, never ranked)
+# netSpread / grossSpread = annualized % (netSpread = gross minus round-trip costs amortized over --hold-days)
+# spot-perp rows: netSpreadPct / grossSpreadPct, spotExchanges[], perpExchange, direction
+
+# Execute (perp-perp or spot+perp via spot:<venue>; spot venues: hl, lt, lrh, aster, ondo)
+# Sequential: long first, then the short sized to the verified long fill; reconcile always on;
+# an unconfirmed leg quarantines the symbol. Supports --dry-run.
+perp --json arb exec <SYM> <longEx> <shortEx> <USD>         # perp-perp dual-leg entry
+perp --json arb exec <SYM> spot:hl hl <USD>                 # spot+perp via HL spot
+perp --json arb exec <SYM> spot:lt pac <USD>                # spot+perp via LT spot
+perp --json arb exec <SYM> <longEx> <shortEx> <USD> \
+   --leverage 2 --isolated --smart --max-slippage 0.5
 
-# Spot+Perp arb (spot funding = 0, spread = |perp funding|)
-perp --json arb scan --mode spot-perp       # scan spot+perp opportunities
-perp --json arb scan --mode all             # both perp-perp + spot-perp
-perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$>  # execute spot+perp arb
-perp --json arb spot-close <SYM> --spot-exch <hl|lt>   # close spot+perp arb
-# spotEx: hl (Hyperliquid) or lt (Lighter). perpEx: hl, lt, pac.
-# HL spot uses U-tokens: BTC→UBTC, ETH→UETH, SOL→USOL (auto-resolved)
+# Close
+perp --json arb close <SYM>                                  # close perp-perp arb
+perp --json arb close <SYM> --pair <longEx>:<shortEx>       # disambiguate by pair
+perp --json arb close <SYM> --spot-exch hl --perp-exch hl   # close spot+perp legs
+perp --json arb close <SYM> --smart                         # IOC limits at best price
+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 (no order sent)
 
-# Other arb tools
-perp --json arb rates                       # funding rates across all DEXs (detailed)
-perp --json arb prices                      # cross-exchange price gaps
-perp --json arb dex                         # HIP-3 cross-dex arb (Hyperliquid)
-# Deprecated: 'gap show' → use 'arb prices'; 'funding rates/spread' → use 'arb rates/scan'
+# Status / history / config / rebalance
+perp --json arb status                                      # open arb positions + PnL + funding; check unconfirmedPairs, staleStateEntries
+perp --json arb status --period 7 --symbol BTC              # filter funding lookback / symbol
+perp --json arb history                                     # alias: arb log
+perp --json arb history --period 30                         # past arb trade performance
+perp --json arb config                                      # show arb defaults
+perp --json arb rebalance --check                           # cross-exchange balance distribution (read-only)
+perp --json arb rebalance --target 50:50 --amount 1000      # plan only; execute with funds rebalance execute
+
+# Auto-execute daemon
+perp --json arb auto --min-spread 30 --close-spread 5 --size 100 --max-positions 5
+perp --json arb auto --background                           # tmux session
+perp --json arb auto --hip3 --min-oi 50000 --min-grade C    # HIP-3 mode
+perp --json --dry-run arb auto                              # simulate (--background inherits it)
 ```
 
 ## Wallet Management
 ```bash
-perp --json wallet set hl <KEY>             # set Hyperliquid key
-perp --json wallet set pac <KEY>            # set Pacifica key
-perp --json wallet set lt <KEY>             # set Lighter key
-perp --json wallet set hl <KEY> --default   # set key + make default exchange
-perp --json wallet show                     # show configured wallets (public addresses)
-perp --json wallet generate evm             # generate new EVM wallet
-perp --json wallet generate solana          # generate new Solana wallet
-perp --json wallet balance                  # on-chain balance
+perp --json wallet generate evm                # generate EVM wallet
+perp --json wallet generate solana             # generate Solana wallet
+printf '%s' "$KEY" | OWS_PASSPHRASE=<pp> perp --json wallet import --name <n> [--chain evm|solana|dual] [--mnemonic]   # import a key (stdin / hidden prompt; argv key, --evm/--solana <key>, --legacy rejected)
+printf '%s' "$KEY" | OWS_PASSPHRASE=<pp> perp --json wallet set hl   # import key (stdin / hidden prompt; argv key rejected) into OWS vault → active wallet
+perp --json wallet set pac --name pac          # Solana key, hidden prompt (TTY)
+perp --json wallet set hl --default            # also make hyperliquid the default exchange
+perp --json wallet show                        # public addresses for active wallet
+perp --json wallet list                        # all named wallets
+perp --json wallet use <name>                  # set active wallet
+perp --json wallet rename <old> <new>
+perp --json wallet remove <name>
+perp --json wallet balance                     # on-chain USDC balances
+perp --json wallet solana <address>            # check arbitrary Solana address
+perp --json wallet arbitrum <address>          # check arbitrary Arbitrum address
+perp --json wallet migrate                     # migrate legacy ~/.perp/.env config
+perp --json wallet rotate --from <name> --to <name> [--chain evm]   # MUTATING: new wallet + transfers assets; no --dry-run — only on explicit user request
+perp --json wallet backup                      # encrypted backup
+perp --json wallet restore <file>              # restore from backup
+perp --json wallet deposit <walletName> [--for <ex>|-c <chain>]   # MoonPay multi-chain deposit (auto-converts to USDC)
+perp --json wallet setup --name <n> --max-tx-usd <usd> --max-daily-usd <usd> [--skip-key]
+                                               # one-click: wallet + policy + agent key.
+                                               # Passphrase prompt unless OWS_PASSPHRASE env is set.
+```
+
+### Agent wallet (DEX-side delegation)
+```bash
+# Register an agent (master-signed: user consent; passphrase via OWS_PASSPHRASE / stdin; no --dry-run).
+# Default expires-in is 90d — then AGENT_EXPIRED; pass --expires-in 1y / 180d / etc to extend.
+perp --json wallet agent approve <exchange> \
+  [--master <name>] \
+  [--agent-name <name>] \
+  [--expires-in 30d|90d|180d|1y|<ISO-8601>] \
+  [--can-perp|--no-perp] [--can-spot|--no-spot] [--can-withdraw|--no-withdraw] \
+  [--rotate] \
+  [--ip-whitelist <list>] \
+  [--account-index <0-9|255>]          # Arcus subaccount
+  [--api-key-index <n>]                # Lighter slot 4-254 (default: first slot free locally AND on-chain)
+  [--force]                            # Lighter: overwrite an --api-key-index slot that already holds an on-chain key
+
+# Import a key the USER created on the exchange WEBSITE (master wallet not needed here).
+# Key on stdin only (one line; ondo: key id + secret; qfex: public key + secret) — an argv key is rejected (INVALID_PARAMS).
+# Verified against the venue before storing (refused → nothing stored); pacifica → "unverified".
+printf '%s' "$AGENT_KEY" | perp --json wallet agent import <exchange> \
+  [--master-address <addr>]            # aster / pacifica / arcus: required; hyperliquid / lighter: cross-check
+  [--account-index <n>] [--api-key-index <n>]   # lighter / lighter-rh: required (arcus: optional cross-check)
+  [--account-id <uuid>]                # qfex: the account the key trades (default primary; required when piped — it confirms the binding)
+  [--agent-name <name>] [--expires-in <dur>] [--replace]
+# → data: { source: "imported", masterAddress, agentAddress|publicKey, accountIndex, apiKeyIndex,
+#           expiresAt|null, storage, verification: { status: "verified"|"unverified", method } }
+
+perp --json wallet agent list [exchange]          # rows carry source: "approved" | "imported"
+perp --json wallet agent revoke <exchange> <agentName> [--local-only]
+#   imported key: refused unless --local-only (deletes local key + record; still authorized on the
+#   exchange — revoke it on the website). --local-only on an approved agent = --force.
+perp --json wallet agent rotate <exchange> [oldAgentName]
+#   imported key: refused — create a new key on the website, then import --agent-name <name> --replace
+# verify: --master (Aster/PAC; passphrase via OWS_PASSPHRASE) / --master-address (HL only) / --account-index (Lighter only).
+# Aster: NOT_IMPLEMENTED (no venue endpoint lists agents) — use wallet agent list aster.
+perp --json wallet agent verify [exchange] [agentName] \
+  [--master <name>] [--master-address <addr>] [--account-index <n>]
+```
+
+### Builder fees (`wallet builder`) — OFF by default
+```bash
+# Nothing is attached unless the user configures it explicitly (strict: format, cap, increment):
+perp --json settings set builder.<venue> <address|code>,<feeBps> --yes   # hyperliquid/aster: address; pacifica/ondo: code; --yes required non-interactively
+perp --json settings unset builder.<venue>
+perp --json wallet builder status [venue]           # support, config, venue approval, attaches?
+perp --json [--dry-run] wallet builder approve <venue> [--master <name>] [--yes]   # master-signed; y/N or --yes
+perp --json [--dry-run] wallet builder revoke <venue> [--master <name>] [--yes]    # pacifica / aster
+perp --json --no-builder -e <EX> trade market BTC buy 0.1   # never attach on this run
+# Caps: hyperliquid 10 bps (never HIP-3), pacifica 10 bps max (perp-cli cap; never spot), aster 10 bps (mainnet),
+# ondo 10 bps (no approval; also on position stops). lighter / lighter-rh / arcus → CAPABILITY_UNSUPPORTED.
+# Approval missing/unknown → order sent WITHOUT the fee; execution.notes says why. execution.builderFee records it.
+# No master on this computer → NO_SIGNER_AVAILABLE: approve on the venue website.
+```
+
+### Exchange settings (`wallet manage`)
+```bash
+perp --json -e <EX> wallet manage margin <SYMBOL> <cross|isolated>
+perp --json wallet manage account-mode [unified|standard|portfolio]   # Hyperliquid only; no arg = show current
+perp --json wallet manage sub create <name>            # not supported (CAPABILITY_UNSUPPORTED): the subaccount wallet must co-sign — use the web app
+perp --json wallet manage sub list
+perp --json wallet manage sub transfer <from> <to> <amount>   # <from> must be the signing account
+perp --json wallet manage lake create [--manager <address>] [--nickname <name>] [--initial-deposit <amount>]
+perp --json wallet manage lake deposit <lake> <amount>       # <lake> = vault address
+perp --json wallet manage lake withdraw <lake> <shares>      # shares to redeem, not USDC
+perp --json wallet manage builder overview                    # Pacifica builder-OWNER tools only (user approvals: wallet builder)
+perp --json wallet manage builder trades <code>
+perp --json wallet manage builder leaderboard <code>
+perp --json wallet manage builder update-fee <code> <feeRate>
+perp --json wallet manage referral claim <code>               # Pacifica
+perp --json -e hyperliquid wallet manage referral set [code]  # HL / Lighter (-e lighter): signs + sends one referral action; supports --dry-run
+perp --json wallet manage apikey create
+perp --json wallet manage apikey list
+perp --json wallet manage apikey revoke <key>
+```
+
+### OWS (Open Wallet Standard) API key + policy — optional, scoped agent tokens
+```bash
+perp --json wallet key create
+perp --json wallet key list
+perp --json wallet key revoke <id>
+perp --json wallet policy create
+perp --json wallet policy list
+perp --json wallet policy show <id>
+perp --json wallet policy delete <id>
 ```
 
 ## Risk & Analytics
 ```bash
-perp --json risk status                     # portfolio risk overview (level, violations, canTrade)
-perp --json risk liquidation-distance       # % distance from liquidation for ALL positions
-perp --json risk limits                     # view current risk limits
-perp --json risk limits --min-liq-distance 30 --max-leverage 5  # set risk limits
-perp --json risk check --notional 1000 --leverage 3  # pre-trade risk check
-perp --json history summary                 # trading performance
-perp --json history pnl                     # P&L breakdown by exchange
-perp --json history funding                 # funding payment aggregation
-perp --json history report                  # full performance report (summary + pnl + funding)
-perp --json history perf --period daily     # daily PnL breakdown (replaces daily-pnl)
-perp --json history perf --period weekly    # weekly PnL breakdown (replaces weekly-pnl)
-perp --json history perf --period summary   # performance summary stats
-perp --json history list                    # execution audit trail
-```
-
-## Automated Strategies (strategy — 19 algorithms + nested scripted plans)
-```bash
-perp --json strategy list-strategies                         # list all 19 strategies
-perp --json strategy run <STRATEGY> [SYMBOL]                 # run any registered strategy
-perp --json strategy run funding-auto                        # multi-exchange funding arb (no symbol needed)
-perp --json strategy apex [SYMBOL]                           # APEX autonomous orchestrator (Radar+Pulse+Guard)
-perp --json strategy reflect                                 # trading performance analysis (win rate, fees, PnL)
-perp --json strategy preset-list                             # list strategy presets
-perp --json strategy preset <NAME> [SYMBOL]                  # run from preset
-perp --json strategy twap <SYMBOL> <SIDE> <SIZE> <DURATION>  # TWAP execution
-perp --json strategy grid <SYMBOL> --range <PCT> --grids <N> --size <USD>
+perp --json risk status                        # portfolio risk overview (level, violations, canTrade)
+perp --json health                             # adapter health: ping venue REST endpoints (connectivity + latency)
+perp --json risk liquidation-distance          # % distance from liquidation for ALL positions
+perp --json risk limits                        # view current risk limits
+perp --json risk limits --min-liq-distance 30 --max-leverage 5  # set risk limits (also --max-position[-pct], --max-exposure[-pct], --max-positions, --daily-loss[-pct], --max-drawdown[-pct], --max-margin, --reset)
+# The order gate (trade market/buy/sell/limit/split/scale-in/twap/multi, stop --no-reduce-only) enforces
+# max position / total exposure / max positions; reduce-only exempt; --force bypasses (user consent only).
+perp --json risk check --notional 1000 --leverage 3             # pre-trade risk check
+```
+
+## History (execution log + analytics)
+```bash
+perp --json history list                       # execution audit trail
+perp --json history positions                  # position lifetime tracking
+perp --json history prune                      # purge old entries
+perp --json history summary                    # trading performance summary (replaces former 'stats')
+perp --json history pnl                        # P&L breakdown by exchange
+perp --json history funding                    # funding payment aggregation
+perp --json history report                     # full performance report (summary + pnl + funding)
+perp --json history compare                    # compare strategies / accounts
+perp --json history snapshot                   # equity snapshot
+perp --json history track                      # PnL tracking helper
+perp --json history perf --period daily        # daily PnL breakdown
+perp --json history perf --period weekly       # weekly PnL breakdown
+perp --json history perf --period summary      # performance summary stats
+```
+
+## Strategies (`perp strategy` — 20 algorithms + nested scripted plans)
+```bash
+perp --json strategy list-strategies                         # list all 20 strategies
+perp --json strategy run <STRATEGY> [SYMBOL] [--exchanges <list>]   # multi-venue strategies: --exchanges must include the -e venue
+perp --json --dry-run strategy run <STRATEGY> [SYMBOL]       # simulate (actions logged, never sent)
+perp --json strategy run funding-auto                        # multi-exchange funding arb
+perp --json strategy apex [SYMBOL]                           # APEX orchestrator
+perp --json strategy reflect                                 # performance analysis
+perp --json strategy preset-list
+perp --json strategy preset <NAME> [SYMBOL] [--size <n>]   # grid: total base; DCA: base per order; arb: $ per leg
+perp --json strategy start <CONFIG.yaml>                     # YAML/JSON config-driven
+perp --json strategy quick-grid <SYMBOL>
+perp --json strategy quick-dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL_SEC> [--orders <n>]   # 0 = unlimited
+perp --json strategy quick-arb
+perp --json strategy delta-neutral
+perp --json strategy twap <SYMBOL> <SIDE> <SIZE> <DURATION>
+perp --json strategy grid <SYMBOL> --upper <PRICE> --lower <PRICE> --grids <N> --size <BASE> [--close-on-stop]
+#   at stop: orders cancelled; the grid's inventory stays OPEN (warning) unless --close-on-stop
 perp --json strategy dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
-perp --json strategy trailing-stop <SYMBOL>                  # trailing stop with callback %
-perp --json strategy funding-arb                             # auto funding arb
-perp --json strategy quick-grid <SYMBOL>                     # quick grid bot
-perp --json strategy quick-arb                               # quick arb bot
+perp --json strategy trailing-stop <SYMBOL>
+perp --json strategy funding-arb [--auto-execute]           # monitor only unless --auto-execute
+
+# Quarantine (unknown / unhedged outcome): global per symbol, network-scoped; blocks opening orders,
+# arb exec / arb auto and bots (reduce-only passes). Clear only after the USER verified positions.
+perp --json strategy quarantine
+perp --json strategy quarantine-clear <SYMBOL> [--strategy <source>]
 
 # Scripted execution plans (one-shot multi-step)
-perp --json strategy plan example                            # show plan format
-perp --json strategy plan validate <FILE>                    # validate plan
-perp --json strategy plan execute <FILE> --dry-run           # dry-run plan
+perp --json strategy plan example
+perp --json strategy plan validate <FILE>
+perp --json --dry-run strategy plan execute <FILE>
+# No --dry-run (refused with INVALID_PARAMS): strategy start / preset / quick-* / grid / dca / twap / funding-arb / apex
+```
+
+### Available Strategies (20)
+- **Market Making:** `simple-mm`, `engine-mm`, `avellaneda-mm`, `regime-mm`, `grid-mm`, `liquidation-mm`
+- **Signal/Directional:** `momentum-breakout`, `mean-reversion`, `aggressive-taker`
+- **Arbitrage:** `funding-arb`, `funding-arb-v2`, `funding-auto`, `basis-arb`, `spot-perp-arb`
+- **Infrastructure:** `hedge-agent`, `rfq-agent`, `claude-agent`
+- **Classic:** `grid`, `dca`, `apex`
+
+## Background Process Supervisor (tmux)
+```bash
+perp --json background list                   # list running jobs (default subcommand)
+perp --json background stop <ID> [--timeout <sec>]   # graceful: SIGINT (job cancels its orders, saves state), waits (default 90s), then kills; reports what is left on the venue
+perp --json background logs <ID>              # view logs (use -f to follow)
+perp --json background remove <ID>            # remove a job entry
+perp --json background clean                  # purge all stopped/done jobs
+```
 
-# Background process supervisor (tmux)
-perp --json background list                                  # list running jobs
-perp --json background stop <ID>                             # stop a job
-perp --json background logs <ID>                             # view job logs
-perp --json background remove <ID>                           # remove a job entry
-perp --json background clean                                 # remove all stopped/done jobs
+## Backtest
+```bash
+perp --json backtest funding-arb              # backtest funding arb on historical data
+perp --json backtest grid                     # backtest grid strategy
+```
+
+## Alerts (Telegram / Discord)
+```bash
+perp alerts setup                             # interactive setup wizard
+perp --json alerts test                       # send test message
+perp --json alerts add <SYMBOL> <PCT> [--exchange <venue>] [--below]   # annual funding % threshold (default: above)
+perp --json alerts add --all <PCT>            # alert for any symbol
+perp --json alerts list                       # list active rules
+perp --json alerts remove <SYMBOL|all>        # remove a rule
+perp alerts start [--background]              # run daemon (tmux for background)
+perp alerts stop                              # stop background daemon
 ```
 
-### Available Strategies
-Market Making: `simple-mm`, `engine-mm`, `avellaneda-mm`, `regime-mm`, `grid-mm`, `liquidation-mm`
-Signal/Directional: `momentum-breakout`, `mean-reversion`, `aggressive-taker`
-Arbitrage: `funding-arb`, `funding-auto`, `basis-arb`
-Infrastructure: `hedge-agent`, `rfq-agent`, `claude-agent`
-Classic: `grid`, `dca`, `twap`, `apex`
+## Settings
+```bash
+perp --json settings show                     # show current CLI settings
+perp --json settings set <key> <value>        # set a CLI default
+#   keys: default-exchange, defaultSlippageBps, slippageBps.<venue>, referralCodes.{hyperliquid,lighter},
+#         builder.<venue> "<address|code>,<feeBps>" (off unless set), bridge.debridgeAffiliate.{referralCode,fee}
+perp --json settings unset <key>              # slippageBps.<venue> | defaultSlippageBps | builder.<venue> | withdraw.<venue> | bridge.debridgeAffiliate
+# withdraw.<venue> (withdraw / HL transfer allowlist + limits): USER ONLY, interactive terminal; agents never set it (POLICY_DENIED)
+perp --json settings fees show                # cached exchange fee table
+perp --json settings fees sync                # refresh fee cache
+perp --json settings env show                 # show ~/.perp/.env values
+perp --json settings env set <name> <value>   # non-secret values only (keys / *_PRIVATE_KEY / secrets → INVALID_PARAMS; use wallet set)
+perp --json settings env remove <name>
+perp --json settings env path                 # config file path
+```
 
-## Agent Wallet Management
+## Init / Setup
 ```bash
-perp wallet agent approve <exchange> [--master <name>]   # Register an agent wallet
-perp wallet agent list [exchange]                        # List registered agents
-perp wallet agent revoke <exchange> <agentName>          # Revoke an agent
-perp wallet agent rotate <exchange> [agentName]          # Revoke + re-approve same name
-perp wallet agent verify [exchange] [agentName]          # Verify via DEX query API
+# Interactive default — DO NOT use from agent without flags (will hang on prompts).
+perp setup                                    # alias: perp init
+perp init
+
+# Agent-safe non-interactive variant (writes settings; signs nothing by default):
+OWS_PASSPHRASE=<pp> perp --json [-n testnet] setup --non-interactive \
+  (--wallet <existing-ows-wallet> | --wallet-name <new-name>) \
+  [--venues <list>] [--default-venue <venue>] \
+  [--slippage-bps <n>] [--slippage <venue>=<bps> ...]
+# Agent registration (signs with the master wallet — get user consent first):
+#   --approve-agents --yes [--aster-can-spot] [--lighter-api-key-index <n>]
+#   [--lighter-rh-api-key-index <n>] [--arcus-account-index <0-9|255>]
+#   [--ondo-secret-stdin]   # Ondo key id + secret as 2 stdin lines; passphrase then via OWS_PASSPHRASE
+# Keys created on the exchange WEBSITES (no master wallet needed when every venue is imported —
+# then omit --wallet / --wallet-name; owsActiveWallet is left unchanged):
+#   --import-agents <venues> --yes   # subset of --venues; keys on stdin, ONE LINE PER VENUE IN THIS ORDER
+#                                    # (ondo: 2 lines — key id, then secret; qfex: 2 lines — public key, then secret)
+#   [--master-address <venue>=<addr> ...]   # required for aster, pacifica, arcus
+#   [--allow-unverified pacifica]           # required for pacifica (no read-only check exists)
+#   [--qfex-account-id <uuid>]              # required for qfex (confirms the bound account)
+#   [--lighter-account-index <n>] [--lighter-api-key-index <n>]
+#   [--lighter-rh-account-index <n>] [--lighter-rh-api-key-index <n>] [--arcus-account-index <n>]
+#   agents[] entries: { venue, status: "imported", agentName, verification }
 ```
+
+For per-exchange key registration without the wizard, use `printf '%s' "$KEY" | OWS_PASSPHRASE=<pp> perp wallet set <ex>` — also agent-safe (key on stdin, never argv).