perp-cli 0.14.2 → 0.15.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), **Lighter RH** (Robinhood chain), **Ondo Perps** (off-chain), **Arcus** (Robinhood chain), **QFEX** (off-chain, TradFi perps).
+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), **RISEx** (RISE chain — read-only in 0.15.0, trading in a later release), **TxFlow** (market data only — unofficial API), **Variational Omni** (market data only — official API, RFQ venue), **GRVT** (market data only — official API; trading in a later release), **Extended** (Starknet, market data only — official API; trading in a later release), and **Derive** options data (read-only).
 
 ```bash
 npm install -g perp-cli       # global install
@@ -16,7 +16,7 @@ npx -y perp-cli --json portfolio
 
 ## Features
 
-- **8 Venues** — trade on Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus, QFEX (bridge / perp-perp arb cover the original four)
+- **13 perp venues** — trade on 8: Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus, QFEX (bridge / perp-perp arb cover the original four); market data on RISEx (read-only in 0.15.0, trading in a later release) TxFlow (unofficial API, read-only), Variational (official API, read-only — no public trading API yet) GRVT (official API, read-only in this version — trading in a later release) and Extended (official API, read-only in this version — trading in a later release); plus **Derive** options data (read-only). See the [support matrix](#support-matrix)
 - **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
@@ -24,6 +24,31 @@ npx -y perp-cli --json portfolio
 - **Agent-First Design** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection
 - **Safety** — pre-trade validation, response sanitization, client-id deduplication
 
+## Support matrix
+
+What each venue supports in this release, derived from the code (venue definitions in `src/exchanges/venues/*.ts`, `perp-cli/ws` codecs in `src/ws/codecs/`, the `funds deposit|withdraw` commands, the options registry). ✅ = implemented and available; — = not available. This says what perp-cli **offers**, not what was run with real money — for that see [What works — mainnet verification](#what-works--mainnet-verification-2026-10-13).
+
+| Venue | Market data (CLI) | Funding | WS stream (`perp-cli/ws`) | Trading | Deposit via perp-cli | Withdraw via perp-cli | Extras | API |
+|---|---|---|---|---|---|---|---|---|
+| Hyperliquid (incl. HIP-3 via `--dex`) | ✅ | ✅ hourly | ✅ public + user (HIP-3 dexes opt-in) | ✅ | ✅ (USDC from Arbitrum) | ✅ (CCTP) | spot, outcomes (HIP-4), native TWAP | official |
+| Pacifica | ✅ | ✅ hourly | ✅ public + user | ✅ | ✅ | ✅ | spot (unified margin), native TWAP (master-signed only); Print (`perp print`), Vaults (`perp vault`; deposit master-only) and Atomic basket (`trade atomic`) — each not yet verified live; legacy `wallet manage lake`: `create` still works, `deposit` / `withdraw` refuse and point to `perp vault` | official |
+| Lighter | ✅ | ✅ hourly | ✅ public + user | ✅ | ✅ (L1 or CCTP) | ✅ | spot, client-side TWAP | official |
+| Lighter RH | ✅ | ✅ hourly | ✅ public + user (mainnet; testnet WS → HTTP 403) | ✅ | ✅ (USDG, mainnet) | ✅ (`-e lighter-rh funds withdraw lighter`) | spot, client-side TWAP | official |
+| Aster | ✅ | ✅ per symbol | ✅ public only (user channels: known gap) | ✅ | ✅ (USDT / USDC, mainnet) | ✅ (agent with `--can-withdraw --ip-whitelist`) | spot, client-side TWAP | official |
+| Ondo Perps | ✅ | ✅ hourly | — | ✅ | ✅ (USDC, mainnet) | — (the API allows none; web app)⁴ | spot, client-side TWAP | official |
+| Arcus | ✅ | ✅ hourly | ✅ public + user | ✅ | — (web app) | ✅ (to the account owner) | spot (on-chain swaps), client-side TWAP | official |
+| QFEX | ✅ | unverified (display only, `--include-unverified`) | — | ✅ (no resting reduce-only, no automation — see [QFEX](#qfex)) | address only | — (disabled for now; web app)⁵ | — | official |
+| RISEx | ✅ | ✅ hourly | — | — (**read-only in 0.15.0**; trading in a later release) | — (app only) | — (app only) | account reads by address | official |
+| TxFlow | ✅ | unverified (display only, `--include-unverified`) | — | — (market data only) | — | — | — | **unofficial** |
+| Variational | ✅ (`market book` = RFQ quotes, not an order book) | unverified (display only, `--include-unverified`); interval per market (1h / 4h / 8h) | — | — (market data only) | — | — | equities / ETFs / commodities; pre-IPO (not matched) | official |
+| GRVT | ✅ | unverified (display only, `--include-unverified`); interval per market (4h / 8h) | — (per-instrument streams only) | — (market data only in this version; trading in a later release) | — | — | equities / ETFs, commodities; pre-IPO not matched | official |
+| Extended | ✅ (crypto plus equities / ETFs / commodities / indices / FX) | unverified (display only, `--include-unverified`), hourly; `_24_5` equities print 0 off-hours | — (one socket per stream; not supported yet) | — (read-only in 0.15.0) | — | — | asset-class column; pre-IPO and ambiguous tickers not matched | official |
+| Derive | options only (`perp -e derive options …`) | — | — | — (**read-only**; trading in a later release) | — | — | options: underlyings, expiries, chain (IV, greeks), quote | official |
+
+- **Funding** ✅ = the rate's unit is verified against settled payments (`fundingVerified`), so the venue takes part in `arb scan` and funding strategies; unverified venues are shown only with `--include-unverified`, never ranked or traded.
+- **WS stream** = `perp-cli/ws` / `@hypurrquant/perp-ws` channels: public = all-market / per-market state and `bbo`; user = account, positions, orders, fills. `book` / `trades` channels are not available yet on any venue.
+- **Client-side TWAP** = `trade twap` / `strategy twap` slicing on venues without a native TWAP (refused on QFEX by its automation gate).
+
 ## Setup
 
 ```bash
@@ -34,7 +59,7 @@ pbpaste | OWS_PASSPHRASE="$PP" perp wallet set pac --name pac   # Pacifica (Sola
 # 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
+# Or the interactive setup wizard (every trading venue): 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.
@@ -111,6 +136,11 @@ Secrets are stored once (see `docs/SSOT_RULES.md` Rule #3): Lighter RH → `~/.p
 | 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) |
+| RISEx | `risex` (`rise`) | **no — read-only in 0.15.0** (trading in a later release; see **RISEx** below) | Fully on-chain order book on RISE chain, USDC; official API. Market data, funding and account reads by address; every trade / agent / bot path → `CAPABILITY_UNSUPPORTED`; deposits / withdrawals in the RISEx app only |
+| Variational | `variational` (`var`, `omni`) | **no — market data only** (see **Variational** below) | Variational Omni, an RFQ venue (one market maker, no order book); official read-only API, no public trading API yet. Funding is unverified (shown only with `--include-unverified`); restricted: US, CA and others |
+| GRVT | `grvt` (`grv`) | **no — market data only in this version** (trading in a later release; see **GRVT** below) | Hybrid perps exchange, USDT collateral; official Market Data API. Funding is unverified (shown only with `--include-unverified`); testnet = `-n testnet`; trading needs KYC; restricted: US, CA, SG, HK and others |
+| Extended | `extended` (`ext`, `x10`) | **no — market data only in this version** (trading in a later release; see **Extended** below) | Perps order book on Starknet (formerly X10), USD collateral; official public API. Crypto plus RWA (equities, ETFs, indices, commodities, FX). Funding is unverified (shown only with `--include-unverified`); testnet = Sepolia (`-n testnet`); restricted: US, GB, CA, HK and others |
+| TxFlow | `txflow` (`txf`) | **no — market data only** | **UNOFFICIAL API**: TxFlow has no official API yet; perp-cli reads the undocumented API its web app uses. It may change or break without notice. Funding is unverified (shown only with `--include-unverified`) |
 
 - **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`.
@@ -123,7 +153,7 @@ Secrets are stored once (see `docs/SSOT_RULES.md` Rule #3): Lighter RH → `~/.p
 
 ### 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).
+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.
 
 ✅ verified live · ⛔ not supported (refused before anything is sent) · ❌ implemented but not run on mainnet yet · — not offered by the venue
 
@@ -143,10 +173,15 @@ Every mark below comes from a real-money mainnet run, not from code reading —
 | `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) | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Withdraw (to your own address)⁶ | ✅ | (HL) | ✅ | ✅ | ✅ | ✅ (`--asset USDC`) | ⛔⁴ | ✅ | ⛔⁵ |
+
+RISEx, TxFlow, Variational, GRVT and Extended are not in this table: none trades in this release. RISEx trading (shipped but disabled in 0.15.0) was exercised on **testnet** only (2026-10-14); no mainnet RISEx order has been run.
 
 ² 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.
+³ Verified in the session; no saved log file.  
+⁴ Not available: the Ondo Perps API does not allow withdrawals (`funds withdraw ondo` → `CAPABILITY_UNSUPPORTED`). Withdraw in the Ondo web app.  
+⁵ Disabled in perp-cli for now (`funds withdraw qfex` → `CAPABILITY_UNSUPPORTED`). Withdraw in the QFEX web app.  
+⁶ Mainnet, 2026-10-13: one withdrawal per venue to the account's own address, received amount checked on the destination chain — `funds withdraw hyperliquid 12.22` (Arbitrum USDC), `funds withdraw pacifica 12.98` (Solana USDC), `-e lighter funds withdraw lighter 15.95` (Ethereum USDC), `-e lighter-rh funds withdraw lighter 12.96` and `funds withdraw arcus 9.94` (Robinhood Chain USDG), `funds withdraw aster 8.74 --chain arbitrum --asset USDC` (Arbitrum USDC).
 
 Automation, verified live (bounded runs at minimum size, stopped and flattened afterwards):
 
@@ -157,7 +192,17 @@ Automation, verified live (bounded runs at minimum size, stopped and flattened a
 | 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.
+Funds and bridge, verified live (mainnet, 2026-10-13 — `funds bridge send` runs, `funds rebalance plan` + `execute --withdraw-only` after a $11 HL deposit, alerts rule commands without a channel):
+
+| Area | Verified | Not verified |
+|---|---|---|
+| `funds bridge send` | deBridge Arbitrum → Solana USDC (OWS-signed); Relay swaps Arbitrum ETH → Robinhood ETH, Robinhood USDG → Solana SOL / USDC, Robinhood USDG → Arbitrum USDC | CCTP routes; any **Solana-source** bridge (the OWS Solana signing path is covered by mocked tests only) |
+| `funds bridge exchange` | — | everything; the HyperCore → Solana CCTP route (`--from hyperliquid --to pacifica`) is suspected broken (Solana recipient encoding) |
+| `funds rebalance` | `plan`; `execute --withdraw-only` (HL → Arbitrum) | `execute --auto-bridge` (no gas pre-check yet) |
+| `funds transfer` | — | HL `usdSend`, QFEX account transfer (need a receiving account) |
+| alerts | rule `add` / `list` / `remove`; `test` / `start` refuse without a channel | Telegram / Discord delivery (needs a bot token) |
+
+Not run on mainnet yet: subaccounts, builder fees, `strategy claude-agent` (needs an Anthropic key), dashboard.
 
 ### QFEX
 
@@ -190,7 +235,96 @@ Known caveat: cancelling a stop / TP right after its position was closed can ans
 
 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>`.
+**Withdrawals** are disabled in perp-cli for now (`funds withdraw qfex` → `CAPABILITY_UNSUPPORTED`, also under `--dry-run`); withdraw in the QFEX web app. Subaccounts: `perp -e qfex funds transfer <amount> primary --from <account uuid>`.
+
+### RISEx (read-only in 0.15.0 — trading in a later release)
+
+RISEx is a fully on-chain perps order book on RISE chain (USDC collateral), reached through its **official** API. New venues ship in phases: in this release perp-cli reads RISEx data only; trading comes in a later release.
+
+```bash
+perp -e risex market list                     # public; funding = last settled hourly rate (verified)
+perp -e risex market book BTC                 # also: prices | info | trades | kline | funding
+perp arb scan --rates                         # RISEx rows in the funding comparison
+perp health                                   # RISEx is probed as an official venue
+perp -e risex account positions --ows <master>   # account reads are public by address — nothing is signed
+```
+
+- **Refused in this release** (`CAPABILITY_UNSUPPORTED`, "RISEx trading is planned for a later perp-cli release", before any key is read or request is sent — also under `--dry-run`): every `perp -e risex trade …` write, `trade multi` / `arb exec` / `arb auto` legs, every `strategy …` command (bots, plans, TWAP / grid / DCA, `--exchanges` legs), `wallet agent approve|import|revoke|rotate risex` (`revoke --force` only clears the local record), `perp setup --venues risex`, `funds faucet risex`, and the MCP `trade_preview` / `trade_execute` / `trade_close` tools. `arb scan --basis` covers trading venues only, so RISEx is not in it; in `arb scan` a pair with a RISEx leg is marked `executable: false` / "(read-only)".
+- **Funds:** deposits and withdrawals are done in the RISEx app (app.rise.trade). `funds deposit|withdraw risex`, `funds transfer -e risex` and `funds rebalance execute` with risex refuse with `CAPABILITY_UNSUPPORTED` (also under `--dry-run`).
+- The trading code (session signer restricted on-chain to trading only, EIP-712 permits) ships with its tests but is switched off by one flag (`RISEX_TRADING_ENABLED` in `src/exchanges/venues/risex-release.ts`).
+
+### TxFlow (market data only — UNOFFICIAL API)
+
+TxFlow publishes no official API yet. perp-cli reads the **undocumented** API that app.txflow.com uses — read-only, and it may change or be blocked at any time. Every JSON row carries `venueApi: "unofficial"` (`apiStatus` in mixed tables and MCP output); human output adds a footnote.
+
+```bash
+perp -e txflow market list | info <SYM> | book <SYM> | trades <SYM> | kline <SYM> 1h
+perp arb scan --rates --include-unverified                  # TxFlow funding (percent per hour on the venue, shown as a fraction), display only
+```
+
+Every trade / account / portfolio / funds (deposit, withdraw, transfer, rebalance) / agent / builder / strategy / arb exec command and every MCP account or trading tool refuses TxFlow with `CAPABILITY_UNSUPPORTED` before any request. There is no funding history and no testnet; a market whose funding interval cannot be proven to be 1 hour shows funding as unknown.
+
+### Variational (market data only — official API)
+
+Variational Omni is an RFQ venue: its single market maker (the OLP) quotes every trade, so there is no order book. perp-cli reads its **official**, documented read-only API (one `GET /metadata/v2/stats` call for every market, shared for 5 s; venue limit 10 requests / 10 s per IP). Variational has no public trading API yet.
+
+```bash
+perp -e variational market list | prices | info <SYM>   # perps by base (BTC), swaps keep the suffix (XAU-SWAP)
+perp -e variational market book BTC                      # the OLP's indicative RFQ quotes at fixed sizes — not an order book
+perp -e variational market funding BTC                   # current terms: per interval (1h / 4h / 8h per market), hourly, APR
+perp arb scan --rates --include-unverified               # Variational funding rows, display only
+perp health                                              # probed as an official venue
+```
+
+- **Funding is unverified:** the published rate is a moving prediction for the next payment and cannot be checked against settled payments (no public account API), so it is shown only with `--include-unverified` — never ranked, traded or saved to funding history. There is no funding history endpoint.
+- **Symbols:** TradFi perps (equities, ETFs, commodities) are classified explicitly; `US500-PERP` is the SPDR S&P 500 ETF (compared as `SPY`); pre-IPO markets, swaps, `SPX` (SPX6900) and `QNT` (Quant) are never matched across venues. No index price, tick, lot, leverage or base-unit open interest is published (shown as `-` / null).
+- **Refused** (`CAPABILITY_UNSUPPORTED`, before any request — also under `--dry-run`): every trade / account / portfolio / funds / agent / builder / strategy / arb exec command and every MCP account or trading tool. No testnet, no WebSocket.
+
+### GRVT (market data only — official API)
+
+GRVT is a hybrid perps exchange (off-chain matching, USDT collateral). perp-cli reads its **official**, keyless Market Data API (`POST https://market-data.grvt.io/full/v1/…`; testnet `-n testnet`). In this version GRVT is read-only; trading is planned for a later release.
+
+```bash
+perp -e grvt market list | prices | info <SYM>   # base tickers (BTC, KPEPE, XAU, AAPL); BTC_USDT_Perp also accepted
+perp -e grvt market book BTC                      # order book (10 / 50 / 100 / 500 levels served)
+perp -e grvt market funding BTC                   # settled funding history (per 4h / 8h interval)
+perp -e grvt market trades | kline BTC …          # public tape / candles
+perp arb scan --rates --include-unverified        # GRVT funding rows, display only
+perp health                                       # probed as an official venue
+```
+
+- **Funding is unverified:** the interval is per market (4h or 8h); market rows carry GRVT's indicative rate for the running interval (`fundingRateKind: "predicted"`), converted from percent to a fraction per interval. It has not been checked against settled payments, so it is shown only with `--include-unverified` — never ranked or traded.
+- **Symbols:** crypto by ticker; equities / ETFs by ticker from a reviewed list; XAU / XAG / CL / BZ → GOLD / SILVER / WTI / Brent; pre-IPO markets (OPENAI, ANTHROPIC, SPACEX) and ambiguous tickers are never matched across venues. No lot step is published (`stepSize` null); max leverage comes from GRVT's margin rules (`market list|prices|info`, cached up to 6 h — `leverageAsOf`).
+- **Requests:** GRVT has no bulk ticker, so a full market read is one ticker per market (~185 requests, ~5 s), reused for 15 s; documented limits (1500 / min for tickers, 500 / min otherwise) are enforced by the venue limiter.
+- **Refused** (`CAPABILITY_UNSUPPORTED`, "GRVT is read-only (market data) in this version; trading is planned for a later release", before any request — also under `--dry-run`): every trade / account / portfolio / funds / agent / builder / strategy / arb exec command, `setup --venues grvt`, and every MCP account or trading tool. No `perp-cli/ws` codec (GRVT streams are per instrument, capped below its market count).
+
+### Extended (market data only — official API)
+
+Extended (formerly X10) is a perps order book on Starknet (USD collateral) listing crypto and RWA markets (equities, ETFs, indices, commodities, FX). perp-cli reads its **official**, keyless public API (`https://api.starknet.extended.exchange/api/v1`; testnet Sepolia `-n testnet`). In this version Extended is read-only; trading is planned for a later release.
+
+```bash
+perp -e extended market list | prices | info <SYM>   # base tickers (BTC, TSLA, SPX500M); wire names (TSLA_24_5-USD) also accepted
+perp -e extended market book TSLA                     # order book (RFQ markets: the indicative book)
+perp -e extended market funding ETH                   # applied hourly funding prints
+perp -e extended market trades | kline BTC …          # public tape / candles
+perp arb scan --rates --include-unverified            # Extended funding rows, display only
+perp health                                           # probed as an official venue
+```
+
+- **Funding is unverified:** applied once per hour, a fraction per hour rounded to 6 decimals. Market rows carry the current hour's accruing rate (`fundingRateKind: "accruing"`); `market funding` shows the applied prints. It has not been checked against an account's funding payments, and `_24_5` equities print 0 while their underlying is closed, so it is shown only with `--include-unverified` — never ranked or traded.
+- **Symbols:** the asset name without the `_24_5` suffix (`TSLA_24_5-USD` → `TSLA`); `market list` shows an asset-class column. Crypto by ticker; equities / ETFs by ticker; XAU / XAG / WTI / XBR → GOLD / SILVER / WTI / Brent, SPX500M / TECH100M → SPX / NDX. Pre-IPO markets, RWA tickers that are crypto tickers elsewhere (PURR, QNT, BB, ON, ADI, BOT), XIAOMI and the crypto `SPX` (SPX6900) are never matched across venues.
+- **Refused** (`CAPABILITY_UNSUPPORTED`, "Extended is read-only (market data) in this version; trading is planned for a later release", before any request — also under `--dry-run`): every trade / account / portfolio / funds / agent / builder / strategy / arb exec command, `setup --venues extended`, and every MCP account or trading tool. No `perp-cli/ws` codec (Extended streams are one socket per stream URL, with no subscribe frame).
+
+### Options market data — Derive (read-only)
+
+Derive (derive.xyz) options through its official public API — keyless; no orders, no account, no signing (trading in a later release). Derive is not a perp venue: `-e derive` works only with `perp options`.
+
+```bash
+perp --json -e derive options underlyings
+perp --json -e derive options expiries ETH
+perp --json -e derive options chain ETH --expiry 2026-12-25 --strikes 10   # bid/ask, mark, IV, greeks, OI per strike
+perp --json -e derive options quote ETH-20261225-3500-P
+```
 
 ### Spot trading
 
@@ -233,6 +367,9 @@ 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 |
@@ -326,11 +463,9 @@ 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
@@ -401,7 +536,7 @@ Global flags: `--json`, `--fields <f>`, `--ndjson`, `--dry-run`, `--dex <name>`
 
 [![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.
+perp-cli includes a full-featured MCP server (29 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.
 
@@ -427,9 +562,13 @@ For trading and account data, run `perp setup` first: the MCP server reads the s
 }
 ```
 
-**Read-only tools (no keys):** `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `arb_scan`, `health_check`
+**Read-only tools (no keys):** `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `get_outcome_markets`, `get_outcome_view`, `get_outcome_book`, `get_option_expiries`, `get_option_chain`, `get_option_quote` (Derive options), `pacifica_print_products`, `pacifica_print_quote`, `pacifica_print_positions`, `pacifica_vaults` (Pacifica Print / vaults; writes are CLI-only), `arb_scan`, `health_check`
+
+**Advisor tools (no keys):** `suggest_command`, `explain_command`
+
+**Account & trading tools (keys required):** `get_balance`, `get_positions`, `get_open_orders`, `get_outcome_positions`, `portfolio`, `trade_preview`, `trade_execute`, `trade_close`, `get_funding_analysis`, `get_pnl_analysis`, `get_arb_compare`
 
-**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`
+- `get_markets` / `get_orderbook` add `meta.apiStatus` (`"unofficial"` + `apiNote` for TxFlow); `get_prices` lists `meta.unofficialApiVenues`; `health_check` rows carry `apiStatus`. Account / trading tools refuse TxFlow with `CAPABILITY_UNSUPPORTED`; `trade_preview` / `trade_execute` / `trade_close` refuse RISEx (read-only in 0.15.0) before any credential is read.
 
 **Resources:** `market://prices`, `market://funding-rates`, `perp://schema`
 

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

@@ -1,4 +1,4 @@
-import type { AgentMeta, AgentSource, AnyAgentMeta, ArcusAgentMeta, OndoAgentMeta, QfexAgentMeta } from "../settings.js";
+import type { AgentMeta, AgentSource, AnyAgentMeta, ArcusAgentMeta, OndoAgentMeta, QfexAgentMeta, RisexAgentMeta } from "../settings.js";
 import type { Network } from "../exchanges/venue-types.js";
 /**
  * Attempt to acquire the lockfile for an exchange's agent-approve operation.
@@ -56,6 +56,7 @@ type VenueAgentMap = {
     ondo: OndoAgentMeta;
     arcus: ArcusAgentMeta;
     qfex: QfexAgentMeta;
+    risex: RisexAgentMeta;
 };
 /** Named agent, or the only/first registered one when agentName is omitted. */
 export declare function getVenueAgent<V extends keyof VenueAgentMap>(venue: V, agentName?: string): VenueAgentMap[V] | null;
