perp-cli 0.15.0 → 0.16.0

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:

package/skills/perp-cli/references/ws-library.md

@@ -4,10 +4,10 @@
 custom live dashboard, funding comparison or price/account feed for **hyperliquid** (native + HIP-3),
 **pacifica**, **lighter**, **lighter-rh**, **aster** and **arcus**, in the browser or in Node.
 
-> **Stability:** ships in **0.15.0** and is **@experimental** through 0.15.x — breaking changes only in a
+> **Stability:** shipped since **0.15.0** and **@experimental** through 0.15.x — breaking changes only in a
 > minor bump (CHANGELOG callouts); every event carries `schema: 1`. **@stable from 0.16.0** after consumer
-> sign-off. Planned for **0.15.1**: Aster user channels, Ondo / QFEX, `book` / `trades`, `perp stream`.
-> The `VenueId` type already includes `"ondo"` and `"qfex"`, but there are no codecs for them until 0.15.1.
+> sign-off. Planned, not yet available: Aster user channels, Ondo / QFEX, `book` / `trades`, `perp stream`.
+> The `VenueId` type already includes `"ondo"` and `"qfex"`, but there are no codecs for them yet.
 > **GRVT** (CLI venue, market data only) has no codec: its public WS has per-instrument selectors only (no
 > all-markets stream) and a 150-stream cap below its 184 perpetuals, so `allMarkets` cannot be served.
 > **Extended** (CLI venue `extended`, market data only) has no codec: its public streams are one socket
@@ -26,7 +26,7 @@ Two packages, **the same code and API** (built from one source):
 
 | Package | Install | When |
 |---|---|---|
-| **`@hypurrquant/perp-ws`** (recommended for integrators) | `npm install @hypurrquant/perp-ws` (+ `ws` for the Node entry) | apps, dashboards, bots — **no dependencies** (~100 KB ESM) |
+| **`@hypurrquant/perp-ws`** (recommended for integrators) | `npm install @hypurrquant/perp-ws` (+ `ws` for the Node entry) | apps, dashboards, bots — **no dependencies** (~170 KB ESM, ~41 KB gzip; 0.16.0 build) |
 | `perp-cli/ws` | `npm install perp-cli` | perp-cli is already installed (the CLI pulls ~140 MB of CLI deps) |
 
 | Runtime | `@hypurrquant/perp-ws` | `perp-cli` | Transport |
@@ -76,7 +76,7 @@ page's job, like a bundler's resolver):
 
 Serve the page and `node_modules` from the same static server (any origin works: the venues do not check
 Origin and their REST CORS is `*`). Do the same with a CDN that serves npm files (e.g.
-`https://cdn.jsdelivr.net/npm/@hypurrquant/perp-ws@0.15.0/dist/index.js`). The `/node` entry is
+`https://cdn.jsdelivr.net/npm/@hypurrquant/perp-ws@<version>/dist/index.js`). The `/node` entry is
 Node-only (it loads `ws`); never map it in a browser.
 
 ## 2. Minimal examples
