perp-cli 0.14.3 → 0.16.0

package/README.md

@@ -1,229 +1,155 @@
+**English** | [한국어](README.ko.md) | [中文](README.zh.md) | [日本語](README.ja.md)
+
 # perp-cli
 
 [![npm version](https://img.shields.io/npm/v/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)
 [![npm downloads](https://img.shields.io/npm/dw/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)
 [![license](https://img.shields.io/npm/l/perp-cli.svg)](https://github.com/hypurrquant/perp-cli/blob/main/LICENSE)
 
-Multi-DEX perpetual futures CLI — **Pacifica** (Solana), **Hyperliquid** (HyperEVM), **Lighter** (Ethereum), **Aster** (BNB Chain), **Lighter RH** (Robinhood chain), **Ondo Perps** (off-chain), **Arcus** (Robinhood chain), **QFEX** (off-chain, TradFi perps).
+One CLI for perpetual futures across many DEXs — trade, compare funding, move funds and run bots from the terminal, or hand it to an AI agent (JSON output, MCP server, agent skill).
+
+- **Trade on 8 venues:** Hyperliquid (incl. HIP-3 dexes), Pacifica, Lighter, Lighter RH, Aster, Ondo Perps, Arcus, QFEX (bridge and perp-perp arb cover the original four: Pacifica, Hyperliquid, Lighter, Aster)
+- **Market data only:** RISEx, GRVT, Extended, Variational, TxFlow (unofficial API) — plus Derive options data
+
+## Install
 
 ```bash
-npm install -g perp-cli       # global install
-perp --json portfolio
+npm install -g perp-cli
+perp --version
 
-# Or without global install (restricted environments)
+# Or without a global install
 npx -y perp-cli --json portfolio
 ```
 
-## Features
+The package ships three executables: `perp` (the CLI), `perp-mcp` (the [MCP server](docs/mcp.md), stdio) and `perp-guardrail` (the [signing guardrail](docs/guardrail.md)).
 
-- **8 Venues** — trade on Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus, QFEX (bridge / perp-perp arb cover the original four)
-- **Funding Rate Arb** — perp-perp + spot-perp scan & one-command dual-leg execution
-- **Portfolio** — single call returns balances, positions, risk level across all exchanges
-- **Funds** — deposit, withdraw, transfer, multi-provider bridge (cctp/relay/debridge), inter-exchange rebalance — all in one group
-- **Bots** — TWAP, grid, DCA, trailing-stop with background job management
-- **Agent-First Design** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection
-- **Safety** — pre-trade validation, response sanitization, client-id deduplication
+## Quick start
 
-## Setup
+**1. Look around — no keys needed.**
 
 ```bash
-# Import an exchange key into the encrypted OWS vault and make it the active wallet.
-# The key is read from a hidden prompt or stdin — never argv (shell history), never ~/.perp/.env.
-perp wallet set hl                   # Hyperliquid (EVM) — hidden prompt
-pbpaste | OWS_PASSPHRASE="$PP" perp wallet set pac --name pac   # Pacifica (Solana) — piped
-# The active wallet serves every venue; one EVM key covers HL / Lighter / Aster.
-# Lighter trading also needs: perp wallet agent approve lighter
-
-# Or the interactive setup wizard (all 7 venues): picks / creates / imports an OWS
-# vault wallet, network, venues, registers agent wallets (y/N confirmation before
-# any signature — never moves funds), explains + sets the slippage bound, and the
-# default venue. It never writes keys to ~/.perp/.env.
-perp setup
-
-# Scriptable (CI / agents) — writes settings only, signs nothing:
-perp --json setup --non-interactive --wallet <ows-wallet> --venues hyperliquid,aster \
-  --network testnet --default-venue hyperliquid --slippage-bps 50 --slippage aster=80
-# Add agent registration explicitly (Ondo key id + secret via stdin only):
-OWS_PASSPHRASE=<pp> perp --json setup --non-interactive --wallet <ows-wallet> \
-  --venues hyperliquid,arcus --approve-agents --yes --arcus-account-index 0
-
-# Verify
-perp wallet show
+perp -e hl market list                  # markets, prices, funding
+perp -e hl market book BTC              # order book
+perp arb scan --rates                   # funding rates across venues
 ```
 
-Same EVM key works for both Hyperliquid and Lighter.
-
-> **Lighter API Key Index:** Indexes 0–3 are reserved by Lighter's frontend (web/mobile). perp-cli defaults to index `4`. Override with `LIGHTER_API_KEY_INDEX` env var, or use `perp wallet agent approve lighter --api-key-index <n>` for managed agent slots. Valid range: 4–254.
-
-### Lighter RH, Ondo Perps, Arcus
-
-These venues have no `wallet set` private-key path — register an agent / API key instead:
+**2. Add a wallet.** The setup wizard creates or imports an encrypted [OWS](https://github.com/open-wallet-standard) vault wallet, picks venues and registers agent keys (it asks before every signature and never moves funds):
 
 ```bash
-perp wallet agent approve lighter-rh                  # Lighter RH L2 slot key (USDG collateral, Robinhood chain)
-printf '%s\n%s\n' "$KEY_ID" "$SECRET" | perp wallet agent approve ondo   # Ondo HMAC key id + secret, stdin only
-perp wallet agent approve arcus --master <ows-wallet> # Arcus Ed25519 API key (OWS wallet agent-arcus-<master>)
-perp wallet agent verify [lighter-rh|ondo|arcus]      # no venue = verify every configured venue
+perp setup
+perp wallet show
 ```
 
-### No master wallet on this computer — import a key created on the exchange website
+Keys are read from a hidden prompt or stdin — never from argv or `~/.perp/.env`. One EVM key covers Hyperliquid, Lighter and Aster. For other paths (one-line key import, scriptable setup, keys created on the exchange website) see [docs/setup.md](docs/setup.md).
 
-Create the agent / API key on the venue's website, then import it. The master wallet never has to be
-on this machine; it is identified only by its public address. The key is read from a hidden prompt or
-stdin (never argv) and **checked against the venue before anything is stored** — a refused check stores
-nothing; a venue that cannot be checked without the master is reported as `unverified`, never as verified.
+**3. Check your account and trade.** Add `-n testnet` to any command to use testnet.
 
 ```bash
-perp -n testnet wallet agent import hyperliquid                    # API wallet key; master read from HL (userRole)
-pbpaste | perp wallet agent import aster --master-address 0xYOU     # signer key; signed /fapi/v3/balance check (works on Aster testnet too)
-perp wallet agent import pacifica --master-address <SOL account>   # agent key; UNVERIFIED (Pacifica lists bindings only master-signed)
-perp wallet agent import lighter --account-index 123 --api-key-index 5   # slot key; auth token accepted for that slot
-perp wallet agent import arcus --master-address 0xOWNER            # Ed25519 key; public key listed ACTIVE for the owner
-printf '%s\n%s\n' "$KEY_ID" "$SECRET" | perp wallet agent import ondo
-printf '%s\n%s\n' "$PUBLIC_KEY" "$SECRET" | perp wallet agent import qfex --account-id <uuid>   # QFEX: import only (keys are created on the website, 2FA)
-perp wallet agent list                                              # SOURCE column: approved | imported
-
-# Setup without any master wallet: one stdin line per --import-agents venue, in order (ondo: 2 lines)
-printf '%s\n%s\n' "$HL_AGENT_KEY" "$LT_KEY" | perp --json setup --non-interactive \
-  --venues hyperliquid,lighter --import-agents hyperliquid,lighter --yes \
-  --lighter-account-index 123 --lighter-api-key-index 5
+perp --json portfolio                                 # balances + positions + risk on every venue
+perp --json --dry-run -e hl trade market BTC buy 0.001   # validate only, nothing is sent
+perp --json -e hl trade market BTC buy 0.001          # market order (bounded by the slippage setting)
+perp --json -e hl trade close BTC
 ```
 
-Trading works with the imported key. **Deposits, withdrawals, transfers, bridge, referral set and agent
-approvals need the master**: without it they fail with `NO_SIGNER_AVAILABLE` ("do it on the exchange
-website, or add the master with `perp wallet import`"). The CLI cannot revoke or rotate an imported key —
-revoke it on the website; `perp wallet agent revoke <venue> <name> --local-only` removes the local copy,
-and `wallet agent import <venue> --agent-name <name> --replace` swaps in a new website-created key.
-`perp setup` offers the same choice per venue: approve with this computer's master wallet, or import a
-website-created key (Step 1 can skip the master wallet).
+## AI Agent Skill
 
-Secrets are stored once (see `docs/SSOT_RULES.md` Rule #3): Lighter RH → `~/.perp/lighter-rh-agents/`, Ondo → `~/.perp/ondo-agents/<keyId>.json`, Arcus → OWS wallet `agent-arcus-<master>`; imported EVM / Solana / Ed25519 keys → OWS wallet `agent-{hl,aster,pac,arcus}-import-<name>` (empty passphrase, like approved agent wallets), imported Lighter keys → the network-tagged Lighter keystore. A missing wallet/key now fails with `KEY_NOT_FOUND` / `NO_SIGNER_AVAILABLE` instead of silently falling back to read-only.
+Drop-in skill for Claude Code, Cursor, Codex, Gemini CLI, and other agent CLIs. Bundles a non-interactive command guide, ops playbook, strategy framework, and reusable shell scripts (preflight, arb monitor, validation) so your agent stops at the right confirmation points and never wedges on interactive wizards.
 
-## Venues
+### Install
 
-| Venue | `-e` id (aliases) | Trading | Notes |
-|-------|-------------------|---------|-------|
-| Pacifica | `pacifica` (`pac`) | yes | Solana |
-| Hyperliquid | `hyperliquid` (`hl`) | yes | HyperEVM; HIP-3 dexes via `--dex` |
-| Lighter | `lighter` (`lt`) | yes | Ethereum L2 |
-| Aster | `aster` (`ast`) | yes | BNB Chain; funding interval is per symbol |
-| Lighter RH | `lighter-rh` (`lrh`, `rh`) | yes | Lighter engine on the Robinhood chain, USDG collateral |
-| Ondo Perps | `ondo` (`ondo-perps`) | yes | Off-chain engine; limit TIF GTC (default) / IOC / ALO; restricted: US, PA |
-| QFEX | `qfex` (`qf`) | yes (see **QFEX** below) | Custodial, off-chain engine; equities / indices / commodities, cross margin, USDC; limit TIF GTC (default) / IOC / FOK / ALO; testnet = QFEX UAT; restricted: US, GB, ES and others |
-| Arcus | `arcus` | yes | Robinhood chain, USDG collateral; limit TIF GTC (default, sent as GTT) / IOC / FOK / ALO; restricted: US, CA, GB; **access whitelist** — unlisted addresses are rejected (request access at arcus.xyz) |
-
-- **Time in force:** `trade limit` defaults to `GTC` on every venue (common names `GTC | IOC | FOK | ALO`; a TIF the venue does not offer → `CAPABILITY_UNSUPPORTED`). Lighter post-only (`ALO`) is disabled until verified on the venue.
-- **TP/SL on an entry:** `trade market|buy|sell|limit ... --tp <px> --sl <px>` means the same on every venue — *protect this entry's verified fill*. The direction is checked before anything is sent (long: tp > reference > sl; short: the reverse; reference = mark for market entries, the limit price for limit entries). Ondo attaches the legs to the order; Arcus sends an entry+TP/SL batch; Hyperliquid / Lighter / Aster verify the entry fill, then place reduce-only TP/SL trigger orders sized to it (only market or `--tif IOC` entries — a resting entry → `CAPABILITY_UNSUPPORTED`); Pacifica verifies the fill, then sets position TP/SL (refused if the symbol already has a position or TP/SL — never overwritten). Entry outcome unknown → `ORDER_PENDING` and **no** TP/SL (the position may be unprotected); entry filled but a leg failed → `ORDER_PARTIAL` (not retryable) with the entry result and which legs were placed — do not re-enter, finish with `trade tpsl`.
-- **TP/SL on a position:** `trade tpsl <SYM> <long|short> --tp <px> --sl <px> [--tp-limit <px>] [--size <n>]` — the argument is the **position's** side (buy/sell no longer accepted), checked against the live position; legs are reduce-only and sized to the live position (or `--size`).
-- **Stop orders are reduce-only by default** on every venue (`trade stop`); pass `--no-reduce-only` to let a stop open or flip a position (refused on Ondo and QFEX, whose stops are always reduce-only). Lighter / Arcus market triggers execute as a limit at trigger ± the slippage bound (`--slippage-bps` or settings) and may stay unfilled in a fast move; other venues use native market triggers (`--slippage-bps` → `CAPABILITY_UNSUPPORTED`).
-- **Order edit:** `trade edit` keeps the order's TIF. Pacifica: post-only (ALO) orders are edited natively; GTC / TOB orders placed by perp-cli (TIF recorded in the client order id) are cancelled and replaced with the remaining open size; orders whose TIF is unknown → `CAPABILITY_UNSUPPORTED` (pass `--tif`).
-- **Slippage bound:** every market-type order (entry, close, spot) is bounded by one value: `--slippage-bps <n>` → `settings.slippageBps.<venue>` → `settings.defaultSlippageBps` (shipped default 50, shown in `perp settings show`; change with `perp settings set defaultSlippageBps <n>`). Values outside 1..venue max (Arcus 1000) are rejected before sending.
-- **Restricted regions:** creating a signing adapter for a venue with restricted regions (Ondo, Arcus, QFEX) prints a one-time stderr notice; it never blocks — check the venue terms yourself.
-- **Aggregate views** (`portfolio`, `account positions/orders`, `risk`, `history`, `wallet agent verify`, MCP `portfolio`) cover every account venue with configured credentials.
-
-### What works — mainnet verification (2026-10-13)
-
-Every mark below comes from a real-money mainnet run, not from code reading — at the venue minimum, with the per-venue cap raised to about $25–30 for multi-slice / multi-level checks and about $110 for the Hyperliquid TWAP. Details, evidence and the open issues: [`docs/MAINNET-VERIFICATION-STATUS.md`](docs/MAINNET-VERIFICATION-STATUS.md).
-
-✅ verified live · ⛔ not supported (refused before anything is sent) · ❌ implemented but not run on mainnet yet · — not offered by the venue
-
-| Feature | HL | HIP-3 `xyz` | Pacifica | Lighter | Lighter RH | Aster | Ondo | Arcus | QFEX |
-|---|---|---|---|---|---|---|---|---|---|
-| Market / limit (GTC, ALO, IOC), cancel, edit, close, reduce, flatten, status | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Entry `--tp/--sl`, `trade tpsl`, `trade stop` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Stop-limit | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⛔ | ✅ | ⛔ |
-| Resting reduce-only limit | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⛔ | ✅ | ⛔ (IOC only) |
-| Client order id (place / status / cancel) | ✅ | ✅ | ✅³ (UUID) | ✅ (numeric) | ✅ (numeric) | ✅ | ✅ | ✅ | generated ids only |
-| Isolated margin (set, read back with a position, revert) | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (venue rejected with `-4050`, condition unknown) | ⛔ | ✅ | ⛔ |
-| `trade scale-in` / `scale-tp` | ✅ | ✅ (position ≥ $20.5) | ✅ | ✅ | ✅ | ✅ | scale-in ✅ / scale-tp ⛔ — use partial `trade tpsl --size` ✅ | ✅ | scale-in ✅ / scale-tp ⛔ |
-| `trade split` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `trade multi` (legs on several venues) | ✅ | ✅ (global `--dex xyz`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Native TWAP (`trade twap`) | ✅ | ❌ (HL minimum $100) | ✅ master-signed / ⛔ agent-signed | —² | —² | —² | —² | —² | —² |
-| Client-side TWAP (`trade twap` on other venues, `strategy twap`, `--background`) | — | — | — | ✅ | ✅ | ✅ | ✅ | ✅ | ⛔ (automation gate) |
-| `account margin` with a position | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Spot (`trade spot-*`) | ✅ | — | ✅ | ✅ | ✅ | ❌ (needs USDT) | ✅ | ❌ (needs an Arcus-issued key) | — |
-| Deposit via perp-cli | ✅ | (HL) | ✅ | ✅ | ✅ | ✅ | ✅ | — (web app) | — (address only) |
-| Withdraw | ❌ | (HL) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-
-² perp-cli has no native TWAP for this venue: `trade twap` runs the client-side TWAP (slices) instead. Whether the venue's API offers one is not checked.  
-³ Verified in the session; no saved log file.
-
-Automation, verified live (bounded runs at minimum size, stopped and flattened afterwards):
-
-| Area | Verified |
-|---|---|
-| Arbitrage | `arb exec` / `status` / `close` on Aster–Arcus, Lighter–Arcus; `arb auto` (Lighter–HL); spot-perp `arb exec <sym> spot:hl pacifica` and `arb close`; `strategy funding-arb`, `quick-arb`, `funding-auto` (Pacifica–HL); `strategy delta-neutral` (HL spot + Pacifica perp) |
-| Bots | `strategy grid` / `dca` / `trailing-stop` / `quick-grid` / `quick-dca` / `preset` (Aster); all 12 engine strategies via `strategy start <config>` (Aster); `strategy apex` (Aster) |
-| Execution helpers | `strategy twap` (Aster), `trade twap --background` (Arcus), `strategy plan execute` (9 of 10 action types — `cancel_order` not run), `perp background stop` (graceful: orders cancelled, positions listed) |
-| Hyperliquid HIP-4 outcomes | GTC place / cancel, IOC buy, `outcome sell --all` / `--size` |
+```bash
+# Claude Code — slash command
+/install-skill hypurrquant/perp-cli
 
-Not run on mainnet yet: withdrawals and `funds transfer` / `rebalance execute` / `bridge exchange` (run last), subaccounts, builder fees, `strategy claude-agent` (needs an Anthropic key), alerts / dashboard.
+# Cursor / Codex / generic agent CLIs — via npx
+npx skills add hypurrquant/perp-cli
 
-### QFEX
+# Manual install (any agent that reads a Skills directory)
+git clone https://github.com/hypurrquant/perp-cli.git
+cp -R perp-cli/skills/perp-cli ~/.claude/skills/        # or your CLI's skills dir
+```
 
-QFEX is custodial: there is no wallet signature. The only credential is an **API key created on the QFEX website** (Developer Settings, 2FA), imported with `perp wallet agent import qfex` (public key + secret via hidden prompt / stdin; stored encrypted in `~/.perp/qfex-agents/`). The import resolves the **one account UUID** the key trades (primary, or `--account-id <uuid>`), shows it and stores nothing until you confirm it (piped: pass `--account-id` equal to it). Create the trading key **without** the "Deposit and withdraw" permission.
+The skill ships inside the npm package (`perp-cli/skills/perp-cli`), so a global install also makes it available locally:
 
 ```bash
-perp -n testnet wallet agent import qfex              # QFEX UAT (api.qfex.io); y/N on the resolved account
-perp -e qfex market list                              # public: /refdata + market-data snapshot
-perp -e qfex trade limit AAPL buy 320 0.01            # GTC: "accepted" after the ACK; "open" once listed (trade status)
-perp -e qfex trade market AAPL buy 0.01               # IOC LIMIT at mark ± slippage (never the venue's unbounded MARKET)
-perp -e qfex trade status c:<id> --symbol AAPL        # by the generated client order id
-perp funds deposit qfex                               # prints the USDC / Arbitrum One deposit address; you send the funds
+npm install -g perp-cli@latest
+ls "$(npm root -g)/perp-cli/skills/perp-cli"
 ```
 
-Verified on QFEX production (2026-10-13): `trade close` / `close-all` / `flatten` / `reduce` (sent as reduce-only **IOC**), `trade stop`, `trade tpsl` (both legs), market entry with `--sl`, `trade edit` (native modify — a new order id, the client id is kept, so `c:<id>` keeps working), cancel / status by `c:<id>`.
+### What's in the skill
 
-What perp-cli **still refuses on QFEX** (uniform `CAPABILITY_UNSUPPORTED`, before anything is sent):
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Top-level agent guide — rules, workflows, examples |
+| `references/commands.md` | Full non-interactive command reference (every group) |
+| `references/agent-operations.md` | Setup flows, idempotency, error handling, common mistakes |
+| `references/strategies.md` | Funding-arb decision framework + risk management |
+| `scripts/preflight.sh` | Install + wallet + connectivity + risk readiness check |
+| `scripts/arb-monitor.sh` | Live monitor for open arb positions |
+| `scripts/spot-perp-scan.sh` | Scan spot+perp opportunities with balance context |
+| `scripts/funding-analysis.sh` | Cross-exchange funding overview / per-symbol drilldown |
+| `scripts/validate-arb.sh` | Pre-execution validation (price / balance / risk / dry-run) |
 
-| Refused | Why | Do instead |
-|---|---|---|
-| Resting reduce-only orders (`trade limit --reduce-only` with GTC / ALO, `trade scale-tp`) | Live: a resting reduce-only order **stays open after the position goes flat**; how the venue treats it if it later matches is unverified | Reduce-only IOC (`trade close` / `reduce`), or `trade stop` / `trade tpsl` |
-| Stop-limit (`--tp-limit`, `trade stop` with a limit price) | The venue's stop orders convert to market orders when triggered | Stop-market |
-| Stops that open or flip a position (`trade stop --no-reduce-only`) | QFEX stop orders only reduce a position | Reduce-only stops |
-| `trade edit` of a reduce-only order | A reduce-only order is sized against the live position when placed; a modify would skip that check | `trade cancel`, then place again |
-| `--client-id` | Client ids are not unique on the venue; perp-cli only trusts ids it generates | Omit it (the generated id is reported) |
-| Markets not quoted in USD (`SKHYNIX-KRW`, …) | Sizing, risk limits and notionals assume USD | QFEX web app |
-| Unattended automation on QFEX: bots, plans, TWAP, DCA, grid, funding arb, trailing stop, background jobs; QFEX in `arb scan` rankings | Automation is gated until verified (`QFEX_AUTOMATION_VERIFIED`); the funding rate's unit is unverified and equity funding accrues only part of the week (Q4) | Trade QFEX by hand; view funding only: `perp arb scan --rates --include-unverified` |
+See [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md) for the full agent guide.
 
-Known caveat: cancelling a stop / TP right after its position was closed can answer "unexpected error" while the venue removes the stop itself. QFEX keeps no record of stop orders, so perp-cli cannot prove the cancel and reports `ORDER_PARTIAL` (pending) — check `perp -e qfex account orders`; if it lists nothing, the stop is gone.
+## Features
 
-Order outcomes are never guessed: an IOC / market order is final only on a venue terminal frame (nothing filled → `ORDER_REJECTED`, `reason: iocNoFill`); anything unclear after the order was sent is `ORDER_PENDING` with the `c:<id>` to check — never resubmit. perp-cli never enables QFEX cancel-on-disconnect, but **another connection of the same user that enabled it (e.g. the official QFEX CLI) cancels all of the account's orders when that connection drops**.
+- **Funding rate arb** — perp-perp and spot-perp scans, one-command dual-leg entry and exit
+- **Portfolio** — one call returns balances, positions and risk across every venue
+- **Funds** — deposit, withdraw, transfer, multi-provider bridge (CCTP / Relay / deBridge), inter-exchange rebalance
+- **Bots** — TWAP, grid, DCA, trailing stop and more, with background job management
+- **Agent-first** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection
+- **Safety** — pre-trade validation, a slippage bound on every market order, client-id deduplication, response sanitization
 
-**Withdrawals** are authorized by the API key alone, so they are off until you set a local gate in an interactive terminal (no `--yes`, refused under `--json` / pipes / MCP): `perp settings set withdraw.qfex <address[+address…]>,<maxPerTx>,<maxPerDay>`, then `perp funds withdraw qfex <amount> --to <allowlisted address>` (`--dry-run` shows the plan and the gate verdict). The gate guards against mistakes and misdirected automation — it is **not** a defence against key theft; that defence is a trading key without the withdraw permission. QFEX itself documents that withdrawals need 2FA on the web app, so the API may refuse. Subaccounts: `perp -e qfex funds transfer <amount> primary --from <account uuid>`.
+## Venues
 
-### Spot trading
+| Venue | `-e` | Trading | Chain / collateral |
+|---|---|---|---|
+| Hyperliquid | `hyperliquid` (`hl`) | ✅ | HyperEVM, USDC; HIP-3 dexes via `--dex` |
+| Pacifica | `pacifica` (`pac`) | ✅ | Solana, USDC |
+| Lighter | `lighter` (`lt`) | ✅ | Ethereum L2, USDC |
+| Lighter RH | `lighter-rh` (`lrh`) | ✅ | Robinhood chain, USDG |
+| Aster | `aster` (`ast`) | ✅ | BNB Chain, USDT / USDC |
+| Ondo Perps | `ondo` | ✅ | off-chain, USDC |
+| Arcus | `arcus` | ✅ (access whitelist) | Robinhood chain, USDG |
+| QFEX | `qfex` (`qf`) | ✅ (manual trading only) | custodial; equities, indices, commodities |
+| RISEx | `risex` | read-only | RISE chain, USDC |
+| GRVT | `grvt` | market data only | USDT |
+| Extended | `extended` (`ext`) | market data only | Starknet; crypto + equities / FX |
+| Variational | `variational` (`var`) | market data only | RFQ venue |
+| TxFlow | `txflow` (`txf`) | market data only | **unofficial** API |
+| Derive | `derive` | options data only | — |
+
+- **[Support matrix and per-venue notes](docs/venues.md)** — funding, WebSocket, deposit / withdraw, lookups by address, restricted regions
+- **[Mainnet verification](docs/verification.md)** — which features have been run with real money
+- **[Trading details](docs/trading.md)** — time in force, TP/SL, stops, slippage, spot trading, builder fees
+
+## Common commands
 
-Spot support is declared per venue (`VenueDefinition.spot`) and every spot command, portfolio view and bot goes through one factory. Symbols are `BASE/QUOTE`; a bare base (`ETH`) uses the venue's first quote asset.
+```bash
+# Market data
+perp --json -e <EX> market list | book <SYM> | funding <SYM> | kline <SYM> 1h
 
-| Venue | Account model | Quote | Limit / book / cancel | Spot↔perp transfer |
-|-------|---------------|-------|-----------------------|--------------------|
-| Hyperliquid | runtime (unified accounts share USDC with perp; standard accounts are separate) | USDC | yes | yes (no-op on unified accounts) |
-| Lighter / Lighter RH | separate | USDC / USDG | yes | yes |
-| Aster | separate (`sapi` spot account) | USDT, USD1 (bare base → USDT) | yes | yes |
-| Pacifica | **unified** — spot shares the perp account | USDC | yes | no (not needed) |
-| Ondo Perps | separate (spot wallet ↔ margin) | USDC | yes | yes |
-| Arcus | **wallet** — on-chain swaps from your master EVM wallet (router, Permit2) | USDG | no (market swaps only) | no |
+# Trading
+perp --json -e <EX> trade buy <SYM> <SIZE> --tp <PX> --sl <PX>    # entry protected by TP/SL
+perp --json -e <EX> trade limit <SYM> buy <PX> <SIZE>
+perp --json -e <EX> trade close <SYM>                              # or: flatten (every position)
 
-```bash
-perp --json -e <EX> trade spot-buy <SYM> <SIZE> [--slippage-bps <n>] [--yes]
-perp --json -e <EX> trade spot-sell <SYM> <SIZE> [--slippage-bps <n>] [--yes]
-perp --json -e <EX> trade spot-limit <SYM> <buy|sell> <PRICE> <SIZE> [--tif GTC|IOC|ALO]
-perp --json -e <EX> trade spot-cancel <SYM> <ORDER_ID>
-perp --json -e <EX> trade spot-orders [SYM]
-perp --json -e <EX> trade spot-transfer <to-spot|to-perp> <AMOUNT>   # moves the venue's first quote asset
-perp --json -e <EX> trade spot-balance
+# Account
+perp --json portfolio
+perp --json -e <EX> account positions
+perp --json account balance --address <ADDR>                       # any account, keyless
+
+# Funding arb
+perp --json arb scan --min 5
+perp --json arb exec <SYM> <longEx> <shortEx> <USD>
+
+# Funds
+perp --json funds deposit hyperliquid 100
+perp --json funds bridge send --from solana --to arbitrum --amount 100
 ```
 
-- **Unsupported operations fail loudly** with `CAPABILITY_UNSUPPORTED` (e.g. `spot-limit` / `spot-cancel` / `spot-orders` / `spot-transfer` on Arcus).
-- **`spot-transfer` on a shared-balance account** (Pacifica, Hyperliquid unified) succeeds as a no-op with `execution.method: "sharedAccount"` (nothing needs to move); a real move reports `execution.method: "transfer"`.
-- **Slippage:** same rule as perps — `--slippage-bps <n>` → `settings.slippageBps.<venue>` → `settings.defaultSlippageBps` (shipped 50).
-- **Pacifica:** spot buys spend the shared USDC perp margin and reduce perp available margin (a warning is printed before the first buy). Pacifica `getMarkets()` (perp) no longer lists the `SOL-USDC` spot market.
-- **Aster:** an agent signer needs spot permission — `perp wallet agent rotate aster --can-spot` (or `perp wallet agent approve aster --can-spot`); otherwise spot orders fail with `POLICY_DENIED`.
-- **Arcus:** swaps go through `router.spot.arcus.xyz` and settle on the Robinhood chain from the master EVM wallet (`--ows` / active OWS wallet; none → `NO_SIGNER_AVAILABLE`). Spot needs only the master wallet — no Arcus perp agent key; perp orders / account reads without one fail with `AGENT_NOT_REGISTERED` (`perp wallet agent approve arcus`). Listing Arcus spot markets is slow (~80 s, one router `/price` per token) — use `spot-buy` / `spot-sell` directly. Tokens without EIP-2612 permit need a one-time on-chain `approve(Permit2)` that costs Robinhood Chain ETH gas — pass `--yes` to allow it. Results show `status`, `finality`, `receivedToken` and a remediation; a `pending` result means the swap was submitted — **do not resubmit**.
-- **Results:** spot orders print the normalized result (status, finality, filled size, average price, received token, remediation). `spot-buy` / `spot-sell` add an `execution` record on every venue (method, slippage bps + source, protection price and reference where the venue path computes one). `spot-cancel` returns one `SpotOrderResult` shape on every venue (a Lighter cancel is `pending` until `spot-orders` confirms it); `spot-orders` lists the same columns on every venue (Hyperliquid included).
-- **Portfolio / landing:** spot value is added on top of perp equity except balances marked `shared` (Pacifica USDC, Hyperliquid unified USDC). Tokens without a spot price are excluded from totals with a stderr warning (never valued at 0).
-- **Bots and arb** (`funding-arb`, `spot-perp-arb`, `arb exec spot:<venue>`, `arb close`, `arb scan --mode spot-perp`) only use spot venues with a separate (or runtime) spot balance **and** a spot↔perp transfer: hyperliquid, lighter, lighter-rh, aster, ondo. Pacifica (shared margin) and Arcus (on-chain swaps) are refused with `CAPABILITY_UNSUPPORTED`; trade them manually with `trade spot-*`.
+Full list with every group: **[docs/commands.md](docs/commands.md)**. Global flags: `--json`, `--fields <f>`, `--ndjson`, `--dry-run`, `-n testnet`, `-e <venue>`, `--dex <name>` (HIP-3), `-w, --wallet <name>`.
 
 ## Command Groups
 
@@ -233,13 +159,16 @@ perp --json -e <EX> trade spot-balance
 | `account` | Balance, positions, orders, margin |
 | `trade` | Market/limit/stop orders, close, scale, split execution |
 | `outcome` | Hyperliquid Outcome (HIP-4) — binary/range contracts, quoted per outcome (outcomeMeta `quoteToken`, USDC today), no leverage |
+| `options` | Options market data, read-only (Derive: `-e derive options underlyings / expiries / chain / quote`) |
+| `print` | Pacifica Print — strike orders earning a premium per cycle: games, quote, positions, history, events, deposit / cancel (`--dry-run`) |
+| `vault` | Pacifica vaults (API: lakes) — list, info, positions, deposit (master wallet only) / withdraw (`--dry-run`) |
 | `arb` | Funding rate arb — scan, exec, close, monitor (perp-perp & spot-perp) |
 | `strategy` | 19 bot algorithms (grid, dca, twap, APEX, REFLECT, presets) + nested scripted plans |
 | `funds` | Deposit, withdraw, transfer, cross-chain bridge (multi-provider), inter-exchange rebalance |
 | `risk` | Risk limits, liquidation distance, guardrails |
 | `wallet` | Multi-wallet management, agent wallets (`wallet agent ...`), builder fees (`wallet builder ...`, off by default), margin mode / subaccount / API keys (`wallet manage ...`), on-chain balances |
 | `history` | Execution log, PnL, performance breakdown |
-| `portfolio` | Cross-exchange unified overview (replaces former `account balance` / `status` / `dashboard`) |
+| `portfolio` | Cross-exchange unified overview (replaces former `account balance` / `status` / `dashboard`; `account balance --address` reads any account's balances, keyless) |
 | `health` | Adapter health check: ping every venue's REST endpoint (connectivity + latency) |
 | `settings` | CLI settings (referrals, defaults, fees, builder fees, deBridge affiliate) |
 | `backtest` | Strategy backtesting |
@@ -247,165 +176,38 @@ perp --json -e <EX> trade spot-balance
 | `alerts` | Funding rate alerts (Telegram / Discord) with background daemon |
 | `setup` | Setup wizard: OWS wallet, venues, agent wallets, slippage, default venue (alias: `init`; `--non-interactive` for scripts) |
 
-### Builder fees (off by default)
-
-perp-cli attaches **no** builder fee unless you configure one and the venue approval is confirmed:
-
-```bash
-perp settings set builder.hyperliquid 0xBuilder…,1   # <address|code>,<feeBps> — strict: format, venue cap; asks y/N (or --yes)
-perp wallet builder status                            # per venue: supported? configured? approved? attached?
-perp --dry-run wallet builder approve hyperliquid     # plan only
-perp wallet builder approve hyperliquid               # master-signed, asks y/N (or --yes)
-perp --no-builder trade market BTC buy 0.1            # skip it for one command
-perp settings unset builder.hyperliquid               # off again
-```
-
-Supported: hyperliquid (≤ 10 bps, not on HIP-3 dexes), pacifica (≤ 10 bps max, not on spot), aster (≤ 10 bps, mainnet), ondo (≤ 10 bps, no approval step), qfex (`perp settings set builder.qfex <uuid>` — a **fee share**: your fills are attributed to the builder code and you pay the normal fee, nothing extra; the code rides on the trading connection; mainnet only). Lighter / Lighter RH / Arcus: unsupported. If the approval is missing or cannot be read, the order is sent **without** the fee and the result's `execution.notes` says why; `execution.builderFee` shows what was attached.
+## Agent-First CLI Design
 
-## Core Commands
+Built following [agent-first CLI principles](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/):
 
 ```bash
-# Portfolio (balances + positions + risk across all exchanges)
+# Every command returns structured JSON envelope
 perp --json portfolio
+# → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }
 
-# Market data
-perp --json -e <EX> market list
-perp --json -e <EX> market book <SYM>
-perp --json -e <EX> market mid <SYM>              # fast mid-price lookup
-perp --json -e <EX> market funding <SYM>
-perp --json -e <EX> market kline <SYM> 1h          # candlestick data
-perp --json -e hl market hip3                       # list HIP-3 deployed dexes
-
-# Trading
-perp --json -e <EX> trade buy <SYM> <SIZE>          # shortcut for market buy
-perp --json -e <EX> trade sell <SYM> <SIZE>         # shortcut for market sell
-perp --json -e <EX> trade market <SYM> buy <SIZE> --smart  # IOC limit (less slippage)
-perp --json -e <EX> trade split <SYM> buy 5000      # orderbook-aware split (large orders)
-perp --json -e <EX> trade close <SYM>
-perp --json -e <EX> trade flatten                    # close ALL positions on exchange
-perp --json -e <EX> trade reduce <SYM> 50            # reduce position by 50%
-perp --json -e <EX> trade cancel <SYM>               # cancel by symbol (or orderId)
-perp --json -e <EX> trade buy <SYM> <SIZE> --tp <PX> --sl <PX>  # entry protected by TP/SL
-perp --json -e <EX> trade tpsl <SYM> long --tp <PX> --sl <PX>   # TP/SL on an open position (long|short)
-perp --json -e <EX> trade stop <SYM> sell <SIZE> <PX>            # reduce-only stop (default)
-perp --json -e <EX> trade leverage <SYM> <N>
-
-# Account
-perp --json portfolio -e <EX>                        # balance + spot + positions (account balance was renamed in v0.12)
-perp --json -e <EX> account positions
-perp --json -e <EX> account pnl                      # realized + unrealized + funding
-perp --json -e <EX> account funding                  # personal funding payment history
-perp --json -e <EX> account settings                 # per-market leverage & margin mode
-
-# Outcome markets (Hyperliquid HIP-4 — fully-collateralized binary contracts, quote token per outcome (USDC today), min 10 quote tokens)
-perp --json outcome list                                       # active markets + Yes/No mid prices
-perp --json outcome view <outcome>                             # symmetric Yes/No book + underlying gap + expiry
-perp --json outcome book <outcome> <side>                      # one-side orderbook (e.g. '1 yes' or '1 0')
-perp --json outcome positions                                  # open outcome holdings
-perp --json outcome orders                                     # open outcome orders
-perp --json outcome buy <outcome> <side> <usd> --dry-run       # validate before submit
-perp --json outcome buy <outcome> <side> <usd>                 # market buy, notional in the outcome's quote token
-perp --json outcome sell <outcome> <side> <usd> --limit <px> --tif gtc
-perp --json outcome cancel <outcome> <side> <oid>
-
-# Funding rate arbitrage
-perp --json arb scan --min 5                         # perp-perp opportunities
-perp --json arb scan --mode spot-perp                # spot+perp opportunities
-perp --json arb scan --rates                         # funding rates across all exchanges
-perp --json arb scan --basis                         # cross-exchange basis opportunities
-perp --json arb scan --gaps                          # cross-exchange price gaps
-perp --json arb scan --hip3                          # HIP-3 cross-dex funding spreads
-perp --json arb scan --live                          # continuous live monitoring
-perp --json arb exec <SYM> <longEx> <shortEx> <$>   # perp-perp dual-leg entry
-perp --json arb exec <SYM> spot:<exch> <perpEx> <$>  # spot+perp entry
-perp --json arb config                               # show arb defaults
-perp --json arb history                              # past arb trade performance (alias: log)
-
-# Funds (deposit, withdraw, transfer, bridge, rebalance)
-perp --json funds deposit hyperliquid 100
-perp --json funds withdraw pacifica 50
-perp --json funds deposit lighter-rh 10                # USDG on Robinhood Chain (approve + deposit, mainnet)
-perp --json -e lighter-rh funds withdraw lighter 10    # USDG → Robinhood Chain
-perp --json --dry-run funds withdraw ondo 10 --to <ADDRESS>   # plan only, nothing sent
-perp --json funds deposit aster 8                      # USDT → Aster vault on BNB Chain (--chain arbitrum / --asset USDC; mainnet)
-perp --json funds withdraw aster 8 --chain bsc         # USDT → your own address (agent needs --can-withdraw --ip-whitelist)
-perp --json funds deposit ondo 12 --probe 2            # USDC transfer to your Ondo funding address (Arbitrum; --chain ethereum)
-perp --json funds address-book add ondo <MASTER_ADDR>  # SIWE challenge → Ondo withdrawal address book
-perp --json funds withdraw arcus 10                   # to the Arcus account owner
-perp --json funds transfer 100 <ADDRESS>             # HL internal transfer (instant)
-perp --json funds bridge quote --from solana --to arbitrum --amount 100
-perp --json funds bridge send --from solana --to arbitrum --amount 100   # auto-cheapest provider
-perp --json --dry-run funds bridge send --from robinhood --to solana --from-asset USDG --to-asset SOL --amount 15   # Relay quote only
-perp --json funds bridge send --from robinhood --to bsc --from-asset USDG --to-asset USDT --amount 15               # Relay swap, OWS master signs
-perp --json funds bridge exchange --from pacifica --to hyperliquid --amount 100
-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 funds info                               # all routes & limits
-
-# Risk
-perp --json risk limits --max-leverage 5
-perp --json risk liquidation-distance
-
-# Strategies (19 bot algorithms + nested scripted plans)
-perp strategy list-strategies                        # list all available strategies
-perp strategy run <strategy> [symbol]                # run any strategy
-perp strategy apex [symbol]                          # APEX autonomous orchestrator
-perp strategy reflect                                # trading performance analysis
-perp strategy preset-list                            # list strategy presets
-perp --json strategy twap <SYM> buy <SIZE> 30m
-perp --json strategy grid <SYM> --range 5 --grids 10 --size 100
-perp strategy plan example                           # scripted multi-step plan format
-perp --json strategy plan validate <FILE>            # validate scripted plan
-perp --json strategy plan execute <FILE> --dry-run   # dry-run scripted plan
-
-# Background process supervisor (tmux)
-perp background list                                 # list running jobs
-perp background stop <ID>                            # stop a job
-perp background logs <ID> -f                         # follow logs
-# Jobs inherit -n, --dry-run, -e, --ows, -w, --no-agent, --dex and never receive keys via argv/env:
-# they read the OWS vault / agent keystores / ~/.perp/.env themselves. -k, --passphrase, --ows-key or a
-# shell-exported key / OWS_PASSPHRASE is refused — register an agent (perp wallet agent approve <venue>).
-
-```
-
-## Telegram Alerts
-
-Funding rate alerts via Telegram with background daemon support.
-
-```bash
-# Interactive setup (BotFather token + chat ID auto-detection)
-perp alerts setup
+# Filter output to specific fields (saves tokens)
+perp --json --fields totalEquity,risk portfolio
 
-# Add alert rules
-perp alerts add ETH 30              # alert when ETH funding > 30% annualized
-perp alerts add --all 50            # alert for any symbol > 50%
+# Stream large lists as NDJSON (one JSON per line)
+perp --json --ndjson -e hl market list
 
-# Test & manage
-perp alerts test                    # send test message
-perp alerts list                    # show active rules
+# Pre-validate before executing
+perp --json -e hl trade check BTC buy 0.01
+perp --json --dry-run -e hl trade market BTC buy 0.01
 
-# Run daemon
-perp alerts start                   # foreground
-perp alerts start --background      # tmux background daemon
-perp alerts stop                    # stop background daemon
+# Idempotent orders with client ID (Hyperliquid: a 128-bit cloid, 0x + 32 hex; --auto-id generates one)
+perp --json -e hl trade market BTC buy 0.01 --client-id 0x1234567890abcdef1234567890abcdef
+perp --json -e hl trade status c:0x1234567890abcdef1234567890abcdef
 ```
 
-Setup flow: BotFather token → bot validation → send `/start` to bot → auto-detect chat ID → test message.
-
-Exchange flag: `-e hyperliquid` / `-e pacifica` / `-e lighter` / `-e aster` (aliases: `hl`, `pac`, `lt`).
-
-Global flags: `--json`, `--fields <f>`, `--ndjson`, `--dry-run`, `--dex <name>` (HIP-3), `-w, --wallet <name>`.
+All responses are auto-sanitized (control chars stripped, prompt injection patterns blocked).
+Errors include `retryable` flag — only retry when `true`.
 
 ## MCP Server
 
 [![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)
 
-perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts) for Claude Desktop, Cursor, and other MCP clients.
-
-**No API keys required for market data** — explore prices, orderbooks, funding rates, and arb opportunities without any setup. Add keys only when you want to trade.
-
-**Network:** set `PERP_NETWORK=testnet` in the server env to serve testnet (validated; unset = mainnet); every result reports `meta.network`. `trade_execute` / `trade_close` place real orders through the same local risk gate as `perp trade` (no override over MCP), refuse non-reduce-only orders on quarantined symbols, and are written to the execution log.
+`perp-mcp` serves 31 tools to Claude Desktop, Cursor and other MCP clients. Market data needs no keys; for account and trading tools run `perp setup` first (the server reads the same wallet). Never put private keys in the MCP config.
 
 ```json
 {
@@ -418,90 +220,21 @@ perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts)
 }
 ```
 
-For trading and account data, run `perp setup` first: the MCP server reads the same OWS vault wallet and agent keystores as the CLI. Never put private keys in the MCP config. Select the network with `PERP_NETWORK` (`mainnet` | `testnet`; unset = mainnet, invalid values stop the server):
-```json
-{
-  "env": {
-    "PERP_NETWORK": "testnet"
-  }
-}
-```
-
-**Read-only tools (no keys):** `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `arb_scan`, `health_check`
-
-**Account & trading tools (keys required):** `get_balance`, `get_positions`, `portfolio`, `trade_preview`, `trade_execute`, `trade_close`, `get_funding_analysis`, `get_pnl_analysis`, `get_arb_compare`
-
-**Resources:** `market://prices`, `market://funding-rates`, `perp://schema`
+Testnet, the full tool list, resources and prompts: **[docs/mcp.md](docs/mcp.md)**.
 
-**Prompts:** `trading-guide`, `arb-strategy`
+## Documentation
 
-## AI Agent Skill
-
-Drop-in skill for Claude Code, Cursor, Codex, Gemini CLI, and other agent CLIs. Bundles a non-interactive command guide, ops playbook, strategy framework, and reusable shell scripts (preflight, arb monitor, validation) so your agent stops at the right confirmation points and never wedges on interactive wizards.
-
-### Install
-
-```bash
-# Claude Code — slash command
-/install-skill hypurrquant/perp-cli
-
-# Cursor / Codex / generic agent CLIs — via npx
-npx skills add hypurrquant/perp-cli
-
-# Manual install (any agent that reads a Skills directory)
-git clone https://github.com/hypurrquant/perp-cli.git
-cp -R perp-cli/skills/perp-cli ~/.claude/skills/        # or your CLI's skills dir
-```
-
-The skill ships inside the npm package (`perp-cli/skills/perp-cli`), so a global install also makes it available locally:
-
-```bash
-npm install -g perp-cli@latest
-ls "$(npm root -g)/perp-cli/skills/perp-cli"
-```
-
-### What's in the skill
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Top-level agent guide — rules, workflows, examples |
-| `references/commands.md` | Full non-interactive command reference (every group) |
-| `references/agent-operations.md` | Setup flows, idempotency, error handling, common mistakes |
-| `references/strategies.md` | Funding-arb decision framework + risk management |
-| `scripts/preflight.sh` | Install + wallet + connectivity + risk readiness check |
-| `scripts/arb-monitor.sh` | Live monitor for open arb positions |
-| `scripts/spot-perp-scan.sh` | Scan spot+perp opportunities with balance context |
-| `scripts/funding-analysis.sh` | Cross-exchange funding overview / per-symbol drilldown |
-| `scripts/validate-arb.sh` | Pre-execution validation (price / balance / risk / dry-run) |
-
-See [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md) for the full agent guide.
-
-## Agent-First CLI Design
-
-Built following [agent-first CLI principles](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/):
-
-```bash
-# Every command returns structured JSON envelope
-perp --json portfolio
-# → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }
-
-# Filter output to specific fields (saves tokens)
-perp --json --fields totalEquity,risk portfolio
-
-# Stream large lists as NDJSON (one JSON per line)
-perp --json --ndjson -e hl market list
-
-# Pre-validate before executing
-perp --json -e hl trade check BTC buy 0.01
-perp --json --dry-run -e hl trade market BTC buy 0.01
-
-# Idempotent orders with client ID (Hyperliquid: a 128-bit cloid, 0x + 32 hex; --auto-id generates one)
-perp --json -e hl trade market BTC buy 0.01 --client-id 0x1234567890abcdef1234567890abcdef
-perp --json -e hl trade status c:0x1234567890abcdef1234567890abcdef
-```
-
-All responses are auto-sanitized (control chars stripped, prompt injection patterns blocked).
-Errors include `retryable` flag — only retry when `true`.
+| Doc | What's in it |
+|---|---|
+| [Setup](docs/setup.md) | Wallets, agent keys, keys created on the exchange website, where secrets are stored |
+| [Venues](docs/venues.md) | Support matrix, venue ids, QFEX / RISEx / GRVT / Extended / Variational / TxFlow / Derive details |
+| [Trading](docs/trading.md) | Time in force, TP/SL, stops, order edit, slippage, spot trading, builder fees |
+| [Commands](docs/commands.md) | Every command group with examples, Telegram alerts |
+| [Mainnet verification](docs/verification.md) | What has been run with real money, per venue |
+| [MCP server](docs/mcp.md) | Configuration, testnet, tools, resources, prompts |
+| [Signing guardrail](docs/guardrail.md) | `perp-guardrail`, the OWS policy executable for agent keys |
+| [Testing](docs/TESTING.md) | Test suites and the venue checklist |
+| [CHANGELOG](CHANGELOG.md) | Release notes |
 
 ## License