@@ -65,6 +66,6 @@ export declare function setVenueAgent<V extends keyof VenueAgentMap>(venue: V, m
 export declare function deleteVenueAgent(venue: keyof VenueAgentMap, agentName: string): boolean;
 export declare function listVenueAgents(): Array<{
     exchange: keyof VenueAgentMap;
-    meta: OndoAgentMeta | ArcusAgentMeta | QfexAgentMeta;
+    meta: OndoAgentMeta | ArcusAgentMeta | QfexAgentMeta | RisexAgentMeta;
 }>;
 export {};

package/dist/agent-wallet/store.js

@@ -91,7 +91,7 @@ function isPidAlive(pid) {
  * agentName is omitted.
  */
 /** Venues whose agents use a non-legacy meta shape (see getVenueAgent). */
-const NON_LEGACY_AGENT_VENUES = new Set(["ondo", "arcus", "qfex"]);
+const NON_LEGACY_AGENT_VENUES = new Set(["ondo", "arcus", "qfex", "risex"]);
 function assertLegacyAgentVenue(exchange) {
     if (NON_LEGACY_AGENT_VENUES.has(exchange)) {
         throw new PerpError("INVALID_PARAMS", `${exchange} agents use a venue-specific meta; call getVenueAgent("${exchange}")`);
@@ -294,7 +294,7 @@ export function deleteVenueAgent(venue, agentName) {
 export function listVenueAgents() {
     const settings = loadSettings();
     const out = [];
-    for (const v of ["ondo", "arcus", "qfex"]) {
+    for (const v of ["ondo", "arcus", "qfex", "risex"]) {
         const m = settings.agents?.[v];
         if (m)
             for (const meta of Object.values(m))

package/dist/api/public/hyperliquid.js

@@ -22,6 +22,8 @@ export function fetchHyperliquidMeta() {
         const ctxs = (json[1] ?? []);
         const out = [];
         universe.forEach((asset, i) => {
+            if (asset.isDelisted === true)
+                return; // delisted: zeroed funding / mark history, not a market
             const ctx = (ctxs[i] ?? {});
             const symbol = String(asset.name ?? "");
             const funding = Number(ctx.funding);
@@ -49,6 +51,8 @@ export function parseHyperliquidMetaRaw(raw) {
     const ctxs = (raw[1] ?? []);
     const assets = (universe?.universe ?? []);
     assets.forEach((a, i) => {
+        if (a.isDelisted === true)
+            return; // delisted: not a market (zeroed funding)
         const ctx = (ctxs[i] ?? {});
         const sym = String(a.name ?? "");
         if (!sym)

package/dist/api/public/pacifica.js

@@ -1,17 +1,84 @@
-import { PACIFICA_API_URL, sharedApiNetwork } from "./urls.js";
+import { PACIFICA_API_URL, PACIFICA_INFO_URL, sharedApiNetwork } from "./urls.js";
+import { PerpError } from "../../errors.js";
+import { isPacificaPerpetual } from "../../ws/pacifica-instrument.js";
 import { assertOk } from "./_http.js";
 import { withCache, TTL_MARKET } from "../../cache.js";
+import { getNetworkConfig } from "../../pacifica/constants.js";
+import { PACIFICA_COST_STANDARD, PACIFICA_READ_NEED, pacificaRateLimiter } from "../../pacifica/rate-limit.js";
 // ── Fetchers ──
+const publicRate = () => pacificaRateLimiter(getNetworkConfig(sharedApiNetwork()).restUrl, undefined, "unsigned");
+/**
+ * Unauthenticated GET through the shared Pacifica credit limiter (the IP quota the adapter's
+ * keyless client also spends): headers recorded, HTTP 429 → RATE_LIMITED. Never waits
+ * (maxWaitMs 0): arb / dashboard callers settle venues with allSettled, so a nearly spent quota
+ * fails this leg fast (RATE_LIMITED, nothing sent) instead of stalling the scan.
+ */
+async function pacificaPublicGet(url, what) {
+    const rate = publicRate();
+    const ticket = await rate.acquire(what, { ...PACIFICA_READ_NEED, maxWaitMs: 0 });
+    let res;
+    try {
+        res = await fetch(url);
+    }
+    finally {
+        ticket.release();
+    }
+    rate.observe(res);
+    if (res.status === 429)
+        throw rate.rateLimitedError(what, res, await res.text());
+    return res;
+}
+const INFO_REMEDIATION = "The Pacifica /info response shape changed; retry, and report it if it persists";
+/**
+ * Symbols of GET /info rows with instrument_type "perpetual". `/info/prices` also lists spot
+ * markets (SOL-USDC) — they must not reach arb / funding-arb as perps. A row without the field
+ * cannot be classified → EXCHANGE_ERROR (same rule as the adapter's getMarkets).
+ * Cached as a string[] (the file cache is JSON: a Set would come back as `{}`); the Set is built
+ * outside withCache.
+ */
+async function fetchPacificaPerpSymbols() {
+    const symbols = await withCache(`pub:pac:${sharedApiNetwork()}:perps:list`, TTL_MARKET, async () => {
+        const res = await pacificaPublicGet(PACIFICA_INFO_URL, "GET /info");
+        await assertOk(res, "Pacifica info");
+        const json = (await res.json());
+        if (json === null || typeof json !== "object" || !Array.isArray(json.data)) {
+            throw new PerpError("EXCHANGE_ERROR", "Pacifica GET /info has no data array", { exchange: "pacifica", remediation: INFO_REMEDIATION });
+        }
+        const out = [];
+        for (const m of json.data) {
+            if (m === null || typeof m !== "object" || Array.isArray(m)) {
+                throw new PerpError("EXCHANGE_ERROR", `Pacifica GET /info row is not an object: ${JSON.stringify(m)}`, { exchange: "pacifica", remediation: INFO_REMEDIATION });
+            }
+            const row = m;
+            if (typeof row.instrument_type !== "string") {
+                throw new PerpError("EXCHANGE_ERROR", `Pacifica /info row ${String(row.symbol)} has no instrument_type`, { exchange: "pacifica", remediation: INFO_REMEDIATION });
+            }
+            if (isPacificaPerpetual(row))
+                out.push(String(row.symbol));
+        }
+        return out;
+    });
+    if (!Array.isArray(symbols)) {
+        // A cache entry from before the string[] format (or a corrupt one) is not trusted.
+        throw new PerpError("EXCHANGE_ERROR", "Pacifica /info perp list cache entry is not a list", { exchange: "pacifica", remediation: INFO_REMEDIATION });
+    }
+    return new Set(symbols);
+}
+/** `/info/prices` envelope reduced to perp rows (`{ data }`, the shape parsePacificaRaw reads). */
+async function fetchPacificaPerpPrices() {
+    const [res, perps] = await Promise.all([pacificaPublicGet(PACIFICA_API_URL, "GET /info/prices"), fetchPacificaPerpSymbols()]);
+    await assertOk(res, "Pacifica prices");
+    const json = await res.json();
+    const data = json.data ?? json;
+    if (!Array.isArray(data))
+        return { data: [] };
+    return { data: data.filter((p) => perps.has(String(p.symbol))) };
+}
 export function fetchPacificaPrices() {
     // SSOT rule #2: error must propagate. Row-level skipping is applied for
     // missing/invalid mark or funding so a 0 doesn't reach downstream paths.
-    return withCache(`pub:pac:${sharedApiNetwork()}:prices`, TTL_MARKET, async () => {
-        const res = await fetch(PACIFICA_API_URL);
-        await assertOk(res, "Pacifica prices");
-        const json = await res.json();
-        const data = json.data ?? json;
-        if (!Array.isArray(data))
-            return [];
+    return withCache(`pub:pac:${sharedApiNetwork()}:prices:perp`, TTL_MARKET, async () => {
+        const { data } = await fetchPacificaPerpPrices();
         const out = [];
         for (const p of data) {
             const symbol = String(p.symbol ?? "");
@@ -32,11 +99,8 @@ export function fetchPacificaPricesRaw() {
     // Callers should wrap with Promise.allSettled to keep multi-DEX comparisons
     // running when one DEX is down. Non-2xx responses are also rejected so a
     // 5xx JSON body cannot fulfill as if it were valid data.
-    return withCache(`pub:pac:${sharedApiNetwork()}:prices:raw`, TTL_MARKET, async () => {
-        const res = await fetch(PACIFICA_API_URL);
-        await assertOk(res, "Pacifica prices");
-        return res.json();
-    });
+    // Perp rows only (spot SOL-USDC dropped via /info instrument_type).
+    return withCache(`pub:pac:${sharedApiNetwork()}:prices:raw:perp`, TTL_MARKET, fetchPacificaPerpPrices);
 }
 export function parsePacificaRaw(raw) {
     const rates = new Map();
@@ -64,11 +128,17 @@ export function parsePacificaRaw(raw) {
 // ── Health check ──
 export async function pingPacifica() {
     const start = Date.now();
+    // A health probe asks the venue itself (never throttled locally — an exhausted quota shows as the
+    // venue's HTTP 429), but its cost and headers go through the shared limiter.
+    const rate = publicRate();
+    const ticket = rate.track(PACIFICA_COST_STANDARD);
     try {
         const res = await fetch(PACIFICA_API_URL);
+        ticket.settle(res);
         return { ok: res.ok, latencyMs: Date.now() - start, status: res.status };
     }
     catch {
+        ticket.release();
         return { ok: false, latencyMs: Date.now() - start, status: 0 };
     }
 }

package/dist/api/public/urls.d.ts

@@ -8,6 +8,8 @@
 type LegacyPublicVenue = "pacifica" | "hyperliquid" | "aster";
 export declare function legacyPublicBaseUrl(venue: LegacyPublicVenue, net: "mainnet" | "testnet"): string;
 export declare let PACIFICA_API_URL: string;
+/** GET /info (instrument_type: which `prices` rows are perps). */
+export declare let PACIFICA_INFO_URL: string;
 export declare let HYPERLIQUID_API_URL: string;
 export declare let LIGHTER_API_URL: string;
 /** Network selected by the CLI entry point (setSharedApiNetwork). */

package/dist/api/public/urls.js

@@ -35,6 +35,8 @@ const TESTNET_URLS = {
     lighter: "https://testnet.zklighter.elliot.ai",
 };
 export let PACIFICA_API_URL = MAINNET_URLS.pacifica;
+/** GET /info (instrument_type: which `prices` rows are perps). */
+export let PACIFICA_INFO_URL = `${PAC_MAINNET_REST}/info`;
 export let HYPERLIQUID_API_URL = MAINNET_URLS.hyperliquid;
 export let LIGHTER_API_URL = MAINNET_URLS.lighter;
 let _sharedNetwork = "mainnet";
@@ -50,6 +52,7 @@ export function setSharedApiNetwork(network) {
     _sharedNetwork = network;
     const urls = network === "testnet" ? TESTNET_URLS : MAINNET_URLS;
     PACIFICA_API_URL = urls.pacifica;
+    PACIFICA_INFO_URL = `${network === "testnet" ? PAC_TESTNET_REST : PAC_MAINNET_REST}/info`;
     HYPERLIQUID_API_URL = urls.hyperliquid;
     LIGHTER_API_URL = urls.lighter;
 }

package/dist/arb/utils.d.ts

@@ -3,8 +3,7 @@
  */
 /**
  * Settlement schedules per venue (UTC hours when settlement occurs), generated
- * from `VenueDefinition.settlementIntervalHours`, anchored at 00:00 UTC
- * (design §10.1, §10.13 #1). Venues whose interval is per-market (Aster)
+ * from `VenueDefinition.settlementIntervalHours`, anchored at 00:00 UTC. Venues whose interval is per-market (Aster)
  * have no entry — pass the market's interval to getLastSettlement().
  */
 export declare const SETTLEMENT_SCHEDULES: Record<string, number[]>;

package/dist/arb/utils.js

@@ -8,8 +8,7 @@ import { ensureVenuesRegistered } from "../exchanges/venues/index.js";
 ensureVenuesRegistered();
 /**
  * Settlement schedules per venue (UTC hours when settlement occurs), generated
- * from `VenueDefinition.settlementIntervalHours`, anchored at 00:00 UTC
- * (design §10.1, §10.13 #1). Venues whose interval is per-market (Aster)
+ * from `VenueDefinition.settlementIntervalHours`, anchored at 00:00 UTC. Venues whose interval is per-market (Aster)
  * have no entry — pass the market's interval to getLastSettlement().
  */
 export const SETTLEMENT_SCHEDULES = Object.fromEntries(listVenues()

package/dist/bot/apex/pulse.js

@@ -20,6 +20,9 @@ export function tierRank(tier) {
 }
 export function detectPulse(current, history) {
     const symbol = "unknown"; // caller sets the actual symbol
+    // Unknown OI → no pulse signal (the OI change cannot be computed).
+    if (current.openInterest === null)
+        return { symbol, tier: "NONE", confidence: 0, oiChange: 0, volumeRatio: 0 };
     const currentOi = parseFloat(current.openInterest);
     const currentVolume = current.volume24h;
     const past = history.get(symbol) ?? [];

package/dist/bot/apex/radar.js

@@ -20,7 +20,8 @@ function scoreStructure(snapshot) {
     else if (vol > 1_000_000)
         score += 15;
     // OI component (0-50): higher open interest = more conviction
-    const oi = parseFloat(snapshot.openInterest);
+    // null (unknown) → no OI score, the same as below every threshold — never a parsed fake 0.
+    const oi = snapshot.openInterest === null ? NaN : parseFloat(snapshot.openInterest);
     if (oi > 50_000_000)
         score += 50;
     else if (oi > 20_000_000)

package/dist/bot/engine.d.ts

@@ -1,7 +1,7 @@
 import type { ExchangeAdapter } from "../exchanges/index.js";
 import { filledOf } from "./fill-size.js";
 import type { BotConfig } from "./config.js";
-import type { StrategyAction } from "./strategy-types.js";
+import type { StrategyAction, EnrichedSnapshot } from "./strategy-types.js";
 import { type QuoteRules } from "./quote-rules.js";
 import "./strategies/grid-strategy.js";
 import "./strategies/dca-strategy.js";
@@ -87,6 +87,15 @@ export declare function executeActions(adapter: ExchangeAdapter, symbol: string,
     filled: number;
 }>;
 export { filledOf };
+/**
+ * The tick's market snapshot. `unknown` names a failed orderbook / klines read (null = both
+ * read): the empty arrays in `snapshot` then are NOT data — the engine skips the tick of a
+ * strategy that reads them (MARKET_DATA_STRATEGIES).
+ */
+export declare function getEnrichedSnapshot(adapter: ExchangeAdapter, symbol: string, log: BotLog): Promise<{
+    snapshot: EnrichedSnapshot;
+    unknown: string | null;
+}>;
 /** TUI positions of one venue; a failed read → `error` set (shown "unavailable"), never an empty list. */
 export declare function fetchPositions(adapter: ExchangeAdapter, symbol: string, exchangeName?: string): Promise<{
     positions: import("./tui/index.js").Position[];