perp-cli 0.12.15 → 0.14.0

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

@@ -6,10 +6,11 @@ You are not expected to follow rigid rules — use this as a decision framework
 ## Core Concepts
 
 ### Funding Rate Mechanics
-- Funding rates settle **every 1 hour** on all supported exchanges
+- Funding settles **every 1 hour** on every venue except Aster, whose interval is **per symbol** (from its fundingInfo `fundingIntervalHours`)
+- QFEX funding rates are unverified: excluded from scans / arb; shown only with `arb scan --rates --include-unverified` (display only)
 - Positive rate = longs pay shorts, negative rate = shorts pay longs
-- Rates are annualized in display but applied hourly: `hourly = annual / 8760`
-- Scan opportunities: `perp --json arb scan --min 5` (shows spread, longExch, shortExch, netSpread)
+- Rates are displayed annualized: per hour ≈ `annual / 8760`
+- Scan opportunities: `perp --json arb scan --min 5` (shows grossSpread, netSpread, longExch, shortExch)
 
 ### Opportunity Cost Awareness
 
@@ -26,9 +27,9 @@ Switch Cost =
 
 Query each component:
 ```bash
-perp --json -e <FROM> trade check <SYM> <SIDE> <SIZE>   # close cost estimate
-perp --json bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT>  # bridge cost
-perp --json -e <TO> trade check <SYM> <SIDE> <SIZE>     # open cost estimate
+perp --json -e <FROM> trade check <SYM> <SIDE> <SIZE> --leverage <L>   # close cost estimate
+perp --json funds bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT>  # bridge cost
+perp --json -e <TO> trade check <SYM> <SIDE> <SIZE> --leverage <L>     # open cost estimate
 ```
 
 **Only switch if:**
@@ -56,8 +57,10 @@ During transition, you are **unhedged**. Price can move against you. Factor this
 
 ### Discovery Loop
 ```bash
-perp --json arb scan --min 5             # find spreads > 5 bps (shows longExch/shortExch/netSpread)
-# NOTE: 'arb rates' is deprecated — use 'arb scan' instead
+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
+# NOTE: legacy 'arb rates'/'arb prices'/'arb dex' are removed — all routes go through 'arb scan'
 ```
 
 ### CRITICAL: Reading arb scan Results
@@ -67,12 +70,14 @@ The `arb scan` output tells you EXACTLY what to do:
 ```
 longExch: "hyperliquid"   → open LONG on this exchange
 shortExch: "pacifica"     → open SHORT on this exchange
-netSpread: 12.87          → profit after fees (bps/hour)
+grossSpread: 15.2         → funding spread, annualized %
+netSpread: 12.87          → annualized % after round-trip trading costs amortized over --hold-days (default 7)
+                            (and --bridge-cost if given)
 ```
 
 **Rules:**
 1. **ALWAYS follow longExch/shortExch directions exactly.** DO NOT reverse them.
-2. **NEVER enter if netSpread ≤ 0.** Negative netSpread = loss after fees.
+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`.
 3. The direction logic: go LONG where funding is negative (longs receive), go SHORT where funding is positive (shorts receive).
 
 **Why these directions?**
@@ -92,7 +97,7 @@ When evaluating an arb opportunity:
 
 3. **How long will the spread persist?**
    - Historical funding tends to mean-revert
-   - Higher confidence in moderate, stable spreads (20-50 bps) than extreme spikes (>100 bps)
+   - Higher confidence in moderate, stable spreads (e.g. 10–50% annualized netSpread) than extreme spikes (hundreds of % annualized)
 
 4. **Can I execute both legs atomically?**
    - Both positions should open near-simultaneously to minimize directional exposure
@@ -103,19 +108,20 @@ When evaluating an arb opportunity:
 **Before entering any arb position, set a target hold duration.** This is critical for calculating whether the position is worth entering.
 
 ```
