perp-cli 0.12.17 → 0.14.0

package/README.md

@@ -4,7 +4,7 @@
 [![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).
+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).
 
 ```bash
 npm install -g perp-cli       # global install
@@ -16,7 +16,7 @@ npx -y perp-cli --json portfolio
 
 ## Features
 
-- **4 Exchanges** — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter, Aster
+- **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
@@ -27,15 +27,26 @@ npx -y perp-cli --json portfolio
 ## Setup
 
 ```bash
-# Set exchange keys
-perp wallet set pac <SOLANA_KEY>     # Pacifica
-perp wallet set hl <EVM_KEY>         # Hyperliquid
-perp wallet set lt <EVM_KEY>         # Lighter (API key auto-generated)
-perp wallet set aster <API_KEY>      # Aster (BNB Chain)
-
-# Or interactive setup wizard
+# 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
 ```
@@ -44,6 +55,176 @@ 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:
+
+```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
+```
+
+### No master wallet on this computer — import a key created on the exchange website
+
+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.
+
+```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
+```
+
+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).
+
+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.
+
+## Venues
+
+| 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` |
+
+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.
+
+### QFEX
+
+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.
+
+```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
+```
+
+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 perp-cli **still refuses on QFEX** (uniform `CAPABILITY_UNSUPPORTED`, before anything is sent):
+
+| 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` |
+
+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.
+
+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**.
+
+**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>`.
+
+### Spot trading
+
+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.
+
+| 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 |
+
+```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
+```
+
+- **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-*`.
+
 ## Command Groups
 
 | Group | Description |
@@ -51,22 +232,35 @@ Same EVM key works for both Hyperliquid and Lighter.
 | `market` | Prices, orderbook, funding, klines, HIP-3 dexes |
 | `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 |
 | `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 & on-chain balances |
+| `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 |
-| `manage` | Margin mode, subaccount, API keys, builder |
-| `portfolio` | Cross-exchange unified overview |
-| `dashboard` | Live web dashboard |
-| `settings` | CLI settings (referrals, defaults) |
+| `portfolio` | Cross-exchange unified overview (replaces former `account balance` / `status` / `dashboard`) |
+| `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 |
 | `background` | Background process supervisor (tmux sessions for strategies, alerts, etc.) |
-| `alerts` | Telegram funding rate alerts with background daemon |
-| `agent` | Schema introspection, capabilities, health check |
-| `setup` | Interactive setup wizard (alias: `init`) |
-| `status` | Unified dashboard: balances, positions, arb opps |
+| `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.
 
 ## Core Commands
 
@@ -91,16 +285,29 @@ 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 tpsl <SYM> long            # set take-profit / stop-loss
+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 -e <EX> account balance
+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
@@ -117,9 +324,19 @@ perp --json arb history                              # past arb trade performanc
 # 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
@@ -146,6 +363,9 @@ perp --json strategy plan execute <FILE> --dry-run   # dry-run scripted plan
 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>).
 
 ```
 
@@ -185,6 +405,8 @@ perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts)
 
 **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.
+
 ```json
 {
   "mcpServers": {
@@ -196,14 +418,11 @@ perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts)
 }
 ```
 
-Optional: add keys for trading and account data:
+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": {
-    "PACIFICA_PRIVATE_KEY": "your-solana-key",
-    "HYPERLIQUID_PRIVATE_KEY": "your-evm-key",
-    "LIGHTER_PRIVATE_KEY": "your-evm-key",
-    "ASTER_API_KEY": "your-api-key"
+    "PERP_NETWORK": "testnet"
   }
 }
 ```
@@ -276,8 +495,9 @@ perp --json --ndjson -e hl market list
 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
-perp --json -e hl trade market BTC buy 0.01 --client-id my-unique-id
+# 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).

package/dist/_stderr-filter.js