@@ -123,7 +123,8 @@ declare function show(venue: string, text: string): void; // your UI: one status
 
 const streams: VenueStream[] = [hyperliquid, pacifica, lighter, aster, arcus].map((c) => createVenueStream(c));
 for (const stream of streams) {
-  // canonicals: "BTC" → hyperliquid/pacifica/lighter BTC, aster BTCUSDT + BTCUSD1, arcus BTC-USD.
+  // canonicals: "BTC" → hyperliquid/pacifica/lighter BTC, aster BTCUSDT, arcus BTC-USD (Aster's
+  // BTCUSD1 / BTCU listings are canonical null — only the USDT listing is matchable, as in the CLI).
   // (symbols would need each venue's directory symbols; ["BTC"] rejects on aster and arcus.)
   // A canonical this venue does not list (e.g. SOL somewhere) is skipped with a non-fatal warning;
   // ready rejects only when the venue lists none of them.
@@ -172,10 +173,12 @@ await Promise.all(streams.map((s) => s.close()));
 - `subscribe(target)`:
   - `{ kind: "allMarkets", canonicals? | symbols? }` → `MarketUpdate` for every market, or a subset:
     **`canonicals`** (recommended across venues) selects every directory market whose `canonical` matches
-    — `["BTC"]` is `BTC` on hyperliquid / pacifica / lighter / lighter-rh (USDG), `BTCUSDT` + `BTCUSD1` on
+    — `["BTC"]` is `BTC` on hyperliquid / pacifica / lighter / lighter-rh (USDG), `BTCUSDT` on
     aster and `BTC-USD` on arcus; HIP-3 markets are `"<dex>:<BASE>"` (`"xyz:TSLA"`, with `hip3Dexes`) and
     `"BTC"` never pulls them in. Canonicals come from `opts.canonicalize` (default: USD-like quotes
-    collapse) — see `MarketDirectoryEntry.canonical` in `stream.markets()`. Canonicals the venue does
+    collapse; an ambiguous ticker — SPX6900 on Hyperliquid / Aster / Lighter / Pacifica, Pacifica BP /
+    CHIP, Lighter BB / BOT / WEN / QNT, an unclassified Lighter RH market — and a non-USDT Aster listing
+    are null, never grouped: the CLI's rule) — see `MarketDirectoryEntry.canonical` in `stream.markets()`. Canonicals the venue does
     not list are **skipped and reported once** as a non-fatal control
     `{ type: "error", code: "SYMBOL_NOT_FOUND", fatal: false, details: { missing: string[], suggestions:
     Record<string, string[]> } }` (suggestions e.g. `"xyz:TSLA"` for `"TSLA"`; the others are subscribed and
@@ -183,7 +186,7 @@ await Promise.all(streams.map((s) => s.close()));
     **`symbols`** are this venue's exact directory symbols. Pass **one or the other** — both together
     reject `INVALID_PARAMS`. Same wire subscription and budget either way (filtering is client-side);
   - `{ kind: "market", symbol, channels: ["market" | "bbo"] }`. `"book"` and `"trades"` are already in
-    the types but **reject with `CAPABILITY_UNSUPPORTED` until 0.15.1** — don't ship UI that needs them.
+    the types but **reject with `CAPABILITY_UNSUPPORTED`** (planned, not yet available) — don't ship UI that needs them.
     Any other channel name (e.g. `"ticker"`) or an empty `channels` rejects with `INVALID_PARAMS`;
   - `{ kind: "user", channels: ["account" | "positions" | "orders" | "fills"] }` (needs `credentials`).
 - **`symbols` / `symbol` mean the venue's directory symbols, case-sensitive** — not canonical names. `BTC` is `"BTC"` on
@@ -211,7 +214,9 @@ await Promise.all(streams.map((s) => s.close()));
   `connecting` / `reconnecting`: it stays `live` with
   `sockets` = open sockets and `pending` = sockets still opening — the channels on those are not ready
   yet (their `ready` resolves when they open). `pending` is present only on multi-socket streams.
-- `closed` is terminal: a later `subscribe` rejects with the close reason. A handshake failure before
+- `closed` is terminal: a later `subscribe` rejects with the close reason (e.g. the code that exhausted
+  the reconnects). After your own `close()` the reason is `CLIENT_CLOSE`, which is not an error code: the
+  rejection is `INVALID_PARAMS` "stream is closed" with `details.closeReason: "CLIENT_CLOSE"`. A handshake failure before
   open = `EXCHANGE_UNREACHABLE` ("network, venue outage, or Origin/CORS block").
 - Ack timeout: no acknowledgement and no data within the channel's stale threshold → a **pending**
   subscription fails with `WS_PROTOCOL_ERROR`.
@@ -232,9 +237,17 @@ funding{ rate, rateKind, rateSource, rateIntervalHours, settlementIntervalHours,
 nextFundingTime, predictedRate, marketClosed }, openInterest{ value, unit: "base"|"usd"|null, sides },
 volume24hNotional, venueTs, recvTs, source, changed[], asOf{}`.
 
+- **Aster `volume24hNotional` can stay `null` for minutes after subscribing:** the venue's `!ticker@arr`
+  pushes only the tickers that changed, so a quiet market's first ticker (and its 24 h notional) arrives
+  late. `null` there means "not received yet", not "no volume" — a volume filter must not treat it as 0
+  (see the example in §5, which keeps such legs out explicitly and says so).
+
 Funding:
 - `rate` is **raw per `rateIntervalHours`** — never pre-annualized. Use `toHourly(rate, h)` to compare and
   `toApr(rate, h)` only for display (both return `null` for `null` input).
+- **Units:** `toHourly` and `toApr` return **fractions** (`toApr` 0.1095 = 10.95 % a year, simple ×24×365).
+  The CLI's `annualizedPct` (`perp --json arb scan --rates`, MCP `get_funding_rates`) is the same figure in
+  **percent** (10.95). Multiply `toApr` by 100 before comparing it with `annualizedPct` or printing a "%".
 - `rateKind`: `"lastSettled"` (the last payment), `"accruing"` (the current period so far, the "if it
   settled now" rate), `"predicted"` (the venue's estimate of the next payment). `predictedRate` is always
   kind `"predicted"`.
@@ -243,7 +256,7 @@ Funding:
 |---|---|---|---|---|---|
 | hyperliquid | accruing | null | 1 h | base, one side | bid/ask/last null → `bbo` channel |
 | pacifica | lastSettled | next_funding | 1 h | base, `sides` null | bid/ask/last/nextFundingTime null |
-| lighter / lighter-rh | lastSettled | current_funding_rate | 1 h | **usd** | wire values are percent/h, emitted as fractions/h |
+| lighter / lighter-rh | lastSettled | current_funding_rate | 1 h | **usd**, one side (inferred, not documented by the venue) | wire values are percent/h, emitted as fractions/h; REST `market info` OI is the same side in base units — convert before comparing; inactive / frozen markets are not streamed (same set as `market list`) |
 | aster | accruing | null | per market (`rest:/fapi/v3/fundingInfo`, null if missing) | null | all quotes (USDT, USD1, …) with `quote` set |
 | arcus | lastSettled | nextFundingRate | 1 h | base, one side | bid/ask null → `bbo` channel |
 
@@ -286,12 +299,12 @@ Options and defaults:
   are forward-looking estimates of the coming payment, so the row is usable for ranking; care when you
   need exact like-for-like numbers (e.g. P&L attribution, or an accruing rate early in its period that
   can still move a lot) — then use `kind: "accruing"` or `"predicted"` and accept fewer legs.
-- **Several legs per venue:** one venue can contribute more than one leg to a row. Aster lists BTC as
-  `BTCUSDT` (quote USDT) and `BTCUSD1` (quote USD1); both canonicalize to `"BTC"`. Pick one per venue
-  before ranking — by `quote`, or by the most liquid market (below) — or pass a `canonicalize` that
-  returns `null` for the quotes you don't want.
+- **One leg per venue by default:** Aster lists BTC as `BTCUSDT` (quote USDT) and `BTCUSD1` (quote
+  USD1); the default canonicalization keeps only the USDT listing matchable and gives every other
+  quote `canonical: null`, as the CLI does. A custom `canonicalize` that
+  returns a key for both brings back several legs per venue — pick one before ranking.
 - **`fundingVerified`** (per leg): the CLI's verdict that the venue's funding unit and which published
-  rate actually settles were confirmed against its funding payments. All six venues in 0.15.0 are
+  rate actually settles were confirmed against its funding payments. All six WS venues are
   `true`; a `false` leg (a future venue) is indicative only — the CLI keeps such venues out of funding
   comparison and refuses them as funding-arb legs, so do the same.
 - **Filter illiquid outliers before ranking spreads.** Tiny or newly listed markets often show extreme
@@ -316,13 +329,19 @@ for (const s of streams) {
 }
 
 const MIN_NOTIONAL = 1_000_000;
-/** One leg per venue: the most liquid market that passes the filter (null volume = unknown → skipped). */
+/**
+ * One leg per venue: the most liquid market that passes the filter. A leg whose 24 h notional is not
+ * known yet (Aster sends a ticker only when it changes — minutes on quiet markets) is skipped, never
+ * read as 0; `unknownVolume` counts them so a dashboard can show "N legs waiting for volume".
+ */
+let unknownVolume = 0;
 function pickLegs(row: FundingRow): FundingLeg[] {
   const best = new Map<string, { leg: FundingLeg; vol: number }>();
   for (const leg of row.legs) {
     if (leg.rate === null || leg.stale || !leg.fundingVerified) continue;
     const vol = notional.get(`${leg.venue}|${leg.symbol}`);
-    if (vol === undefined || vol < MIN_NOTIONAL) continue;
+    if (vol === undefined) { unknownVolume++; continue; } // not received yet — unknown, not 0
+    if (vol < MIN_NOTIONAL) continue;
     const cur = best.get(leg.venue);
     if (cur === undefined || vol > cur.vol) best.set(leg.venue, { leg, vol });
   }
@@ -397,18 +416,28 @@ sub.on((e) => {
 - **The library never holds keys.** `CredentialProvider` is async callbacks: `user()` (the account
   identity), `authToken({ purpose, maxTtlSec })` (Lighter `account_all_orders`; re-called at 80 % of the
   TTL with backoff retries; a read-only `ro:` token is recommended in browsers), `hmacSha256` /
-  `signTypedData` (reserved for 0.15.1 venues). Tokens handed in are redacted from every error, log and
+  `signTypedData` (reserved for planned venues). Tokens handed in are redacted from every error, log and
   raw excerpt.
 - `allowInPageSecrets: true` is required for venues whose auth needs a signing secret in the page
-  (Aster / Ondo / QFEX, 0.15.1). Without it they reject `CAPABILITY_UNSUPPORTED` in a browser.
+  (Aster / Ondo / QFEX — planned, not yet available). Without it they reject `CAPABILITY_UNSUPPORTED` in a browser.
 - `UserRef` per venue: hyperliquid `{ address }` (no auth), pacifica `{ account }` (Solana address, no
   auth), lighter / lighter-rh `{ accountIndex }`, arcus `{ address, subaccount }` (`null` = account 0, no auth).
-- **KNOWN GAP (0.15.0): Aster user channels are not implemented** — `kind: "user"` on aster rejects
-  `CAPABILITY_UNSUPPORTED` (no parity; 0.15.1).
+- **Any account, keyless:** the Hyperliquid (`{ address }`) and Pacifica (`{ account }`) user channels
+  need no auth, so `user()` may return ANY public address — a live positions / fills feed of someone
+  else's account. The REST counterpart (one snapshot, also Lighter / Lighter RH / RISEx) is
+  `perp --json -e <venue> account positions --address <addr>` / MCP `get_positions_by_address`.
+- **KNOWN GAP: Aster user channels are not implemented** — `kind: "user"` on aster rejects
+  `CAPABILITY_UNSUPPORTED` (no parity; planned, not yet available).
 
 Events:
 - `account` — `equity, available, marginUsed, unrealizedPnl` (+ `dex` on hyperliquid, one per perp dex);
-  `source: "snapshot"` when the frame was a full snapshot.
+  `source: "snapshot"` when the frame was a full snapshot. `unrealizedPnl` per venue:
+  hyperliquid = the exact sum of that dex's position `unrealizedPnl` in the same `clearinghouseState`
+  frame (`"0"` with no position; `null` if a position lacks it — the frame has no account-level field);
+  pacifica = `null` (`account_info` publishes none, and the position stream carries no unrealized PnL
+  either); lighter / lighter-rh = `null` on `account` (`user_stats` publishes none) — per position it is
+  `PositionRow.unrealizedPnl` (`unrealized_pnl` on the positions channel); arcus = `null` on `account`,
+  per position on `PositionRow`.
 - `positions` / `orders` — always the **full current set** (snapshot + merged deltas). Pacifica
   `account_positions` snapshots older than the last applied one (envelope `li`) are dropped.
   `orders.complete` = every part of the set came from a venue snapshot. **Pacifica sends no order
@@ -436,7 +465,9 @@ Mark price in `PositionRow` is null except on Arcus — join the `MarketUpdate`
 
 `StreamControl { type: "error", code, message, remediation, raw (redacted ≤ 200 chars), fatal }` — always
 check `fatal`: a fatal error ended that subscription, a non-fatal one is informational (it keeps running);
-`ready` rejects with a `WsError` whose `structured = { code, message, status, retryable, remediation? }`.
+`ready` rejects with a `WsError` whose `structured = { code, message, status, retryable, remediation? }`;
+`err.code` and `err.remediation` (null when none) mirror `structured`, so one handler reads `code` the same
+way on error events (`e.code`) and on rejections (`err.code`).
 
 Where an error surfaces:
 - **Thrown synchronously** (`WsError`, `INVALID_PARAMS`) — bad options, before anything starts:

package/skills/perp-cli/scripts/arb-monitor.sh

@@ -6,16 +6,17 @@
 
 set -euo pipefail
 
-# Auto-detect perp command (supports npx fallback for agents without install permissions)
-if command -v perp &>/dev/null; then
-  PERP="perp"
-else
-  PERP="npx -y perp-cli@latest"
+# perp must be installed (no npx / auto-install path: the user decides what gets installed).
+if ! command -v perp &>/dev/null; then
+  echo "perp not found — ask the user to install perp-cli >= 0.16.0" >&2
+  echo '{"ok":false,"error":{"code":"PERP_NOT_FOUND","message":"perp not found — ask the user to install perp-cli >= 0.16.0"}}'
+  exit 1
 fi
+PERP="perp"
 
 # perp exits 1 on {"ok":false} and prints exactly one JSON document: capture it as-is
-# (never append a fallback document); empty output (crash / not installed) → {"ok":false}.
-pj() { local out; out=$($PERP "$@" 2>/dev/null) || true; if [[ -n "$out" ]]; then printf '%s\n' "$out"; else echo '{"ok":false}'; fi; }
+# (never append a fallback document); empty output (crash) → an explicit NO_OUTPUT error document.
+pj() { local out; out=$($PERP "$@" 2>/dev/null) || true; if [[ -n "$out" ]]; then printf '%s\n' "$out"; else echo '{"ok":false,"error":{"code":"NO_OUTPUT","message":"perp printed nothing (crashed?)"}}'; fi; }
 isok() { jq -e '.ok == true' >/dev/null 2>&1 <<<"$1"; }
 
 JSON_MODE=false
@@ -30,13 +31,15 @@ done
 
 # 1. Get current arb status (already includes funding earned per period)
 ARB_STATUS=$(pj --json arb status)
+# A failed read is an error, never "no positions" (arb status fails as a whole when one
+# configured venue's read fails — check that venue: perp --json -e <venue> account positions).
 if ! isok "$ARB_STATUS"; then
   if $JSON_MODE; then
-    echo '{"ok":false,"error":"No arb positions or arb status unavailable"}'
+    jq -c '{ok:false, error:{code:.error.code, message:.error.message, source:"perp --json arb status"}}' <<<"$ARB_STATUS"
   else
-    echo "No open arb positions found."
+    echo "ERROR: arb status failed: $(jq -r '"\(.error.code): \(.error.message)"' <<<"$ARB_STATUS")" >&2
   fi
-  exit 0
+  exit 1
 fi
 
 # 2. Get current spreads (all modes)

package/skills/perp-cli/scripts/funding-analysis.sh

@@ -1,73 +1,103 @@
 #!/bin/bash
 # Funding rate analysis across all exchanges
-# Usage: ./funding-analysis.sh [--json] [--symbol ETH] [--top 10]
-# Fetches current + historical funding data for comparison
+# Usage: ./funding-analysis.sh [--json] [--symbol ETH] [--top 10] [--hours 24] [-n mainnet|testnet]
+# --symbol: cross-venue compare + each verified venue's SETTLED funding history
+#   (`-e <venue> market funding <SYM> -l <hours>`, averaged per venue). `arb scan --history` is only
+#   the locally recorded snapshots (written by earlier `arb scan --rates` runs) and is often empty.
+# Testnet funding / spreads are not meaningful — use mainnet (the default) for yield analysis.
 
 set -euo pipefail
 
-# Auto-detect perp command (supports npx fallback for agents without install permissions)
-if command -v perp &>/dev/null; then
-  PERP="perp"
-else
-  PERP="npx -y perp-cli@latest"
+# perp must be installed (no npx / auto-install path: the user decides what gets installed).
+if ! command -v perp &>/dev/null; then
+  echo "perp not found — ask the user to install perp-cli >= 0.16.0" >&2
+  echo '{"ok":false,"error":{"code":"PERP_NOT_FOUND","message":"perp not found — ask the user to install perp-cli >= 0.16.0"}}'
+  exit 1
 fi
+PERP="perp"
 
 # perp exits 1 on {"ok":false} and prints exactly one JSON document: capture it as-is
-# (never append a fallback document); empty output (crash / not installed) → {"ok":false}.
-pj() { local out; out=$($PERP "$@" 2>/dev/null) || true; if [[ -n "$out" ]]; then printf '%s\n' "$out"; else echo '{"ok":false}'; fi; }
+# (never append a fallback document); empty output (crash) → an explicit NO_OUTPUT error document.
+pj() { local out; out=$($PERP "$@" 2>/dev/null) || true; if [[ -n "$out" ]]; then printf '%s\n' "$out"; else echo '{"ok":false,"error":{"code":"NO_OUTPUT","message":"perp printed nothing (crashed?)"}}'; fi; }
 isok() { jq -e '.ok == true' >/dev/null 2>&1 <<<"$1"; }
 
 JSON_MODE=false
 SYMBOL=""
 TOP=10
+HOURS=24
+NETWORK="mainnet"
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --json) JSON_MODE=true; shift ;;
     --symbol) SYMBOL="$2"; shift 2 ;;
     --top) TOP="$2"; shift 2 ;;
-    *) shift ;;
+    --hours) HOURS="$2"; shift 2 ;;
+    -n|--network) NETWORK="$2"; shift 2 ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
   esac
 done
+PERP="perp -n $NETWORK"
+
+# Row label per scan mode (perp-perp rows: longExch/shortExch; spot-perp rows: spotExchanges/perpExchange/direction)
+ROW_JQ='if .mode == "spot-perp" then
+    "  \(.symbol) | spot-perp | net \(.netSpread)%/yr | \(.direction) spot:\(.spotExchanges | join("/")) perp:\(.perpExchange)"
+    + (if .direction == "long-spot-short-perp" then "" else "  [NOT executable with arb exec]" end)
+  else
+    "  \(.symbol) | perp-perp | net \(.netSpread)%/yr | long \(.longExch) / short \(.shortExch)"
+  end'
 
 if [[ -n "$SYMBOL" ]]; then
   # Single symbol detailed analysis
-  FUNDING=$(pj --json arb scan --history "$SYMBOL")
   COMPARE=$(pj --json arb scan --compare "$SYMBOL")
+  LOCAL_HISTORY=$(pj --json arb scan --history "$SYMBOL" --hours "$HOURS")
   SCAN=$(pj --json arb scan --mode perp-perp --min 0)
   SPOT_SCAN=$(pj --json arb scan --mode spot-perp --min 0)
 
+  # Settled funding history per verified venue of the compare (rows newest first; rate = fraction per intervalHours)
+  SETTLED="[]"
+  if isok "$COMPARE" && [[ "$(jq -r '.data.available' <<<"$COMPARE")" != "false" ]]; then
+    for VENUE in $(jq -r '.data.rates[] | select(.fundingVerified) | .exchange' <<<"$COMPARE"); do
+      H=$(pj --json -e "$VENUE" market funding "$SYMBOL" -l "$HOURS")
+      ROW=$(jq -c --arg v "$VENUE" '
+        if .ok then
+          { exchange: $v, rows: (.data | length),
+            avgHourlyRate: (if (.data | length) > 0 and all(.data[]; .rate != null and .intervalHours != null)
+                            then ([.data[] | ((.rate | tonumber) / .intervalHours)] | add / length) else null end) }
+          | .avgAnnualPct = (if .avgHourlyRate == null then null else .avgHourlyRate * 8760 * 100 end)
+        else { exchange: $v, error: .error.code, message: .error.message } end' <<<"$H")
+      SETTLED=$(jq -c --argjson r "$ROW" '. + [$r]' <<<"$SETTLED")
+    done
+  fi
+
   if $JSON_MODE; then
     cat <<EOF
 {
   "ok": true,
+  "network": "$NETWORK",
   "symbol": "$SYMBOL",
+  "hours": $HOURS,
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
-  "fundingHistory": $FUNDING,
   "compare": $COMPARE,
+  "settledHistory": $SETTLED,
+  "localSnapshotHistory": $LOCAL_HISTORY,
   "perpPerpArb": $SCAN,
   "spotPerpArb": $SPOT_SCAN
 }
 EOF
   else
-    echo "=== Funding Analysis: $SYMBOL ==="
+    echo "=== Funding Analysis: $SYMBOL ($NETWORK) ==="
     echo ""
     echo "--- Cross-Exchange Compare ---"
-    echo "$COMPARE" | jq -r '.data // empty' 2>/dev/null || echo "(unavailable)"
+    if isok "$COMPARE"; then jq -r '.data' <<<"$COMPARE"; else echo "  ERROR: $(jq -r '.error.code' <<<"$COMPARE")"; fi
     echo ""
-    echo "--- Funding History ---"
-    echo "$FUNDING" | jq -r '.data // empty' 2>/dev/null || echo "(unavailable)"
+    echo "--- Settled funding, last $HOURS rows per venue (avg annualized %) ---"
+    jq -r '.[] | if .error then "  \(.exchange): ERROR \(.error)" else "  \(.exchange): \(.rows) rows, avg \(.avgAnnualPct)%/yr" end' <<<"$SETTLED"
     echo ""
     echo "--- Perp-Perp Arb ---"
-    echo "$SCAN" | jq -r '
-      .data // [] | map(select(.symbol == "'"$SYMBOL"'")) | .[] |
-      "  \(.longExch // .longExchange)→\(.shortExch // .shortExchange): net \(.netSpread)% annual"
-    ' 2>/dev/null || echo "  (no opportunity)"
+    if isok "$SCAN"; then jq -r --arg s "$SYMBOL" ".data[] | select(.symbol == \$s) | $ROW_JQ" <<<"$SCAN"; else echo "  ERROR: $(jq -r '.error.code' <<<"$SCAN")"; fi
     echo ""
     echo "--- Spot+Perp Arb ---"
-    echo "$SPOT_SCAN" | jq -r '
-      .data // [] | map(select(.symbol == "'"$SYMBOL"'")) | .[] |
-      "  \(.direction) spot:\((.spotExchanges // []) | join("/"))→\(.perpExchange): net \(.netSpreadPct)% annual"
-    ' 2>/dev/null || echo "  (no opportunity)"
+    if isok "$SPOT_SCAN"; then jq -r --arg s "$SYMBOL" ".data[] | select(.symbol == \$s) | $ROW_JQ" <<<"$SPOT_SCAN"; else echo "  ERROR: $(jq -r '.error.code' <<<"$SPOT_SCAN")"; fi
   fi
 else
   # All symbols scan
@@ -78,6 +108,7 @@ else
     cat <<EOF
 {
   "ok": true,
+  "network": "$NETWORK",
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "topN": $TOP,
   "allOpportunities": $SCAN,
@@ -85,11 +116,8 @@ else
 }
 EOF
   else
-    echo "=== Funding Rate Overview (top $TOP) ==="
+    echo "=== Funding Rate Overview (top $TOP, $NETWORK) ==="
     echo ""
-    echo "$SCAN" | jq -r "
-      .data // [] | .[0:$TOP] | .[] |
-      \"  \(.symbol) | \(.mode // \"perp\") | net \(.netSpread // .netSpreadPct)%/yr | \(.longExch // (\"spot:\" + ((.spotExchanges // []) | join(\"/\"))))→\(.shortExch // .perpExchange)\"
-    " 2>/dev/null || echo "(no data)"
+    if isok "$SCAN"; then jq -r ".data[0:$TOP][] | $ROW_JQ" <<<"$SCAN"; else echo "  ERROR: $(jq -r '.error.code' <<<"$SCAN")"; fi
   fi
 fi

package/skills/perp-cli/scripts/preflight.sh

@@ -6,16 +6,17 @@
 
 set -euo pipefail
 
-# Auto-detect perp command (supports npx fallback for agents without install permissions)
-if command -v perp &>/dev/null; then
-  PERP="perp"
-else
-  PERP="npx -y perp-cli@latest"
+# perp must be installed (no npx / auto-install path: the user decides what gets installed).
+if ! command -v perp &>/dev/null; then
+  echo "perp not found — ask the user to install perp-cli >= 0.16.0" >&2
+  echo '{"ok":false,"error":{"code":"PERP_NOT_FOUND","message":"perp not found — ask the user to install perp-cli >= 0.16.0"}}'
+  exit 1
 fi
+PERP="perp"
 
 # perp exits 1 on {"ok":false} and prints exactly one JSON document: capture it as-is
-# (never append a fallback document); empty output (crash / not installed) → {"ok":false}.
-pj() { local out; out=$($PERP "$@" 2>/dev/null) || true; if [[ -n "$out" ]]; then printf '%s\n' "$out"; else echo '{"ok":false}'; fi; }
+# (never append a fallback document); empty output (crash) → an explicit NO_OUTPUT error document.
+pj() { local out; out=$($PERP "$@" 2>/dev/null) || true; if [[ -n "$out" ]]; then printf '%s\n' "$out"; else echo '{"ok":false,"error":{"code":"NO_OUTPUT","message":"perp printed nothing (crashed?)"}}'; fi; }
 isok() { jq -e '.ok == true' >/dev/null 2>&1 <<<"$1"; }
 
 JSON_MODE=false
@@ -30,28 +31,35 @@ add_check() {
   if [[ "$status" == "fail" ]]; then issues+=("$name: $detail"); fi
 }
 
-# 1. perp-cli installed and version check
-VERSION=$($PERP --version 2>/dev/null || echo "unknown")
-if [[ "$VERSION" != "unknown" ]]; then
-  add_check "install" "pass" "perp-cli $VERSION ($(command -v perp &>/dev/null && echo 'global' || echo 'npx'))"
+# 1. perp-cli version (must be >= 0.16.0)
+VERSION=$($PERP --version 2>/dev/null || true)
+MIN_VERSION="0.16.0"
+if [[ -z "$VERSION" ]]; then
+  add_check "install" "fail" "perp --version printed nothing — ask the user to (re)install perp-cli >= $MIN_VERSION"
+elif [[ "$(printf '%s\n%s\n' "$MIN_VERSION" "$VERSION" | sort -V | head -1)" != "$MIN_VERSION" ]]; then
+  add_check "install" "fail" "perp-cli $VERSION < $MIN_VERSION — ask the user to upgrade"
 else
-  add_check "install" "fail" "perp-cli not found — ask the user before installing (npm i -g perp-cli@latest) or use npx"
+  add_check "install" "pass" "perp-cli $VERSION"
 fi
 
-# 2. Wallet configured
+# 2. Wallet configured (with an OWS wallet, `exchanges: []` in wallet show is normal)
 WALLET_OUT=$(pj --json wallet show)
 if isok "$WALLET_OUT"; then
   add_check "wallet" "pass" "Wallet configured"
 else
-  add_check "wallet" "fail" "No wallet configured — run: perp wallet set <exchange>  (key via hidden prompt or stdin)"
+  add_check "wallet" "fail" "wallet show failed ($(jq -r '.error.code' <<<"$WALLET_OUT")) — the user registers a key: perp wallet set <exchange> (stdin / hidden prompt)"
 fi
 
-# 3. Exchange connectivity (proxy via unauthenticated market prices fetch)
-HEALTH_OUT=$(pj --json market prices)
-if isok "$HEALTH_OUT"; then
-  add_check "connectivity" "pass" "Exchange reachable"
+# 3. Venue connectivity: perp health (healthy = every OFFICIAL-API venue is up;
+#    allHealthy also counts unofficial APIs such as TxFlow)
+HEALTH_OUT=$(pj --json health)
+if ! isok "$HEALTH_OUT"; then
+  add_check "connectivity" "fail" "perp health failed ($(jq -r '.error.code' <<<"$HEALTH_OUT"))"
+elif [[ "$(jq -r '.data.healthy' <<<"$HEALTH_OUT")" == "true" ]]; then
+  add_check "connectivity" "pass" "All official venues reachable"
 else
-  add_check "connectivity" "warn" "Exchange unreachable"
+  DOWN=$(jq -r '[.data.exchanges[] | select(.status != "ok") | .exchange] | join(",")' <<<"$HEALTH_OUT")
+  add_check "connectivity" "warn" "Official venues down: $DOWN — do not use them until perp health shows them ok"
 fi
 
 # 4. Portfolio & balances