perp-cli 0.14.3 → 0.16.0

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

@@ -4,17 +4,19 @@ All commands support `--json` for structured output. Always use `--json` when ca
 
 ## Global Flags
 
-`--json` (required for agents) | `-e <venue>` | `-n mainnet|testnet` | `--dry-run` (only commands whose `--help` says "supports --dry-run"; others refuse with `INVALID_PARAMS`) | `--fields <f1,f2>` | `--ndjson` | `-w, --wallet <name>` | `--ows <name>` (OWS wallet) | `--no-agent` (skip agent-key routing) | `--no-builder` | `--dex <name>` (HIP-3, Hyperliquid)
+`--json` (required for agents) | `-e <venue>` | `-n mainnet|testnet` | `--dry-run` (honored by: every `trade` write, `arb exec|close|auto|rebalance`, `funds deposit|withdraw|transfer|faucet|bridge send|bridge exchange|rebalance execute|address-book add`, `outcome buy|sell`, `print deposit|cancel`, `vault deposit|withdraw`, `wallet builder approve|revoke`, `wallet manage referral set`, `strategy run`, `strategy plan execute` — `--help` does not always say so; every other command, read-only ones included, refuses it with `INVALID_PARAMS` = unsupported, nothing ran) | `--fields <f1,f2>` | `--ndjson` | `-w, --wallet <name>` | `--ows <name>` (OWS wallet) | `--no-agent` (skip agent-key routing) | `--no-builder` | `--dex <name>` (HIP-3, Hyperliquid)
 
-Venues (`-e`, id | aliases): `pacifica|pac`, `hyperliquid|hl`, `lighter|lt`, `lighter-rh|lrh|rh`, `aster|ast`, `ondo|ondo-perps`, `arcus`, `qfex|qf`. Default = `settings.defaultExchange`, else `pacifica` — always pass `-e`.
+Venues (`-e`, id | aliases): `pacifica|pac`, `hyperliquid|hl`, `lighter|lt`, `lighter-rh|lrh|rh`, `aster|ast`, `ondo|ondo-perps`, `arcus`, `qfex|qf`, `risex|rise` (READ-ONLY in this release — market data + account reads; trading is planned for a later release, every trade / agent / bot write refuses with CAPABILITY_UNSUPPORTED), `txflow|txf` (market data only, UNOFFICIAL API — every write refuses with CAPABILITY_UNSUPPORTED), `variational|var|omni` (market data only, official API, RFQ venue: `market book` = indicative RFQ quotes, `market funding` = current terms — every write refuses with CAPABILITY_UNSUPPORTED), `grvt|grv` (market data only in this version, official API — every write refuses with CAPABILITY_UNSUPPORTED), `extended|ext|x10` (Extended on Starknet, official API, market data only in this version — every write refuses with CAPABILITY_UNSUPPORTED). Default = `settings.defaultExchange`, else `pacifica` — always pass `-e`.
 `-k <key>` is rejected (keys only via stdin / OWS vault). `--passphrase` is deprecated → `OWS_PASSPHRASE` env or stdin.
 
 ## Market Data (read-only, safe)
 ```bash
 perp --json -e <EX> market list                # all markets with prices, funding, volume
-perp --json market prices                      # cross-exchange price comparison
-perp --json -e <EX> market mid <SYMBOL>        # mid price (fast)
-perp --json -e <EX> market info <SYMBOL>       # mark/index price, funding, volume, OI, max leverage
+perp --json market prices                      # cross-exchange price comparison (every market; takes no symbol)
+perp --json -e <EX> market mid <SYMBOL>        # mid price (fast) — the canonical single-symbol price read
+perp --json -e <EX> market info <SYMBOL>       # mark/index price, funding, volume, OI, max leverage, stepSize (no tickSize / min notional — see SKILL.md Step 4)
+# No spot market reads: `market *` are perp markets (HYPE/USDC, @107, HYPE-SPOT → SYMBOL_NOT_FOUND). Spot balances / orders:
+# `trade spot-balance`, `trade spot-orders` (keyed). `arb scan --basis` = cross-venue PERP basis, not spot-perp.
 perp --json -e <EX> market book <SYMBOL>       # orderbook (bids/asks)
 perp --json -e <EX> market trades <SYMBOL>     # recent trades
 perp --json -e <EX> market funding <SYMBOL>    # funding rate history
@@ -24,10 +26,22 @@ perp --json -e hyperliquid --dex <DEX> market list           # one HIP-3 dex's m
 perp --json -e hyperliquid --dex <DEX> market book <SYMBOL>  # any market/account/trade command takes --dex the same way
 ```
 