@@ -5,7 +5,6 @@
 if (process.argv.includes("--json") || process.argv.includes("--ndjson")) {
     const _suppressPatterns = [
         /'--chain evm' is deprecated/,
-        /\[hyperliquid\] Failed to load asset map/,
         /\[lighter\] Account index not available/,
         /Failed to initialize SymbolConversion/,
         /HyperliquidAPIError/,

package/dist/agent-wallet/lighter-keystore.d.ts

@@ -32,3 +32,14 @@ export declare function deleteLighterKey(accountIndex: number, slot: number): bo
  * never reads from keystore back to env.
  */
 export declare function migrateFromEnvIfPresent(): void;
+export type LighterFamilyVenue = "lighter" | "lighter-rh";
+type KeystoreNetwork = "mainnet" | "testnet";
+/** Absolute (network-tagged) keystore path for a Lighter-family L2 key. */
+export declare function lighterFamilyKeystorePath(venue: LighterFamilyVenue, network: KeystoreNetwork, accountIndex: number, slot: number): string;
+/** Encrypt + persist a Lighter-family L2 private key (hex) at its network-tagged path. Returns the absolute path. */
+export declare function saveLighterFamilyKey(venue: LighterFamilyVenue, network: KeystoreNetwork, accountIndex: number, slot: number, privateKeyHex: string, passphrase: string): string;
+/** Read + decrypt a Lighter-family L2 private key (hex, no 0x) for `network`. Throws on missing/corrupt/wrong passphrase. */
+export declare function loadLighterFamilyKey(venue: LighterFamilyVenue, network: KeystoreNetwork, accountIndex: number, slot: number, passphrase: string): string;
+/** Idempotent delete of the `network` key (after migrating an untagged file). Returns true if a file was removed. */
+export declare function deleteLighterFamilyKey(venue: LighterFamilyVenue, network: KeystoreNetwork, accountIndex: number, slot: number): boolean;
+export {};

package/dist/agent-wallet/lighter-keystore.js

@@ -14,10 +14,11 @@
  * No fallbacks (SSOT Rule #2): missing files / wrong passphrase throw with
  * remediation pointing the user at `perp wallet agent approve lighter --rotate`.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync, } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, renameSync, chmodSync, } from "fs";
 import { resolve } from "path";
 import { randomBytes, scryptSync, createCipheriv, createDecipheriv, } from "node:crypto";
 import { PerpError } from "../errors.js";
+import { loadVenueSecret, saveVenueSecret, venueKeystorePath, writeKeystoreAtomic } from "./venue-keystore.js";
 const KDF_PARAMS = { dklen: 32, n: 65536, p: 1, r: 8 };
 const SCRYPT_OPTS = { N: KDF_PARAMS.n, r: KDF_PARAMS.r, p: KDF_PARAMS.p, maxmem: 128 * 1024 * 1024 };
 const REMEDIATION = "perp wallet agent approve lighter --rotate";
@@ -52,8 +53,11 @@ function stripHexPrefix(hex) {
  * Returns the absolute path of the written file.
  */
 export function saveLighterKey(accountIndex, slot, privateKeyHex, passphrase) {
-    const dir = ensureDir();
-    const path = resolve(dir, `${accountIndex}-${slot}.json`);
+    ensureDir();
+    return writeLighterKeyFile(lighterKeystorePath(accountIndex, slot), accountIndex, slot, privateKeyHex, passphrase);
+}
+function writeLighterKeyFile(path, accountIndex, slot, privateKeyHex, passphrase) {
+    ensureDir();
     const cleanHex = stripHexPrefix(privateKeyHex).toLowerCase();
     if (!/^[0-9a-f]+$/.test(cleanHex) || cleanHex.length === 0) {
         throw new PerpError("INVALID_PARAMS", "Lighter L2 private key must be hex", {
@@ -89,12 +93,7 @@ export function saveLighterKey(accountIndex, slot, privateKeyHex, passphrase) {
         },
         createdAt: new Date().toISOString(),
     };
-    writeFileSync(path, JSON.stringify(file, null, 2), { mode: 0o600 });
-    // Re-tighten in case writeFileSync overwrote an existing file with a looser umask
-    try {
-        chmodSync(path, 0o600);
-    }
-    catch { /* non-fatal */ }
+    writeKeystoreAtomic(path, JSON.stringify(file, null, 2));
     return path;
 }
 /**
@@ -111,7 +110,9 @@ export function loadLighterKey(accountIndex, slot, passphrase) {
     // before continuing. This is NOT a runtime fallback — it's a single-pass
     // upgrade path that runs at most once per install.
     migrateFromEnvIfPresent();
-    const path = lighterKeystorePath(accountIndex, slot);
+    return readLighterKeyFile(lighterKeystorePath(accountIndex, slot), passphrase);
+}
+function readLighterKeyFile(path, passphrase) {
     if (!existsSync(path)) {
         throw new PerpError("KEY_NOT_FOUND", `LIGHTER_KEYSTORE_NOT_FOUND: ${path}`, { remediation: REMEDIATION });
     }
@@ -230,3 +231,84 @@ function clearEnvLegacyKeys() {
     }
     writeFileSync(ENV_FILE, out.join("\n"), { mode: 0o600 });
 }
+const LIGHTER_RH_AGENTS_DIR = "lighter-rh-agents";
+const LIGHTER_RH_REMEDIATION = "perp wallet agent approve lighter-rh --rotate";
+function rhKeyName(accountIndex, slot) {
+    if (!Number.isInteger(accountIndex) || accountIndex < 0 || !Number.isInteger(slot) || slot < 0) {
+        throw new PerpError("INVALID_PARAMS", `invalid Lighter RH keystore address: account ${accountIndex}, slot ${slot}`, {
+            remediation: LIGHTER_RH_REMEDIATION,
+        });
+    }
+    return `${accountIndex}-${slot}`;
+}
+/** Network-tagged keystore file name (`<network>-<accountIndex>-<slot>`). Account indexes are per network. */
+function taggedName(network, accountIndex, slot) {
+    return `${network}-${rhKeyName(accountIndex, slot)}`;
+}
+/** Absolute (network-tagged) keystore path for a Lighter-family L2 key. */
+export function lighterFamilyKeystorePath(venue, network, accountIndex, slot) {
+    switch (venue) {
+        case "lighter": return resolve(lighterAgentsDir(), `${taggedName(network, accountIndex, slot)}.json`);
+        case "lighter-rh": return venueKeystorePath(LIGHTER_RH_AGENTS_DIR, taggedName(network, accountIndex, slot));
+    }
+}
+/** Pre-tagging path `<accountIndex>-<slot>` (no network). */
+function legacyFamilyKeystorePath(venue, accountIndex, slot) {
+    switch (venue) {
+        case "lighter": return lighterKeystorePath(accountIndex, slot);
+        case "lighter-rh": return venueKeystorePath(LIGHTER_RH_AGENTS_DIR, rhKeyName(accountIndex, slot));
+    }
+}
+/**
+ * One-time move of a pre-tagging `<accountIndex>-<slot>` file to the tagged path. Called only
+ * with the network of a network-TAGGED agent record (untagged records are refused upstream by
+ * agentNetworkOf → re-register), and approve refuses to reuse another network's account+slot,
+ * so the untagged file belongs to that record's network.
+ */
+function migrateUntaggedKeystore(venue, network, accountIndex, slot) {
+    const tagged = lighterFamilyKeystorePath(venue, network, accountIndex, slot);
+    if (existsSync(tagged))
+        return;
+    const legacy = legacyFamilyKeystorePath(venue, accountIndex, slot);
+    if (!existsSync(legacy))
+        return;
+    renameSync(legacy, tagged);
+    process.stderr.write(`[${venue}] keystore ${accountIndex}-${slot} tagged as ${network} (moved to ${tagged})\n`);
+}
+/** Encrypt + persist a Lighter-family L2 private key (hex) at its network-tagged path. Returns the absolute path. */
+export function saveLighterFamilyKey(venue, network, accountIndex, slot, privateKeyHex, passphrase) {
+    switch (venue) {
+        case "lighter":
+            return writeLighterKeyFile(lighterFamilyKeystorePath(venue, network, accountIndex, slot), accountIndex, slot, privateKeyHex, passphrase);
+        case "lighter-rh": {
+            const cleanHex = stripHexPrefix(privateKeyHex).toLowerCase();
+            if (!/^[0-9a-f]+$/.test(cleanHex)) {
+                throw new PerpError("INVALID_PARAMS", "Lighter RH L2 private key must be hex", {
+                    remediation: LIGHTER_RH_REMEDIATION,
+                });
+            }
+            return saveVenueSecret(LIGHTER_RH_AGENTS_DIR, taggedName(network, accountIndex, slot), cleanHex, passphrase);
+        }
+    }
+}
+/** Read + decrypt a Lighter-family L2 private key (hex, no 0x) for `network`. Throws on missing/corrupt/wrong passphrase. */
+export function loadLighterFamilyKey(venue, network, accountIndex, slot, passphrase) {
+    if (venue === "lighter")
+        migrateFromEnvIfPresent();
+    migrateUntaggedKeystore(venue, network, accountIndex, slot);
+    switch (venue) {
+        case "lighter":
+            return readLighterKeyFile(lighterFamilyKeystorePath(venue, network, accountIndex, slot), passphrase);
+        case "lighter-rh":
+            return loadVenueSecret(LIGHTER_RH_AGENTS_DIR, taggedName(network, accountIndex, slot), passphrase, LIGHTER_RH_REMEDIATION);
+    }
+}
+/** Idempotent delete of the `network` key (after migrating an untagged file). Returns true if a file was removed. */
+export function deleteLighterFamilyKey(venue, network, accountIndex, slot) {
+    migrateUntaggedKeystore(venue, network, accountIndex, slot);
+    const path = lighterFamilyKeystorePath(venue, network, accountIndex, slot);
+    if (!existsSync(path))
+        return false;
+    unlinkSync(path);
+    return true;
+}

package/dist/agent-wallet/passphrase.d.ts

@@ -2,7 +2,7 @@
  * Resolve master passphrase from (in precedence order):
  *   1. opts.flag  (--passphrase)
  *   2. process.env.OWS_PASSPHRASE
- *   3. stdin (only if process.stdin.isTTY === false)
+ *   3. stdin (only when stdin is not a TTY — Node leaves isTTY undefined for pipes/files)
  *
  * Returns null if no path provides one AND stdin IS TTY (caller may prompt).
  * Throws PASSPHRASE_REQUIRED with remediation if no path provides one AND

package/dist/agent-wallet/passphrase.js

@@ -1,10 +1,11 @@
+import { fstatSync } from "node:fs";
 import { PerpError } from "../errors.js";
 const REMEDIATION = "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe (echo $PP | perp ...)";
 /**
  * Resolve master passphrase from (in precedence order):
  *   1. opts.flag  (--passphrase)
  *   2. process.env.OWS_PASSPHRASE
- *   3. stdin (only if process.stdin.isTTY === false)
+ *   3. stdin (only when stdin is not a TTY — Node leaves isTTY undefined for pipes/files)
  *
  * Returns null if no path provides one AND stdin IS TTY (caller may prompt).
  * Throws PASSPHRASE_REQUIRED with remediation if no path provides one AND
@@ -20,8 +21,16 @@ export async function resolvePassphrase(opts) {
     if ("OWS_PASSPHRASE" in process.env) {
         return process.env["OWS_PASSPHRASE"] ?? "";
     }
-    // 3. stdin pipe — only when stdin is not a TTY
-    if (process.stdin.isTTY === false) {
+    // 3. stdin pipe — only when stdin is not a TTY. Node sets isTTY only for a TTY;
+    // a pipe or redirected file leaves it undefined, so test `!== true`.
+    if (process.stdin.isTTY !== true) {
+        // Read only a real pipe or redirected file. Anything else (/dev/null, a socket,
+        // an inherited never-closing stream) has no passphrase to give — reading it could block forever.
+        if (!stdinIsPipeOrFile()) {
+            throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is not a terminal or a pipe", {
+                remediation: REMEDIATION,
+            });
+        }
         const piped = await readStdin();
         if (piped !== null) {
             return piped;
@@ -34,6 +43,10 @@ export async function resolvePassphrase(opts) {
     // stdin IS TTY — caller decides whether to prompt interactively
     return null;
 }
+function stdinIsPipeOrFile() {
+    const st = fstatSync(0);
+    return st.isFIFO() || st.isFile();
+}
 /**
  * Read all bytes from stdin until EOF, trim trailing newlines.
  * Returns null if stdin produced zero bytes.