perp-cli 0.14.3 → 0.16.0

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

package/skills/perp-cli/scripts/spot-perp-scan.sh

@@ -1,56 +1,70 @@
 #!/bin/bash
-# Scan spot+perp funding rate arbitrage opportunities
-# Usage: ./spot-perp-scan.sh [--json] [--mode all|spot-perp|perp-perp] [--min 10]
-# Combines perp-perp and spot-perp scans with validation
+# Scan spot+perp (and perp-perp) funding rate arbitrage opportunities
+# Usage: ./spot-perp-scan.sh [--json] [--mode all|spot-perp|perp-perp] [--min 10] [-n mainnet|testnet] [--no-portfolio]
+# Combines the scan with balances (portfolio) and venue health (perp health).
+# --no-portfolio: skip the balance read (no wallet needed); the output says it was skipped.
+# Spot-perp rows: only direction == "long-spot-short-perp" is executable with `arb exec <SYM> spot:<venue> <perp>`.
+# 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
 MODE="all"
 MIN_SPREAD=10
+NETWORK="mainnet"
+WITH_PORTFOLIO=true
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --json) JSON_MODE=true; shift ;;
     --mode) MODE="$2"; shift 2 ;;
     --min) MIN_SPREAD="$2"; shift 2 ;;
-    *) shift ;;
+    -n|--network) NETWORK="$2"; shift 2 ;;
+    --no-portfolio) WITH_PORTFOLIO=false; shift ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
   esac
 done
+PERP="perp -n $NETWORK"
 
-# 1. Portfolio check (ensure we have balances)
-PORTFOLIO=$(pj --json portfolio)
-if ! isok "$PORTFOLIO"; then
-  if $JSON_MODE; then
-    echo '{"ok":false,"error":"Cannot fetch portfolio — check wallet setup"}'
-  else
-    echo "ERROR: Cannot fetch portfolio. Check wallet setup first."
+# 1. Portfolio (balances). Explicitly skipped with --no-portfolio; a failed read aborts.
+if $WITH_PORTFOLIO; then
+  PORTFOLIO=$(pj --json portfolio)
+  if ! isok "$PORTFOLIO"; then
+    if $JSON_MODE; then
+      jq -c '{ok:false, error:{code:.error.code, message:.error.message, source:"perp --json portfolio", remediation:"Check the wallet setup, or rerun with --no-portfolio to scan without balances"}}' <<<"$PORTFOLIO"
+    else
+      echo "ERROR: portfolio failed ($(jq -r '.error.code' <<<"$PORTFOLIO")). Check the wallet setup, or rerun with --no-portfolio." >&2
+    fi
+    exit 1
   fi
-  exit 1
+else
+  PORTFOLIO='{"skipped":true,"reason":"--no-portfolio"}'
 fi
 
 # 2. Run appropriate scan
 SCAN_RESULT=$(pj --json arb scan --mode "$MODE" --min "$MIN_SPREAD")
 
-# 3. Get exchange health for context (proxy via market prices fetch)
-HEALTH=$(pj --json market prices)
+# 3. Venue health (data.healthy = every official-API venue is up)
+HEALTH=$(pj --json health)
 
 if $JSON_MODE; then
   cat <<EOF
 {
   "ok": true,
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "network": "$NETWORK",
   "mode": "$MODE",
   "minSpread": $MIN_SPREAD,
   "portfolio": $PORTFOLIO,
@@ -60,29 +74,35 @@ if $JSON_MODE; then
 EOF
 else
   echo "=== Spot+Perp Arb Scanner ==="
-  echo "Mode: $MODE | Min spread: ${MIN_SPREAD}% annual"
+  echo "Network: $NETWORK | Mode: $MODE | Min spread: ${MIN_SPREAD}% annual"
   echo ""
 
-  # Show balances
   echo "--- Balances ---"
-  echo "$PORTFOLIO" | jq -r '
-    .data.exchanges // [] | .[] |
-    "  \(.name): equity $\(.perp.equity // "N/A")"
-  ' 2>/dev/null || echo "  (unable to parse)"
+  if $WITH_PORTFOLIO; then
+    jq -r '.data.exchanges[] | "  \(.name): equity $\(.perp.equity) available $\(.perp.available)"' <<<"$PORTFOLIO"
+  else
+    echo "  (skipped: --no-portfolio)"
+  fi
   echo ""
 
-  # Show opportunities
   echo "--- Opportunities ---"
-  echo "$SCAN_RESULT" | jq -r '
-    .data // [] | .[] |
-    "  \(.symbol) | \(.mode // "perp-perp") | net: \(.netSpread // .netSpreadPct)%/yr | \(.longExch // ("spot:" + ((.spotExchanges // []) | join("/"))))→\(.shortExch // .perpExchange)"
-  ' 2>/dev/null || echo "  (no opportunities or parse error)"
+  if isok "$SCAN_RESULT"; then
+    jq -r '.data[] |
+      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' <<<"$SCAN_RESULT"
+  else
+    echo "  ERROR: arb scan failed: $(jq -r '"\(.error.code): \(.error.message)"' <<<"$SCAN_RESULT")"
+  fi
 
-  # Show exchange health
   echo ""
-  echo "--- Exchange Health ---"
-  echo "$HEALTH" | jq -r '
-    .data // {} | to_entries[] |
-    "  \(.key): \(.value.status // .value // "unknown")"
-  ' 2>/dev/null || echo "  (unable to check)"
+  echo "--- Venue Health ---"
+  if isok "$HEALTH"; then
+    jq -r '"  healthy (official venues): \(.data.healthy)", (.data.exchanges[] | "  \(.exchange): \(.status)")' <<<"$HEALTH"
+  else
+    echo "  ERROR: perp health failed: $(jq -r '.error.code' <<<"$HEALTH")"
+  fi
 fi

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

@@ -3,20 +3,22 @@
 # Usage: ./validate-arb.sh <SYMBOL> <LONG_EX> <SHORT_EX> <SIZE_USD> [--leverage N]
 # Performs: price check, liquidity check, balance check, risk check, dry-run via 'arb exec'
 # Returns JSON validation report
-# NOTE: For spot+perp arb, pass spot:<exch> as LONG_EX (e.g. spot:hl).
+# NOTE: For spot+perp arb, pass spot:<exch> as LONG_EX (e.g. spot:hl) — only for a scan row with
+#       direction == "long-spot-short-perp" (arb exec spot: always buys spot + shorts the perp).
 
 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"; }
 
 SYM="${1:?Usage: validate-arb.sh <SYMBOL> <LONG_EX> <SHORT_EX> <SIZE_USD> [--leverage N]}"
@@ -42,24 +44,23 @@ add_result() {
   if [[ "$ok" == "false" ]]; then pass=false; fi
 }
 
-# Venue of the long leg (spot:<venue> → <venue>) for the per-venue reads below
+# Venue of the long leg (spot:<venue> → <venue>) for the per-venue reads below.
+# Aliases (hl, pac, lt, lrh, ast, …) are accepted everywhere, portfolio included.
 LONG_VENUE="${LONG_EX#spot:}"
-# portfolio -e accepts only full venue ids (no aliases)
-venue_id() {
-  case "$1" in
-    pac) echo pacifica ;; hl) echo hyperliquid ;; lt) echo lighter ;; lrh|rh) echo lighter-rh ;;
-    ast) echo aster ;; ondo-perps) echo ondo ;; qf) echo qfex ;; *) echo "$1" ;;
-  esac
-}
-
-# 1. Price comparison — both exchanges must report similar prices
-LONG_PRICE=$(pj --json -e "$LONG_VENUE" market mid "$SYM" | jq -r '.data.mid // "0"' 2>/dev/null || echo 0)
-SHORT_PRICE=$(pj --json -e "$SHORT_EX" market mid "$SYM" | jq -r '.data.mid // "0"' 2>/dev/null || echo 0)
-
-if [[ "$LONG_PRICE" == "0" || "$SHORT_PRICE" == "0" ]]; then
-  add_result "price" "false" "Cannot fetch price: long=$LONG_PRICE short=$SHORT_PRICE"
+SPOT_MODE=false
+[[ "$LONG_EX" == spot:* ]] && SPOT_MODE=true
+
+# 1. Price comparison — both exchanges must report similar prices.
+#    `market mid` reads the PERP book; there is no spot price read — in spot mode the long price
+#    is the spot venue's perp mid (arb exec itself compares the spot and perp books and refuses
+#    an empty book or a > 5% gap).
+LONG_MID=$(pj --json -e "$LONG_VENUE" market mid "$SYM")
+SHORT_MID=$(pj --json -e "$SHORT_EX" market mid "$SYM")
+if ! isok "$LONG_MID" || ! isok "$SHORT_MID"; then
+  add_result "price" "false" "Cannot fetch mid: long=$(jq -r '.error.code // .data.mid' <<<"$LONG_MID") short=$(jq -r '.error.code // .data.mid' <<<"$SHORT_MID")"
 else
-  # Check deviation
+  LONG_PRICE=$(jq -r '.data.mid' <<<"$LONG_MID")
+  SHORT_PRICE=$(jq -r '.data.mid' <<<"$SHORT_MID")
   DEVIATION=$(echo "$LONG_PRICE $SHORT_PRICE" | awk '{d=($1-$2)/$2*100; print (d<0?-d:d)}')
   if (( $(echo "$DEVIATION > 5" | bc -l) )); then
     add_result "price" "false" "Price deviation ${DEVIATION}% > 5% — possible wrong token"
@@ -68,21 +69,37 @@ else
   fi
 fi
 
-# 2. Balance check on both exchanges
-LONG_BAL=$(pj --json portfolio -e "$(venue_id "$LONG_VENUE")" | jq -r '.data.exchanges[0].perp.available // .data.exchanges[0].perp.equity // "0"' 2>/dev/null || echo 0)
-SHORT_BAL=$(pj --json portfolio -e "$(venue_id "$SHORT_EX")" | jq -r '.data.exchanges[0].perp.available // .data.exchanges[0].perp.equity // "0"' 2>/dev/null || echo 0)
-
-NEEDED=$(echo "$SIZE" | awk '{print $1}')
-if (( $(echo "$LONG_BAL < $NEEDED" | bc -l 2>/dev/null || echo 1) )); then
-  add_result "balance_long" "false" "$LONG_EX balance $LONG_BAL < needed $NEEDED"
-else
-  add_result "balance_long" "true" "$LONG_EX balance=$LONG_BAL"
-fi
-if (( $(echo "$SHORT_BAL < $NEEDED" | bc -l 2>/dev/null || echo 1) )); then
-  add_result "balance_short" "false" "$SHORT_EX balance $SHORT_BAL < needed $NEEDED"
+# 2. Balances. Perp legs: portfolio .perp.available only (missing / unreadable = fail, never 0 or equity).
+#    The comparison against the full SIZE is conservative (arb exec needs notional / leverage × buffer).
+perp_available() {
+  local out; out=$(pj --json portfolio -e "$1")
+  if ! isok "$out"; then echo "ERROR:$(jq -r '.error.code' <<<"$out")"; return; fi
+  jq -r '.data.exchanges[0].perp.available // "MISSING"' <<<"$out"
+}
+check_perp_balance() {
+  local name="$1" venue="$2" bal; bal=$(perp_available "$venue")
+  if [[ "$bal" == ERROR:* || "$bal" == "MISSING" ]]; then
+    add_result "$name" "false" "$venue perp available unreadable ($bal)"
+  elif (( $(echo "$bal < $SIZE" | bc -l) )); then
+    add_result "$name" "false" "$venue perp available $bal < $SIZE"
+  else
+    add_result "$name" "true" "$venue perp available=$bal"
+  fi
+}
+if $SPOT_MODE; then
+  # Spot leg: needs spot quote balance (or perp funds the CLI transfers perp→spot on that venue).
+  # The exact rule (shared vs separate spot margin, transfer shortfall) is enforced by the arb exec
+  # dry-run below; here the spot balances are read so a read failure is surfaced.
+  SPOT_BAL=$(pj --json -e "$LONG_VENUE" trade spot-balance)
+  if isok "$SPOT_BAL"; then
+    add_result "balance_spot" "true" "$LONG_VENUE spot balances: $(jq -c '[.data.balances[] | {token, available}]' <<<"$SPOT_BAL" | tr -d '"') — sufficiency checked by the dry-run"
+  else
+    add_result "balance_spot" "false" "$LONG_VENUE spot balance unreadable ($(jq -r '.error.code' <<<"$SPOT_BAL"))"
+  fi
 else
-  add_result "balance_short" "true" "$SHORT_EX balance=$SHORT_BAL"
+  check_perp_balance "balance_long" "$LONG_VENUE"
 fi
+check_perp_balance "balance_short" "$SHORT_EX"
 
 # 3. Market info (symbol availability)
 LONG_INFO=$(pj --json -e "$LONG_VENUE" market info "$SYM")
@@ -101,7 +118,7 @@ RISK_CHECK=$(pj --json risk check --notional "$SIZE" --leverage "${LEVERAGE:-1}"
 if isok "$RISK_CHECK" && [[ "$(jq -r '.data.allowed' <<<"$RISK_CHECK" 2>/dev/null || true)" == "true" ]]; then
   add_result "risk" "true" "Within risk limits"
 else
-  RISK_WHY=$(jq -r '.data.reason // .error.code // "unknown"' <<<"$RISK_CHECK" 2>/dev/null || echo unknown)
+  if isok "$RISK_CHECK"; then RISK_WHY=$(jq -r '.data.reason' <<<"$RISK_CHECK"); else RISK_WHY=$(jq -r '.error.code' <<<"$RISK_CHECK"); fi
   add_result "risk" "false" "Risk check failed: $RISK_WHY"
 fi
 
@@ -110,7 +127,7 @@ DRY_RUN=$(pj --json --dry-run arb exec "$SYM" "$LONG_EX" "$SHORT_EX" "$SIZE" $LE
 if isok "$DRY_RUN"; then
   add_result "dry_run" "true" "Dry-run succeeded"
 else
-  DRY_ERR=$(jq -r '.error.code // "unknown"' <<<"$DRY_RUN" 2>/dev/null || echo unknown)
+  DRY_ERR=$(jq -r '"\(.error.code): \(.error.message)"' <<<"$DRY_RUN" | tr -d '"\\')
   add_result "dry_run" "false" "Dry-run failed: $DRY_ERR"
 fi
 

package/dist/cli-spec.d.ts

@@ -1,46 +0,0 @@
-import type { Command } from "commander";
-interface ArgSpec {
-    name: string;
-    required: boolean;
-}
-interface OptionSpec {
-    flags: string;
-    description: string;
-    default?: unknown;
-}
-interface CommandSpec {
-    name: string;
-    description: string;
-    args: ArgSpec[];
-    options: OptionSpec[];
-    subcommands?: CommandSpec[];
-}
-interface CliSpec {
-    name: string;
-    version: string;
-    description: string;
-    globalOptions: OptionSpec[];
-    commands: CommandSpec[];
-    exchanges: string[];
-    envelope: {
-        success: string;
-        error: string;
-        example: {
-            ok: boolean;
-            data: {
-                equity: string;
-            };
-            meta: {
-                timestamp: string;
-            };
-        };
-    };
-    errorCodes: Record<string, {
-        status: number;
-        retryable: boolean;
-        description: string;
-    }>;
-    tips: string[];
-}
-export declare function getCliSpec(program: Command): CliSpec;
-export {};