-Expected Profit = hourly_spread × target_hours
-Entry/Exit Cost = open_fees + close_fees + slippage (both legs)
-Net Profit = Expected Profit - Entry/Exit Cost
+Expected Funding = notional × (grossSpread% / 100) × target_hours / 8760
+Entry/Exit Cost  = open_fees + close_fees + slippage (both legs)
+Net Profit       = Expected Funding - Entry/Exit Cost
 ```
+(`netSpread` already does this amortization for `--hold-days`; pass `--hold-days` = your target to read it directly.)
 
 **Only enter if Net Profit > 0 with a comfortable margin.**
 
 Guidelines for hold duration:
-- **Stable spreads (20-50 bps):** target 8-24 hours. These are reliable but low-yield — you need time for the funding to accumulate past your entry/exit costs.
-- **Elevated spreads (50-100 bps):** target 4-8 hours. Higher yield, but likely to compress. Take profit earlier.
-- **Spike spreads (>100 bps):** target 1-4 hours. These revert quickly. Must cover entry/exit costs within a few funding cycles.
+- **Moderate, stable spreads (≈10–50% annualized):** target days, not hours — the funding must accumulate past entry/exit costs.
+- **Elevated spreads (≈50–100% annualized):** shorter targets; likely to compress. Take profit earlier.
+- **Spikes (well above 100% annualized):** revert quickly — enter only if the funding over a few settlements covers entry/exit costs.
 
-**Re-evaluate at each funding settlement (every hour):**
+**Re-evaluate at each funding settlement (hourly on most venues):**
 1. Is the spread still above breakeven for the remaining target hours?
 2. If spread compressed, should I exit early or extend the hold?
 3. Has a better opportunity appeared? (Remember: switching has its own cost)
@@ -124,18 +130,18 @@ Guidelines for hold duration:
 
 Example entry decision log:
 ```
-Entry: BTC HL↔PAC | Spread: 35 bps | Target hold: 12h
-Expected: 35 bps × 12h = 420 bps gross
-Entry/exit cost: ~80 bps (fees + slippage both legs)
-Net expected: ~340 bps → ENTER
-Hour 6 check: spread compressed to 15 bps → below breakeven for remaining 6h → EXIT
-Actual hold: 6h | Actual net: ~130 bps
+Entry: BTC HL↔PAC | $1000/leg | grossSpread 80% annual | Target hold: 7d
+Expected funding: 1000 × 0.80 × 168 / 8760 ≈ $15.3
+Entry/exit cost: ~$4 (fees + slippage, both legs, open + close)
+Net expected: ≈ $11 → ENTER (arb scan --hold-days 7 netSpread > 0 agrees)
+Day 3 check: grossSpread compressed to 10% → remaining 4d earn ≈ $1.1 → EXIT if it keeps falling / flips, or a better net opportunity exists
+Actual hold: 3d | log actual funding vs estimate
 ```
 
 ### Monitoring Active Positions
 ```bash
 perp --json portfolio                    # unified multi-exchange view
-perp --json risk overview                # cross-exchange risk assessment
+perp --json risk status                  # cross-exchange risk assessment (level, violations, canTrade)
 perp --json -e <EX> account positions    # per-exchange positions
 perp --json arb scan --min 5             # are current rates still favorable?
 ```
@@ -179,6 +185,8 @@ Round `ORDER_SIZE` to the coarser step size of the two exchanges. If the matched
 
 #### Step 2: Execute Legs Sequentially with Same Size
 
+Prefer `perp --json arb exec <SYM> <LONG_EX> <SHORT_EX> <USD>` — it does exactly this: long first, then the short sized to the verified long fill, reconcile always on, and an unconfirmed leg quarantines the symbol. Manual legs (below) only when `arb exec` cannot be used.
+
 Once you have a single `ORDER_SIZE`, execute both legs using THAT EXACT SIZE:
 
 ```bash
@@ -241,7 +249,7 @@ Leg B: perp --json -e <SHORT_EX> trade split <SYM> sell 5000
 #### Using Limit Orders for Better Execution
 For non-urgent entries, use limit orders at best bid/ask instead of market:
 ```bash
-perp --json -e <EX> trade buy <SYM> <ORDER_SIZE> -p <PRICE>    # limit order
+perp --json -e <EX> trade limit <SYM> buy <PRICE> <ORDER_SIZE>   # limit order (GTC default; --tif ALO = post-only)
 ```
 This avoids crossing the spread but risks not getting filled. Set a timeout and fall back to market if unfilled. **Both legs must still use the same `ORDER_SIZE`.**
 
@@ -309,7 +317,7 @@ perp --json -e <EX> trade leverage <SYM> <LEVERAGE>
 **For funding rate arb, use ISOLATED margin.** Each leg should be independent — if one side gets liquidated, the other side survives.
 
 ```bash
-perp --json manage margin <SYM> isolated     # set isolated margin
+perp --json -e <EX> wallet manage margin <SYM> isolated   # set isolated margin
 perp --json -e <EX> trade leverage <SYM> <LEV> --isolated   # set leverage + isolated at once
 ```
 
@@ -405,8 +413,8 @@ Rules of thumb:
 
 Each exchange holds its own separate balance. Before entering any arb:
 ```bash
-perp --json -e <EX_A> account balance           # check available balance on exchange A
-perp --json -e <EX_B> account balance           # check available balance on exchange B
+perp --json portfolio -e <EX_A>                 # check available balance on exchange A
+perp --json portfolio -e <EX_B>                 # check available balance on exchange B
 ```
 
 **Size each leg to fit the available balance on that exchange:**
@@ -426,15 +434,12 @@ Even "market-neutral" arb can lose money if:
 - Extreme funding spike in the wrong direction
 - Slippage on entry/exit far exceeds estimates
 
-**Always set stop losses on both legs:**
-```bash
-perp --json -e <EX_A> trade sl <SYM> <PRICE>    # stop loss on leg A
-perp --json -e <EX_B> trade sl <SYM> <PRICE>    # stop loss on leg B
-```
-
-Or use TP/SL together:
+**Always set stop losses on both legs** (`long|short` = the OPEN position's side; legs are reduce-only, sized to the live position):
 ```bash
-perp --json -e <EX> trade tp-sl <SYM> --tp <PRICE> --sl <PRICE>
+perp --json --dry-run -e <EX_A> trade tpsl <SYM> long  --sl <PRICE>              # leg A (long): SL below mark
+perp --json -e <EX_A> trade tpsl <SYM> long  --sl <PRICE>
+perp --json -e <EX_B> trade tpsl <SYM> short --sl <PRICE>                       # leg B (short): SL above mark
+perp --json -e <EX> trade tpsl <SYM> long --sl <PRICE> --tp <PRICE>             # TP + SL together
 ```
 
 ### What to Track Over Time
@@ -453,7 +458,8 @@ This is YOUR operational knowledge. Use it to make better decisions over time.
 ### Cross-Exchange Capital Allocation
 Your capital is split across exchanges. Rebalancing has real costs:
 ```bash
-perp --json bridge quote --from solana --to arbitrum --amount 1000
+perp --json funds bridge quote --from solana --to arbitrum --amount 1000
+perp --json funds rebalance plan                  # auto-compute optimal moves across exchanges
 ```
 
 Before rebalancing, ask:

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

@@ -1,7 +1,7 @@
 #!/bin/bash
 # Monitor open arb positions and evaluate exit conditions
 # Usage: ./arb-monitor.sh [--json] [--min-spread 5]
-# Checks: current spread vs entry, funding earned, PnL, liquidation distance
+# Checks: current spread vs entry, funding earned (from arb status), PnL, liquidation distance
 # Returns JSON with position health + actionable recommendations
 
 set -euo pipefail
@@ -13,6 +13,11 @@ else
   PERP="npx -y perp-cli@latest"
 fi
 
+# 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; }
+isok() { jq -e '.ok == true' >/dev/null 2>&1 <<<"$1"; }
+
 JSON_MODE=false
 MIN_SPREAD=5
 while [[ $# -gt 0 ]]; do
@@ -23,9 +28,9 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-# 1. Get current arb status
-ARB_STATUS=$($PERP --json arb status 2>/dev/null || echo '{"ok":false}')
-if ! echo "$ARB_STATUS" | grep -q '"ok":true'; then
+# 1. Get current arb status (already includes funding earned per period)
+ARB_STATUS=$(pj --json arb status)
+if ! isok "$ARB_STATUS"; then
   if $JSON_MODE; then
     echo '{"ok":false,"error":"No arb positions or arb status unavailable"}'
   else
@@ -34,14 +39,14 @@ if ! echo "$ARB_STATUS" | grep -q '"ok":true'; then
   exit 0
 fi
 
-# 2. Get current spreads
-ARB_SCAN=$($PERP --json arb scan --min 0 2>/dev/null || echo '{"ok":false,"data":{"opportunities":[]}}')
+# 2. Get current spreads (all modes)
+ARB_SCAN=$(pj --json arb scan --mode all --min 0)
 
-# 3. Get funding earned
-FUNDING=$($PERP --json arb funding-earned 2>/dev/null || echo '{"ok":false}')
+# 3. Get liquidation distances
+LIQ_DIST=$(pj --json risk liquidation-distance)
 
-# 4. Get liquidation distances
-LIQ_DIST=$($PERP --json risk liquidation-distance 2>/dev/null || echo '{"ok":false}')
+# 4. Get risk overview
+RISK_STATUS=$(pj --json risk status)
 
 # 5. Output combined analysis
 if $JSON_MODE; then
@@ -51,8 +56,8 @@ if $JSON_MODE; then
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "positions": $ARB_STATUS,
   "currentSpreads": $ARB_SCAN,
-  "fundingEarned": $FUNDING,
   "liquidationDistance": $LIQ_DIST,
+  "riskStatus": $RISK_STATUS,
   "minSpreadThreshold": $MIN_SPREAD
 }
 EOF
@@ -60,15 +65,15 @@ else
   echo "=== Arb Position Monitor ==="
   echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
   echo ""
-  echo "--- Positions ---"
+  echo "--- Positions (with funding earned) ---"
   echo "$ARB_STATUS" | jq -r '.data // empty'
   echo ""
-  echo "--- Funding Earned ---"
-  echo "$FUNDING" | jq -r '.data // empty'
-  echo ""
   echo "--- Liquidation Distance ---"
   echo "$LIQ_DIST" | jq -r '.data // empty'
   echo ""
-  echo "Min spread threshold: ${MIN_SPREAD} bps"
-  echo "Recommendation: Check if current spreads exceed ${MIN_SPREAD} bps to continue holding."
+  echo "--- Risk Status ---"
+  echo "$RISK_STATUS" | jq -r '.data // empty'
+  echo ""
+  echo "Min spread threshold: ${MIN_SPREAD}% annual"
+  echo "Recommendation: Check if current spreads exceed ${MIN_SPREAD}% to continue holding."
 fi

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

@@ -12,6 +12,11 @@ else
   PERP="npx -y perp-cli@latest"
 fi
 
+# 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; }
+isok() { jq -e '.ok == true' >/dev/null 2>&1 <<<"$1"; }
+
 JSON_MODE=false
 SYMBOL=""
 TOP=10
@@ -26,9 +31,10 @@ done
 
 if [[ -n "$SYMBOL" ]]; then
   # Single symbol detailed analysis
-  FUNDING=$($PERP --json market funding "$SYMBOL" 2>/dev/null || echo '{"ok":false}')
-  SCAN=$($PERP --json arb scan --min 0 2>/dev/null || echo '{"ok":false}')
-  SPOT_SCAN=$($PERP --json arb scan --mode spot-perp --min 0 2>/dev/null || echo '{"ok":false}')
+  FUNDING=$(pj --json arb scan --history "$SYMBOL")
+  COMPARE=$(pj --json arb scan --compare "$SYMBOL")
+  SCAN=$(pj --json arb scan --mode perp-perp --min 0)
+  SPOT_SCAN=$(pj --json arb scan --mode spot-perp --min 0)
 
   if $JSON_MODE; then
     cat <<EOF
@@ -36,7 +42,8 @@ if [[ -n "$SYMBOL" ]]; then
   "ok": true,
   "symbol": "$SYMBOL",
   "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
-  "funding": $FUNDING,
+  "fundingHistory": $FUNDING,
+  "compare": $COMPARE,
   "perpPerpArb": $SCAN,
   "spotPerpArb": $SPOT_SCAN
 }
@@ -44,25 +51,28 @@ EOF
   else
     echo "=== Funding Analysis: $SYMBOL ==="
     echo ""
-    echo "--- Current Funding Rates ---"
+    echo "--- Cross-Exchange Compare ---"
+    echo "$COMPARE" | jq -r '.data // empty' 2>/dev/null || echo "(unavailable)"
+    echo ""
+    echo "--- Funding History ---"
     echo "$FUNDING" | jq -r '.data // empty' 2>/dev/null || echo "(unavailable)"
     echo ""
     echo "--- Perp-Perp Arb ---"
     echo "$SCAN" | jq -r '
       .data // [] | map(select(.symbol == "'"$SYMBOL"'")) | .[] |
-      "  \(.longExch // .longExchange)→\(.shortExch // .shortExchange): \(.netSpread // .spread)bps"
+      "  \(.longExch // .longExchange)→\(.shortExch // .shortExchange): net \(.netSpread)% annual"
     ' 2>/dev/null || echo "  (no opportunity)"
     echo ""
     echo "--- Spot+Perp Arb ---"
     echo "$SPOT_SCAN" | jq -r '
       .data // [] | map(select(.symbol == "'"$SYMBOL"'")) | .[] |
-      "  \(.direction): \(.annualSpreadPct // .spread)% annual"
+      "  \(.direction) spot:\((.spotExchanges // []) | join("/"))→\(.perpExchange): net \(.netSpreadPct)% annual"
     ' 2>/dev/null || echo "  (no opportunity)"
   fi
 else
   # All symbols scan
-  SCAN=$($PERP --json arb scan --mode all --min 0 2>/dev/null || echo '{"ok":false}')
-  FUNDING_DETAIL=$($PERP --json arb rates 2>/dev/null || echo '{"ok":false}')
+  SCAN=$(pj --json arb scan --mode all --min 0)
+  FUNDING_DETAIL=$(pj --json arb scan --rates)
 
   if $JSON_MODE; then
     cat <<EOF
@@ -79,7 +89,7 @@ EOF
     echo ""
     echo "$SCAN" | jq -r "
       .data // [] | .[0:$TOP] | .[] |
-      \"  \(.symbol) | \(.mode // \"perp\") | \(.netSpread // .spread)bps | \(.longExch // .longExchange)→\(.shortExch // .shortExchange)\"
+      \"  \(.symbol) | \(.mode // \"perp\") | net \(.netSpread // .netSpreadPct)%/yr | \(.longExch // (\"spot:\" + ((.spotExchanges // []) | join(\"/\"))))→\(.shortExch // .perpExchange)\"
     " 2>/dev/null || echo "(no data)"
   fi
 fi

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

@@ -13,6 +13,11 @@ else
   PERP="npx -y perp-cli@latest"
 fi
 
+# 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; }
+isok() { jq -e '.ok == true' >/dev/null 2>&1 <<<"$1"; }
+
 JSON_MODE=false
 [[ "${1:-}" == "--json" ]] && JSON_MODE=true
 
@@ -22,7 +27,7 @@ checks=()
 add_check() {
   local name="$1" status="$2" detail="$3"
   checks+=("{\"name\":\"$name\",\"status\":\"$status\",\"detail\":\"$detail\"}")
-  [[ "$status" == "fail" ]] && issues+=("$name: $detail")
+  if [[ "$status" == "fail" ]]; then issues+=("$name: $detail"); fi
 }
 
 # 1. perp-cli installed and version check
@@ -30,38 +35,39 @@ 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'))"
 else
-  add_check "install" "fail" "perp-cli not found — run: npm i -g perp-cli@latest or use npx"
+  add_check "install" "fail" "perp-cli not found — ask the user before installing (npm i -g perp-cli@latest) or use npx"
 fi
 
 # 2. Wallet configured
-WALLET_OUT=$($PERP --json wallet show 2>/dev/null || echo '{"ok":false}')
-if echo "$WALLET_OUT" | grep -q '"ok":true'; then
+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>"
+  add_check "wallet" "fail" "No wallet configured — run: perp wallet set <exchange>  (key via hidden prompt or stdin)"
 fi
 
 # 3. Exchange connectivity (proxy via unauthenticated market prices fetch)
-HEALTH_OUT=$($PERP --json market prices 2>/dev/null || echo '{"ok":false}')
-if echo "$HEALTH_OUT" | grep -q '"ok":true'; then
+HEALTH_OUT=$(pj --json market prices)
+if isok "$HEALTH_OUT"; then
   add_check "connectivity" "pass" "Exchange reachable"
 else
   add_check "connectivity" "warn" "Exchange unreachable"
 fi
 
 # 4. Portfolio & balances
-PORTFOLIO_OUT=$($PERP --json portfolio 2>/dev/null || echo '{"ok":false}')
-if echo "$PORTFOLIO_OUT" | grep -q '"ok":true'; then
+PORTFOLIO_OUT=$(pj --json portfolio)
+if isok "$PORTFOLIO_OUT"; then
   add_check "portfolio" "pass" "Portfolio accessible"
 else
   add_check "portfolio" "warn" "Could not fetch portfolio"
 fi
 
 # 5. Risk status
-RISK_OUT=$($PERP --json risk status 2>/dev/null || echo '{"ok":false}')
-if echo "$RISK_OUT" | grep -q '"canTrade":true'; then
+RISK_OUT=$(pj --json risk status)
+CAN_TRADE=$(jq -r '.data.canTrade // empty' <<<"$RISK_OUT" 2>/dev/null || true)
+if [[ "$CAN_TRADE" == "true" ]]; then
   add_check "risk" "pass" "Trading allowed (canTrade=true)"
-elif echo "$RISK_OUT" | grep -q '"canTrade":false'; then
+elif [[ "$CAN_TRADE" == "false" ]]; then
   add_check "risk" "fail" "Trading blocked — check risk violations"
 else
   add_check "risk" "warn" "Could not check risk status"
@@ -69,11 +75,12 @@ fi
 
 # Output
 READY=true
-[[ ${#issues[@]} -gt 0 ]] && READY=false
+if [[ ${#issues[@]} -gt 0 ]]; then READY=false; fi
 
 if $JSON_MODE; then
   CHECKS_JSON=$(IFS=,; echo "${checks[*]}")
-  ISSUES_JSON=$(printf '%s\n' "${issues[@]}" | jq -R . | jq -s .)
+  ISSUES_JSON='[]'
+  if [[ ${#issues[@]} -gt 0 ]]; then ISSUES_JSON=$(printf '%s\n' "${issues[@]}" | jq -R . | jq -s .); fi
   echo "{\"ready\":$READY,\"checks\":[$CHECKS_JSON],\"issues\":$ISSUES_JSON}"
 else
   echo "=== perp-cli Pre-flight Check ==="

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

@@ -12,6 +12,11 @@ else
   PERP="npx -y perp-cli@latest"
 fi
 
+# 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; }
+isok() { jq -e '.ok == true' >/dev/null 2>&1 <<<"$1"; }
+
 JSON_MODE=false
 MODE="all"
 MIN_SPREAD=10
@@ -25,8 +30,8 @@ while [[ $# -gt 0 ]]; do
 done
 
 # 1. Portfolio check (ensure we have balances)
-PORTFOLIO=$($PERP --json portfolio 2>/dev/null || echo '{"ok":false}')
-if ! echo "$PORTFOLIO" | grep -q '"ok":true'; then
+PORTFOLIO=$(pj --json portfolio)
+if ! isok "$PORTFOLIO"; then
   if $JSON_MODE; then
     echo '{"ok":false,"error":"Cannot fetch portfolio — check wallet setup"}'
   else
@@ -36,10 +41,10 @@ if ! echo "$PORTFOLIO" | grep -q '"ok":true'; then
 fi
 
 # 2. Run appropriate scan
-SCAN_RESULT=$($PERP --json arb scan --mode "$MODE" --min "$MIN_SPREAD" 2>/dev/null || echo '{"ok":false}')
+SCAN_RESULT=$(pj --json arb scan --mode "$MODE" --min "$MIN_SPREAD")
 
 # 3. Get exchange health for context (proxy via market prices fetch)
-HEALTH=$($PERP --json market prices 2>/dev/null || echo '{"ok":false}')
+HEALTH=$(pj --json market prices)
 
 if $JSON_MODE; then
   cat <<EOF
@@ -55,14 +60,14 @@ if $JSON_MODE; then
 EOF
 else
   echo "=== Spot+Perp Arb Scanner ==="
-  echo "Mode: $MODE | Min spread: ${MIN_SPREAD} bps"
+  echo "Mode: $MODE | Min spread: ${MIN_SPREAD}% annual"
   echo ""
 
   # Show balances
   echo "--- Balances ---"
   echo "$PORTFOLIO" | jq -r '
     .data.exchanges // [] | .[] |
-    "  \(.exchange): $\(.balance // .equity // "N/A")"
+    "  \(.name): equity $\(.perp.equity // "N/A")"
   ' 2>/dev/null || echo "  (unable to parse)"
   echo ""
 
@@ -70,7 +75,7 @@ else
   echo "--- Opportunities ---"
   echo "$SCAN_RESULT" | jq -r '
     .data // [] | .[] |
-    "  \(.symbol) | \(.mode // "perp-perp") | spread: \(.netSpread // .spread)bps | \(.longExch // .longExchange)→\(.shortExch // .shortExchange)"
+    "  \(.symbol) | \(.mode // "perp-perp") | net: \(.netSpread // .netSpreadPct)%/yr | \(.longExch // ("spot:" + ((.spotExchanges // []) | join("/"))))→\(.shortExch // .perpExchange)"
   ' 2>/dev/null || echo "  (no opportunities or parse error)"
 
   # Show exchange health

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

@@ -1,8 +1,9 @@
 #!/bin/bash
 # Validate an arb opportunity before execution
 # Usage: ./validate-arb.sh <SYMBOL> <LONG_EX> <SHORT_EX> <SIZE_USD> [--leverage N]
-# Performs: price check, liquidity check, balance check, risk check, slippage estimate
+# 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).
 
 set -euo pipefail
 
@@ -13,6 +14,11 @@ else
   PERP="npx -y perp-cli@latest"
 fi
 
+# 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; }
+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]}"
 LONG_EX="${2:?Usage: validate-arb.sh <SYMBOL> <LONG_EX> <SHORT_EX> <SIZE_USD>}"
 SHORT_EX="${3:?Usage: validate-arb.sh <SYMBOL> <LONG_EX> <SHORT_EX> <SIZE_USD>}"
@@ -33,12 +39,22 @@ pass=true
 add_result() {
   local name="$1" ok="$2" detail="$3"
   checks+=("{\"check\":\"$name\",\"ok\":$ok,\"detail\":\"$detail\"}")
-  [[ "$ok" == "false" ]] && pass=false
+  if [[ "$ok" == "false" ]]; then pass=false; fi
+}
+
+# Venue of the long leg (spot:<venue> → <venue>) for the per-venue reads below
+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=$($PERP --json -e "$LONG_EX" market mid "$SYM" 2>/dev/null | jq -r '.data.mid // "0"')
-SHORT_PRICE=$($PERP --json -e "$SHORT_EX" market mid "$SYM" 2>/dev/null | jq -r '.data.mid // "0"')
+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"
@@ -53,8 +69,8 @@ else
 fi
 
 # 2. Balance check on both exchanges
-LONG_BAL=$($PERP --json -e "$LONG_EX" account balance 2>/dev/null | jq -r '.data.available // .data.equity // "0"')
-SHORT_BAL=$($PERP --json -e "$SHORT_EX" account balance 2>/dev/null | jq -r '.data.available // .data.equity // "0"')
+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
@@ -69,31 +85,32 @@ else
 fi
 
 # 3. Market info (symbol availability)
-LONG_INFO=$($PERP --json -e "$LONG_EX" market info "$SYM" 2>/dev/null || echo '{"ok":false}')
-SHORT_INFO=$($PERP --json -e "$SHORT_EX" market info "$SYM" 2>/dev/null || echo '{"ok":false}')
+LONG_INFO=$(pj --json -e "$LONG_VENUE" market info "$SYM")
+SHORT_INFO=$(pj --json -e "$SHORT_EX" market info "$SYM")
 
-if echo "$LONG_INFO" | grep -q '"ok":true' && echo "$SHORT_INFO" | grep -q '"ok":true'; then
+if isok "$LONG_INFO" && isok "$SHORT_INFO"; then
   add_result "market_info" "true" "Both exchanges support $SYM"
 else
   add_result "market_info" "false" "Symbol $SYM not available on one or both exchanges"
 fi
 
-# 4. Risk pre-check
+# 4. Risk pre-check (risk check requires --leverage; default 1x when not given)
 LEV_FLAG=""
 [[ -n "$LEVERAGE" ]] && LEV_FLAG="--leverage $LEVERAGE"
-RISK_CHECK=$($PERP --json risk check --notional "$SIZE" $LEV_FLAG 2>/dev/null || echo '{"ok":false}')
-if echo "$RISK_CHECK" | grep -q '"ok":true'; then
+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
-  add_result "risk" "false" "Risk check failed — review risk limits"
+  RISK_WHY=$(jq -r '.data.reason // .error.code // "unknown"' <<<"$RISK_CHECK" 2>/dev/null || echo unknown)
+  add_result "risk" "false" "Risk check failed: $RISK_WHY"
 fi
 
 # 5. Dry-run
-DRY_RUN=$($PERP --json --dry-run arb exec "$SYM" "$LONG_EX" "$SHORT_EX" "$SIZE" $LEV_FLAG 2>/dev/null || echo '{"ok":false}')
-if echo "$DRY_RUN" | grep -q '"ok":true'; then
+DRY_RUN=$(pj --json --dry-run arb exec "$SYM" "$LONG_EX" "$SHORT_EX" "$SIZE" $LEV_FLAG)
+if isok "$DRY_RUN"; then
   add_result "dry_run" "true" "Dry-run succeeded"
 else
-  DRY_ERR=$(echo "$DRY_RUN" | jq -r '.error.message // .error // "unknown"' 2>/dev/null)
+  DRY_ERR=$(jq -r '.error.code // "unknown"' <<<"$DRY_RUN" 2>/dev/null || echo unknown)
   add_result "dry_run" "false" "Dry-run failed: $DRY_ERR"
 fi
 

package/vendor/lighter-signer/SHA256SUMS

@@ -0,0 +1,2 @@
+781ba28b5e7fca1ea816f516f28fe2adbe704b734828e0c941025f8133bd7b4b  lighter-signer.wasm
+0c949f4996f9a89698e4b5c586de32249c3b69b7baadb64d220073cc04acba14  wasm_exec.js

package/vendor/lighter-signer/VERSION

@@ -0,0 +1,8 @@
+lighter-signer.wasm: elliottech/lighter-go release v1.0.9 (2026-09-14), asset "lighter-signer.wasm"
+  https://github.com/elliottech/lighter-go/releases/download/v1.0.9/lighter-signer.wasm
+  built from lighter-go 8854554 ("allow markets gr 4095 (#89)") with go1.25.6 (GOOS=js GOARCH=wasm)
+  sha256 matches the release asset digest published by GitHub.
+wasm_exec.js: Go go1.25.6 lib/wasm/wasm_exec.js (the runtime glue matching the toolchain the wasm was built with)
+  https://github.com/golang/go/blob/go1.25.6/lib/wasm/wasm_exec.js
+Functions/arguments: https://apidocs.lighter.xyz/docs/wasm-signer
+Both files are verified against SHA256SUMS (also pinned in src/exchanges/lighter-signer.ts) before load; a mismatch refuses to sign.