+Hyperliquid read-path notes:
+- **Venue caps that cannot be paged are refused** (`INVALID_PARAMS` naming the cap; never fewer rows than asked, silently). `trades`: the venue serves only the last 10 trades — the default `--limit` is min(20, 10) = 10, an explicit `--limit` above 10 is refused. `book`: at most 20 levels per side — `-d` above 20 is refused (`-d` cuts JSON too). `kline`: only the most recent 5000 candles per interval exist — a `--start` before now − 5000 × interval is refused before any request, naming the earliest allowed start. `backtest grid --days N` clamps its start to that window and reports `dataFrom` / `truncated`.
+- **kline intervals:** `1m,3m,5m,15m,30m,1h,2h,4h,8h,12h,1d,3d,1w,1M` (anything else → `INVALID_PARAMS`, not retryable). `1M` candles are **30-day buckets**, not calendar months; `1w` candles open **Thursday 00:00 UTC**. Each candle carries `closed` (false on the in-progress last candle).
+- **funding:** `--limit N` = the last N hourly settlements (paged over the venue's 500-row cap; max 5000).
+- **Delisted markets** (meta `isDelisted`, e.g. `MATIC`, every asset of `--dex km`) → `SYMBOL_NOT_FOUND` with `details.reason: "delisted"` on `info` / `trades` / `funding` / `book` / `kline`; orders / positions / history still resolve them. `market hip3` lists live assets only (`assets`), plus `delistedAssets` and `delisted: true` for a dex with no live asset; `deployer` comes from `perpDexs`.
+- **Symbol naming:** `market list` / `info` rows use the plain coin `BTC` (HIP-3: `xyz:XYZ100`; the wire coin is in `venueSymbol`), as `market trades` rows and the WS codec. `-PERP` arguments still resolve. Keyed `account positions` rows still show `BTC-PERP`; strip `-PERP` to compare.
+- **marginTiers:** a market on a single-tier table (`marginTableId` < 50) reports `[{ lowerBound: 0, maxLeverage: <id> }]` (docs "Margin tiers"), not null.
+
 ## Account (read-only, safe)
 ```bash
 perp --json portfolio -e <VENUE_ID>            # perp balance + spot holdings + 24h funding; venue id or alias (hl, lt, …)
 perp --json -e <EX> account positions          # open positions
+perp --json -e <EX> account positions --address <ADDR>   # ANY account's open positions, keyless (public data; nothing signed)
+perp --json account positions --address <0xADDR>         # every supporting venue: { venues, errors?, notes? }
+perp --json -e <EX> account balance --address <ADDR>     # ANY account's balances + spot, keyless (same venues; Lighter: per account, --account-index)
+perp --json account balance --address <0xADDR>           # every supporting venue: { venues, errors?, notes? }
 perp --json -e <EX> account orders             # open/pending orders
 perp --json -e <EX> account history            # order history
 perp --json -e <EX> account trades             # trade fill history
@@ -38,6 +52,14 @@ perp --json -e <EX> account pnl                # realized + unrealized + funding
 perp --json -e <EX> account twap-orders        # active TWAP orders
 perp --json portfolio                          # cross-exchange unified view
 # funding24h is null (with fundingError) when a venue's funding history is unreadable; totals.fundingIncomplete = true then
+# --address (public-address positions): hyperliquid / lighter / lighter-rh / risex take a 0x address, pacifica a base58
+#   Solana address (a wrong format → INVALID_PARAMS before any request); other venues → CAPABILITY_UNSUPPORTED
+#   (feature publicPositions). Rows = the account positions rows with plain symbols, plus:
+#   hyperliquid: native + EVERY HIP-3 dex (one read each), `dex: null | "<dex>"`; a dex that fails is in
+#     meta.errors["hip3:<dex>"] + meta.warnings — its rows are missing, the others are kept (exit 0).
+#   lighter / lighter-rh: every account (sub-account) of the address, `accountIndex` on each row; zero-size rows
+#     dropped; --account-index <n> narrows (not an account of the address → INVALID_PARAMS). No account → [] + meta.notes.
+#   --symbol <SYM> filters (GOLD matches xyz:GOLD). meta: { address, source: "public" }. MCP: get_positions_by_address.
 perp --json portfolio --arb                    # full dashboard with arb top 5
 ```
 
@@ -61,10 +83,13 @@ perp --json -e <EX> trade market <SYM> buy <SIZE> --split   # split via flag
 perp --json -e <EX> trade limit <SYMBOL> <buy|sell> <PRICE> <SIZE> [--tif GTC|IOC|FOK|ALO]   # default GTC on every venue; off-grid price → INVALID_TICK (never rounded)
 perp --json -e <EX> trade stop <SYMBOL> <SIDE> <SIZE> <STOP_PRICE>   # reduce-only by default; --no-reduce-only to open (refused on ondo / qfex)
 perp --json -e <EX> trade tpsl <SYMBOL> <long|short> --tp <P> --sl <P>   # positionSide = the open position's side
-perp --json -e <EX> trade buy <SYMBOL> <SIZE> --tp <P> --sl <P>         # entry protected by TP/SL (verified fill)
+perp --json -e <EX> trade buy <SYMBOL> <SIZE> --tp <P> --sl <P>         # entry protected by TP/SL (verified fill); absolute prices, not %; not with --smart
+#   trade limit --tp/--sl: ondo / arcus any entry, other venues --tif IOC only
 
 # Order management
-perp --json -e <EX> trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>
+perp --json -e <EX> trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>   # SIZE = new open size; may return a NEW orderId — use it
+#   pacifica: TIF from the order's client id — ALO native edit, GTC / TOB cancel+replace (new id either way);
+#   ondo: cancel+replace; qfex: venue assigns a new id (client id kept); --tif only on ondo / pacifica
 perp --json -e <EX> trade cancel <SYMBOL_OR_ORDER_ID> [orderId]
 perp --json -e <EX> trade cancel-all
 perp --json -e <EX> trade cancel-stop <SYMBOL> <STOP_ORDER_ID>   # pacifica / qfex only; other venues: trade cancel
@@ -82,6 +107,7 @@ perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage 3
 perp --json -e <EX> trade close <SYMBOL>                # close single position
 perp --json -e <EX> trade close-all                     # close all positions
 perp --json -e <EX> trade flatten                       # cancel all orders + close all positions
+# close / close-all do NOT cancel resting TP/SL / stop / limit orders (QFEX: WARNING lists them) — check account orders
 perp --json -e <EX> trade reduce <SYMBOL> <PCT>         # reduce by percentage
 perp --json -e <EX> trade leverage <SYMBOL> <N> [--isolated]
 
@@ -91,6 +117,16 @@ perp --json -e <EX> trade scale-in <SYMBOL> <SIDE> --levels '<P1>:<PCT>,<P2>:<PC
 perp --json -e <EX> trade pnl-track                     # real-time PnL tracker
 perp --json -e <EX> trade twap <SYMBOL> <SIDE> <SIZE> <DURATION>   # Pacifica: seconds (native), HL: minutes (native, min $100); others client-side: --background [--slices <n>]
 
+# Pacifica Atomic basket (pacifica only; other venues → CAPABILITY_UNSUPPORTED). Legs SYMBOL[:WEIGHT] (≤ 5 per side, each market once);
+# --usd is split by weight at each mark, floored to the lot, each leg ≥ the market's USD minimum. ONE POST /orders/batch of market
+# orders — NOT all-or-nothing: each leg fills or fails on its own (ORDER_PARTIAL / ORDER_REJECTED / ORDER_PENDING per basket).
+# --reduce-only: --long legs must close shorts, --short legs must close longs (checked before sending). Supports --dry-run (plan + unsigned body).
+perp --json -e pacifica trade atomic --long BTC:50 --short ETH:50 --usd 1000 [--reduce-only] [--slippage-bps <n>] [--force]
+# A leg needs notional ≥ the market minimum × (1 + slippage bound). Legs without an order_id in the ack are traced by their client_order_id.
+# A batch failure other than HTTP 400 / 429 (timeout, 5xx, unreadable answer) → ORDER_PENDING and EVERY leg is quarantined.
+# Pacifica Chase / OCO / Trailing Stop / Swarm / Trigger Swarm / Conditional Market|Limit: no documented API / SDK path (as of 2026-10-19) —
+# nearest here: trade twap (≈ Swarm, split market execution), trade tpsl (≈ OCO bracket exit).
+
 # Spot helpers (any venue with spot)
 perp --json -e <EX> trade spot-buy <SYMBOL> <SIZE>
 perp --json -e <EX> trade spot-sell <SYMBOL> <SIZE>
@@ -181,6 +217,61 @@ Encoding formula: `enc = 10 * outcome + side`; asset id = `100,000,000 + enc`.
 
 Settlement at `expiryMs` is venue-side: winning side → 1 quote token per share, losing → 0. Decide before expiry whether to self-close or let the venue settle.
 
+## Options market data (read-only, `-e derive`)
+
+Derive (derive.xyz, formerly Lyra) options through its official public v3 API — keyless, no orders, no account. Options venues are separate from the perp venues (not in `perp health`, arb or `market`). JSON objects carry `schema: 1`; decimals are strings; unknown is `null` (empty book side → `bid`/`ask` `null`; IV the venue could not compute → `null`; 24h high/low `null` without trades).
+
+```bash
+perp --json -e derive options underlyings                     # underlyings with options (spot price)
+perp --json -e derive options expiries ETH                    # active expiries: expiry (YYYY-MM-DD UTC), expiryMs, strikes, instruments
+perp --json -e derive options chain ETH                       # nearest expiry (expirySelection: "nearest"), every strike
+perp --json -e derive options chain ETH --expiry 2026-12-25 --strikes 10   # 10 strikes closest to ATM (forward, else index)
+perp --json -e derive options quote ETH-20261225-3500-P       # one option
+```
+
+- Chain row: `{strike, call, put}`; each side is an option quote: `bid`/`ask` `{price, size}`, `mark`, `index`, `forward`, `discountFactor`, `iv {mark, bid, ask}`, `greeks {delta, gamma, theta, vega, rho}` (venue units, verbatim), `openInterest` (contracts), `stats24h {contracts, notional, premium, trades, high, low}`, `timestampMs`. Chain level: `index`, `forward` (both of the newest ticker of the expiry, not an average), `atm {strike, reference, price}`, `strikesListed`, `missingTickers`.
+- Errors: unknown underlying / expiry / instrument → `SYMBOL_NOT_FOUND` (remediation names the listing command / active expiries); a perp name in `quote` → `INVALID_PARAMS`; an active option with no live ticker (activation / expiry race) → `EXCHANGE_ERROR` (retry); other Derive rejections → `EXCHANGE_ERROR`; no `-e` or a perp venue → `CAPABILITY_UNSUPPORTED`; Derive's rate limit → `RATE_LIMITED` (retryable).
+- Cost: `expiries` 1 request, `chain` 2 (instruments + ONE tickers call for the expiry), `quote` 2. Derive's public budget is 5 requests/s per IP.
+- `-n testnet` reads `testnet.api.derive.xyz`. MCP: `get_option_expiries`, `get_option_chain`, `get_option_quote` (`venue: "derive"`).
+
+## Pacifica Print (`perp print`) and vaults (`perp vault`)
+
+Pacifica-only products: these commands always use Pacifica (`-e <other venue>` → `INVALID_PARAMS`). Reads are unauthenticated GETs and never sign; `--account <address>` reads any account without a key. Every write supports `--dry-run`, which prints the exact message to sign and the body (`signature: null`), never signs and sends nothing. `--account` on a write only plans (with `--dry-run`); a live write with `--account` is refused.
+
+**Signer rule (perp-cli, stricter than the venue):** `vault deposit` is **master-only** (like `funds withdraw pacifica`) — an agent key must never be able to move the balance into a vault someone else manages; with only an agent key on the machine it is `NO_SIGNER_AVAILABLE`. `vault withdraw` (pays only into the own account), `print deposit` and `print cancel` are signed by the active signer (the agent key when approved, else the master). `wallet manage lake deposit|withdraw` were replaced by these commands (they now refuse with a pointer); `wallet manage lake create --initial-deposit` is refused with an agent key.
+
+**Idempotency:** every deposit / withdraw sends a fresh `idempotency_key`. After `ORDER_PENDING` never resubmit with a new key; the only safe retry is the same command with `--idempotency-key <the reported key>` (the venue answers a duplicate with HTTP 409; how long it remembers a key is unverified). `error.details.before` holds the pre-write state (Print order count / vault shares) to compare with `print positions` / `vault positions`.
+
+### Print — strike orders that earn a premium every cycle
+A Print order locks a USDC deposit (min 10) as margin at a target price: **long** = target BELOW mark, **short** = target ABOVE mark, 0.5% … 10% / 20% / 40% from mark for a 24-hour / 7-day / 30-day cycle. Leverage 1 … product max (`print games`). The premium is credited to the order at the START of each cycle. **While resting** (before a fill) it is evaluated only at the END of each cycle: it fills AT the target (size = deposit × leverage ÷ target), rolls to a new target at the same % distance, or is liquidated; max loss = deposit + premiums. **After a fill** it is an ordinary perp position in the main account — continuous mark-price liquidation, it nets with an existing position in the same market and may be cross-margined; read it with `perp -e pacifica account positions`. Product / pool deposit caps are totals across all users (the venue refuses when full). `--cycles 1…1000` caps the cycles (default: roll until cancelled). A cancel takes effect only at the end of the running cycle — funds stay locked until then (up to 30 days on BTC_1M).
+```bash
+perp --json -e pacifica print games                                  # products: cycle, max lev, caps, allowed target range
+perp --json -e pacifica print quote BTC_24H long 100 --strike 79000 --leverage 10 [--cycles 7]
+#   read-only preview: notional, size on fill, docsLiquidationPrice, maxLoss, lock; estimatedPremium is null
+#   (the venue's premium preview is a signed request — never called on a read path)
+perp --json -e pacifica print positions [--account <addr>]           # current orders: printing | cancelling | filled | liquidated | cancelled | completed | ended
+perp --json -e pacifica print history [--account <addr>] [--limit N] [--cursor C]
+perp --json -e pacifica print events <printAddress> [--limit N] [--cursor C]   # created / premium / end_requested / position_opened / liquidated
+perp --json -e pacifica --dry-run print deposit BTC_24H long 100 --strike 79000 --leverage 10 --cycles 7
+perp --json -e pacifica print deposit BTC_24H long 100 --strike 79000 --leverage 10 --cycles 7   # POST /game/deposit (deposit_to_game)
+perp --json -e pacifica --dry-run print cancel <printAddress>         # UNOFFICIAL: POST /game/end (end_game) is not in the API docs (apiStatus: "unofficial")
+perp --json -e pacifica print cancel <printAddress> --unverified-endpoint   #   live run needs the flag; only a `printing` order
+```
+- `docsLiquidationPrice` is the docs formula (margin fully lost) — an outer bound, not the trigger: a liquidation was observed earlier in one live case (2026-10-16, ZEC_24H short at mark 1216.84 vs formula ≈ 1269); the venue's trigger is unpublished. For a 1× long the formula gives ≤ 0: `null` = unknown, not "no liquidation". Show the user `maxLoss`.
+
+### Vaults (API: lakes)
+A vault is a Pacifica account traded by its manager; LPs get shares at NAV (lp_balance ÷ lp_shares). Min deposit 10 USDC; `deposit_cap` caps the LP balance; the manager takes `manager_profit_share` above the high-water mark. A withdrawal redeems shares into YOUR OWN trading balance (the API has no destination) only after `deposit_min_duration_ms` since your LAST deposit (each deposit restarts the lock for your whole balance), inside the withdrawal window when one is set (open while now_s mod window < duration), and from the vault's free balance (a fully deployed vault may pay partially). APY is not published (`apy: null`).
+```bash
+perp --json -e pacifica vault list [--account <addr>]                 # TVL, NAV/share, fee, lock-up, window, config
+perp --json -e pacifica vault info <address|nickname>                 # + live equity, positions, deposit whitelist (UNOFFICIAL endpoint, advisory), window open now?
+#   a nickname must match exactly ONE vault (case-insensitive) — duplicates exist live ("Pacifica Vault" / "Pacifica vault");
+#   ambiguity → INVALID_PARAMS listing every candidate's address / manager / TVL. Writes: prefer the ADDRESS.
+perp --json -e pacifica vault positions [--account <addr>]            # your LP (or manager) shares and value
+perp --json -e pacifica --dry-run vault deposit <vault> <amount>      # POST /lake/deposit (deposit_to_lake) — MASTER-ONLY; refused when the LP NAV is zero / undefined
+perp --json -e pacifica --dry-run vault withdraw <vault> <shares>|--all   # POST /lake/withdraw (withdraw_from_lake)
+```
+MCP (read-only): `pacifica_print_products`, `pacifica_print_quote`, `pacifica_print_positions`, `pacifica_vaults`. Print / vault writes are CLI-only.
+
 ## Funds (deposit, withdraw, transfer, bridge, rebalance)
 
 All fund movement lives under `perp funds`.
@@ -201,6 +292,8 @@ perp --json funds deposit lighter-rh <AMOUNT>               # USDG on Robinhood
 # Ondo Perps: NO API withdrawals — `funds withdraw ondo` → CAPABILITY_UNSUPPORTED; withdraw in the Ondo web app
 perp --json funds withdraw arcus <AMOUNT>                   # USDG → the account owner (min 1)
 perp --json funds deposit qfex                              # prints the USDC / Arbitrum One deposit address (sends nothing)
+# RISEx: deposits / withdrawals are app-only — `funds deposit|withdraw risex` → CAPABILITY_UNSUPPORTED (app.rise.trade)
+# RISEx is read-only in this release (trading later): `funds faucet risex` → CAPABILITY_UNSUPPORTED too
 # QFEX: withdrawals disabled in perp-cli for now — `funds withdraw qfex` → CAPABILITY_UNSUPPORTED; withdraw in the QFEX web app
 perp --json -e qfex funds transfer <AMOUNT> primary --from <account-uuid>   # between your QFEX accounts
 perp --json funds deposit aster <AMOUNT> [--chain bsc|arbitrum] [--asset USDT|USDC]   # vault approve + deposit (mainnet; default BNB Chain USDT)
@@ -251,24 +344,54 @@ perp --json arb scan                                        # default --mode all
 perp --json arb scan --mode perp-perp --min 10              # perp-only with min annual %
 perp --json arb scan --mode spot-perp --min 10              # spot+perp only
 perp --json arb scan --rates                                # funding rates across exchanges
+# Which rate is compared: each venue's market-row `fundingRate` (the CURRENT rate it publishes), labelled
+# per row by `rateKind` — Pacifica / Lighter / Lighter RH / Arcus / RISEx / Ondo "lastSettled", Hyperliquid /
+# Aster / TxFlow / Extended "accruing", GRVT / Variational "predicted", null = QFEX (not established). It is NOT the WS comparator's kind:"next" (predicted
+# next-period rate, where a venue publishes one: Pacifica `predictedFundingRate`).
 perp --json arb scan --basis [SYMBOL]                       # cross-exchange basis
 perp --json arb scan --gaps                                 # cross-exchange price gaps
 perp --json arb scan --hip3                                 # HIP-3 cross-dex spreads
-perp --json arb scan --history [SYMBOL]                     # historical funding
+perp --json arb scan --history [SYMBOL] [--hours 24]        # LOCAL snapshots only (~/.perp/funding-rates/, written by
+#   `arb scan --rates` / `portfolio --arb`; hyperliquid / pacifica / lighter unless -e) — `rates: {}` until scans
+#   have run; `historicalAvg` (avg1h/8h/24h/7d) in --rates / --compare rows comes from the same store (null when empty).
+#   Real settled history: perp --json -e <EX> market funding <SYM> -l <N>  (newest first; rate = fraction per
+#   intervalHours → hourly = rate / intervalHours, annual % = hourly × 8760 × 100; average the rows yourself)
 perp --json arb scan --compare <SYMBOL>                     # compare a symbol across exchanges
 perp --json arb scan --positions                            # position funding impact; actual24h null + fundingHistoryErrors when a venue's history is unreadable
 perp --json arb scan --live --interval 60                   # continuous monitoring
 perp --json arb scan --top 10 --hold-days 7 --bridge-cost 0 --size 100  # cost-aware filtering
-perp --json arb scan --rates --include-unverified           # also show QFEX (unverified funding; display only, never ranked)
+perp --json -e extended market list                          # Extended (read-only): rows carry assetClass, venueSymbol (TSLA_24_5-USD), tickSize, minSize, tradable, fundingRateKind "accruing"
+perp --json -e extended market funding BTC -l 24            # applied hourly prints: rateKind "lastSettled", intervalHours 1, annualizedPct
+perp --json arb scan --rates --include-unverified           # also show QFEX, TxFlow, Variational, GRVT and Extended (unverified funding; TxFlow rows apiStatus "unofficial"; display only, never ranked)
+perp --json -e qfex market funding AAPL -l 72               # hourly windows; outside the market's funding hours: rate null + marketClosed true (not a 0 rate)
+# QFEX marketClosed limits: (1) a market holiday INSIDE a configured session (e.g. SAMSUNG-KRW on
+# Hangul Day, a weekday) is not in market_hours, so its 0 prints as a real-looking rate "0" with
+# marketClosed false; (2) US equities DO fund in the weekday overnight gap (post_market → pre_market),
+# so only an exact 0 with no part of the hour in any funding session counts as closed — a real 0
+# in a gap would also read as closed. Averages / APRs skip marketClosed rows only.
 # netSpread / grossSpread = annualized % (netSpread = gross minus round-trip costs amortized over --hold-days)
-# spot-perp rows: netSpreadPct / grossSpreadPct, spotExchanges[], perpExchange, direction
+# estFeesPct = round trip on BOTH legs = 2 × (taker fee leg A + taker fee leg B) + 2 × 0.05 % slippage, taker fees from
+#   `perp settings fees show` (settings.fees, else the shipped table — the spot leg uses its venue's perp taker rate);
+#   e.g. hl+hl: 2 × (0.035 + 0.035) + 0.1 = 0.24 %. `settings fees show` is the per-fill rate, estFeesPct the round trip.
+# perp-perp rows: mode, longExch, shortExch, markPrice, grossSpread(Pct), netSpread(Pct), estFeesPct, priceGapPct
+# spot-perp rows: mode, spotExchanges[], perpExchange, direction, perpFundingRate, netSpreadPct / grossSpreadPct AND
+#   netSpread / grossSpread (same values), estFeesPct, estHourlyIncomeUsd (per $1000), breakEvenDays, markPrice.
+#   Executable only when direction == "long-spot-short-perp" (arb exec spot: always buys spot + shorts the perp and
+#   does not check the funding sign) — never act on "sell-spot-long-perp".
+# --rates / --compare rows: symbol, rates[] (exchange, fundingRate, hourlyRate, annualizedPct, rateKind, fundingVerified,
+#   historicalAvg), maxSpreadAnnual / longExchange / shortExchange / estHourlyIncomeUsd (null with < 2 verified rates),
+#   executable (act only when true), readOnlyLegs, unverifiedLegs, mixedKinds; --rates top level: symbols[], minSpread,
+#   belowMinSpread, exchangeStatus, exchangeErrors. --compare <unknown> → ok:true, data { symbol, available: false }.
+# Testnet funding / spreads are meaningless (thousands of %/yr) — analyse yield on mainnet only.
 
 # Execute (perp-perp or spot+perp via spot:<venue>; spot venues: hl, lt, lrh, aster, ondo)
 # Sequential: long first, then the short sized to the verified long fill; reconcile always on;
 # an unconfirmed leg quarantines the symbol. Supports --dry-run.
 perp --json arb exec <SYM> <longEx> <shortEx> <USD>         # perp-perp dual-leg entry
-perp --json arb exec <SYM> spot:hl hl <USD>                 # spot+perp via HL spot
+perp --json arb exec <SYM> spot:hl hl <USD>                 # spot+perp via HL spot (long-spot-short-perp rows only)
 perp --json arb exec <SYM> spot:lt pac <USD>                # spot+perp via LT spot
+#   spot: validates balances (spot quote + transferable perp; perp margin), both books (empty book → refused),
+#   spot/perp mid gap ≤ 5 %, depth and venue minimums before anything moves
 perp --json arb exec <SYM> <longEx> <shortEx> <USD> \
    --leverage 2 --isolated --smart --max-slippage 0.5
 
@@ -282,6 +405,8 @@ perp --json arb close <SYM> --state-only --yes              # drop a stale state
 
 # Status / history / config / rebalance
 perp --json arb status                                      # open arb positions + PnL + funding; check unconfirmedPairs, staleStateEntries
+#   reads every configured venue; one failing venue fails the whole command (EXCHANGE_ERROR, no venue filter) →
+#   check per venue with `-e <EX> account positions`
 # spot-perp entries: fundingSource actual | partial | estimate | recorded (+ fundingError) — only "actual" is complete settled funding
 perp --json arb status --period 7 --symbol BTC              # filter funding lookback / symbol
 perp --json arb history                                     # alias: arb log
@@ -299,8 +424,7 @@ perp --json --dry-run arb auto                              # simulate (--backgr
 
 ## Wallet Management
 ```bash
-perp --json wallet generate evm                # generate EVM wallet
-perp --json wallet generate solana             # generate Solana wallet
+perp --json wallet generate [name] [--words 12|24]   # new multi-chain OWS vault wallet (EVM + Solana); passphrase via OWS_PASSPHRASE / stdin
 printf '%s' "$KEY" | OWS_PASSPHRASE=<pp> perp --json wallet import --name <n> [--chain evm|solana|dual] [--mnemonic]   # import a key (stdin / hidden prompt; argv key, --evm/--solana <key>, --legacy rejected)
 printf '%s' "$KEY" | OWS_PASSPHRASE=<pp> perp --json wallet set hl   # import key (stdin / hidden prompt; argv key rejected) into OWS vault → active wallet
 perp --json wallet set pac --name pac          # Solana key, hidden prompt (TTY)
@@ -337,6 +461,9 @@ perp --json wallet agent approve <exchange> \
   [--account-index <0-9|255>]          # Arcus subaccount
   [--api-key-index <n>]                # Lighter slot 4-254 (default: first slot free locally AND on-chain)
   [--force]                            # Lighter: overwrite an --api-key-index slot that already holds an on-chain key
+# risex: READ-ONLY in this release (trading is planned for a later release) — `wallet agent approve|import|revoke|rotate
+#   risex` → CAPABILITY_UNSUPPORTED (also with --dry-run); `wallet agent verify risex` (read-only) still works.
+#   txflow / variational / extended: every agent command → CAPABILITY_UNSUPPORTED (market data only).
 
 # Import a key the USER created on the exchange WEBSITE (master wallet not needed here).
 # Key on stdin only (one line; ondo: key id + secret; qfex: public key + secret) — an argv key is rejected (INVALID_PARAMS).
@@ -383,9 +510,8 @@ perp --json wallet manage account-mode [unified|standard|portfolio]   # Hyperliq
 perp --json wallet manage sub create <name>            # not supported (CAPABILITY_UNSUPPORTED): the subaccount wallet must co-sign — use the web app
 perp --json wallet manage sub list
 perp --json wallet manage sub transfer <from> <to> <amount>   # <from> must be the signing account
-perp --json wallet manage lake create [--manager <address>] [--nickname <name>] [--initial-deposit <amount>]
-perp --json wallet manage lake deposit <lake> <amount>       # <lake> = vault address
-perp --json wallet manage lake withdraw <lake> <shares>      # shares to redeem, not USDC
+perp --json wallet manage lake create [--manager <address>] [--nickname <name>] [--initial-deposit <amount>]   # --initial-deposit: master-signed only
+perp --json wallet manage lake deposit|withdraw …           # MOVED → perp -e pacifica vault deposit|withdraw (refused here)
 perp --json wallet manage builder overview                    # Pacifica builder-OWNER tools only (user approvals: wallet builder)
 perp --json wallet manage builder trades <code>
 perp --json wallet manage builder leaderboard <code>
@@ -411,7 +537,7 @@ perp --json wallet policy delete <id>
 ## Risk & Analytics
 ```bash
 perp --json risk status                        # portfolio risk overview (level, violations, canTrade)
-perp --json health                             # adapter health: ping venue REST endpoints (connectivity + latency)
+perp --json health                             # keyless venue ping: data.healthy (official venues up), allHealthy (+ unofficial), exchanges[], unofficial[], skipped[]
 perp --json risk liquidation-distance          # % distance from liquidation for ALL positions
 perp --json risk limits                        # view current risk limits
 perp --json risk limits --min-liq-distance 30 --max-leverage 5  # set risk limits (also --max-position[-pct], --max-exposure[-pct], --max-positions, --daily-loss[-pct], --max-drawdown[-pct], --max-margin, --reset)

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

@@ -59,7 +59,10 @@ During transition, you are **unhedged**. Price can move against you. Factor this
 ```bash
 perp --json arb scan --min 5             # find spreads > 5% annual (shows longExch/shortExch/netSpread)
 perp --json arb scan --rates             # raw funding rates across all exchanges
-perp --json arb scan --history <SYMBOL>  # historical funding for a symbol
+perp --json -e <EX> market funding <SYMBOL> -l 168   # settled funding history per venue (newest first; average it yourself)
+# `arb scan --history <SYMBOL>` = only snapshots THIS machine recorded during earlier `arb scan --rates` runs
+# (often `rates: {}`; `historicalAvg` in --rates / --compare rows is null for the same reason) — not venue history.
+# Testnet rates are meaningless (thousands of %/yr): analyse on mainnet only.
 # NOTE: legacy 'arb rates'/'arb prices'/'arb dex' are removed — all routes go through 'arb scan'
 ```
 
@@ -75,6 +78,8 @@ netSpread: 12.87          → annualized % after round-trip trading costs amorti
                             (and --bridge-cost if given)
 ```
 
+(perp-perp rows. `--rates` / `--compare` rows name the legs `longExchange` / `shortExchange` and are actionable only when `executable === true`; spot-perp rows have `spotExchanges` / `perpExchange` / `direction` — see "Spot-Perp Carry".)
+
 **Rules:**
 1. **ALWAYS follow longExch/shortExch directions exactly.** DO NOT reverse them.
 2. **NEVER enter if netSpread ≤ 0.** Negative netSpread = loss after fees over the assumed hold. A shorter real hold makes costs weigh more — re-scan with your `--hold-days`.
@@ -181,7 +186,7 @@ Desired size: 1.0
 ```bash
 perp --json -e <EX> market info <SYM>    # check maxLeverage, volume, openInterest
 ```
-Round `ORDER_SIZE` to the coarser step size of the two exchanges. If the matched size falls below either exchange's minimum, the arb is NOT executable at this size — reduce target or skip.
+Round `ORDER_SIZE` to the coarser step size of the two exchanges. If the matched size is below $15 notional on either leg (the skill's default smallest order — the $10 venue minimums plus a buffer for price moves, step rounding and fees; see SKILL.md Step 4), the arb is NOT executable at this size — raise the target or skip.
 
 #### Step 2: Execute Legs Sequentially with Same Size
 
@@ -267,6 +272,34 @@ If positions already have mismatched sizes, close to the smaller size first, the
 - Better opportunity found (after accounting for switch cost!)
 - Risk limits breached
 
+## Spot-Perp Carry (long spot + short perp)
+
+**What:** buy the asset spot and short the same asset's perp while perp funding is POSITIVE (longs pay shorts) — the short leg collects funding, the spot leg pays none, price exposure nets out.
+
+**Find:**
+```bash
+perp --json arb scan --mode spot-perp --min 0 --hold-days 14 --size 500   # mainnet; keep only direction == "long-spot-short-perp"
+perp --json -e <perpExchange> market funding <SYM> -l 168                 # is the rate persistent? (settled, newest first)
+```
+Row fields: `spotExchanges[]` (venues that can hold the spot leg; `arb exec` spot venues: hl, lt, lrh, aster, ondo), `perpExchange`, `direction`, `grossSpread` / `netSpread` (annual %), `estFeesPct` (round trip on BOTH legs: 2 × (taker A + taker B) + 0.1 % slippage — taker fees from `perp settings fees show`), `breakEvenDays` (days of funding needed to pay `estFeesPct`), `estHourlyIncomeUsd` (per $1000). `--hold-days` amortizes the fees into `netSpread`; `--size` / `--bridge-cost` add a bridge cost when the legs sit on different venues. A `sell-spot-long-perp` row is NOT a carry trade for perp-cli: `arb exec spot:` always buys spot and shorts the perp (it does not check the funding sign), so on such a row it pays funding.
+
+**Economics:**
+- Net ≈ funding received on the short − `estFeesPct` (entry + exit, both legs) − bridge cost if the legs are on different venues.
+- Capital = the FULL spot notional in the spot venue's quote token (`trade spot-balance`; separate-margin venues transfer the shortfall perp→spot) + perp margin (notional / leverage, with a buffer) on the perp venue. Hyperliquid unified accounts fund both legs from one balance.
+- Practical ceiling: on many venues funding sits at the base interest rate, 0.00125 %/h ≈ 10.95 % APR (observed 2026-10-26 on HYPE: Pacifica / Ondo / Arcus 10.95 %, Hyperliquid 24 h average ≈ 7.6 %). Treat ~11 % gross as the normal ceiling for liquid assets; much higher prints are usually short-lived spikes — check the settled history before entering.
+- There is no spot price / book read in perp-cli, so the spot-perp basis cannot be pre-computed here; `arb exec` itself compares the spot and perp books (refuses an empty book or a > 5 % mid gap) and checks depth and venue minimums before anything moves.
+
+**Risks:** funding flips negative (the short then PAYS — exit when the settled rate stays negative); short-leg liquidation on a rally (spot gains on another venue do not margin the perp) → 1–2x leverage, isolated margin, watch `risk liquidation-distance`; basis moves at entry / exit; venue / transfer risk on the spot leg.
+
+**Execute / exit (dry-run first, user confirmation for each live step):**
+```bash
+perp --json --dry-run arb exec <SYM> spot:hl hl <USD> --leverage 2 --isolated   # only for a long-spot-short-perp row
+perp --json arb exec <SYM> spot:hl hl <USD> --leverage 2 --isolated
+perp --json arb status                                    # spotPerpPairs; fails as a whole if one venue read fails
+perp --json --dry-run arb close <SYM> --spot-exch hl --perp-exch hl
+perp --json arb close <SYM> --spot-exch hl --perp-exch hl
+```
+
 ## Risk Management — THE MOST IMPORTANT SECTION
 
 **Risk management is more important than profit.** A single liquidation can wipe out months of funding rate income. Every decision you make should be filtered through risk first, profit second.
@@ -399,7 +432,9 @@ Compare each position's unrealized P&L. In a perfect arb, they should roughly of
 
 Think in terms of total capital across all exchanges:
 ```bash
-perp --json portfolio                        # totalEquity, marginUtilization, concentration
+perp --json portfolio                        # totals.{equity,marginUsed,marginPct,funding24h,fundingIncomplete}, risk.{level,marginPct}, exchanges[].perp.available
+# MCP `portfolio`: totalEquity / totalAvailable / totalMarginUsed / riskMetrics.marginUtilization are null when no balance
+# was read — check accountState ("ok" | "unread" | "noAccount") and totalsCover (venues included) first
 ```
 
 Rules of thumb: