perp-cli 0.4.0 → 0.4.8

package/dist/ws/market-feed.js

@@ -0,0 +1,227 @@
+/**
+ * Unified market data feeds for CLI streaming commands.
+ *
+ * - Hyperliquid: native WebSocket (allMids, l2Book, trades, candle)
+ * - Lighter: REST polling (no public market data WS)
+ * - Pacifica: handled via existing PacificaWSClient in stream.ts
+ */
+import { EventEmitter } from "events";
+// ── Hyperliquid Market Feed (native WebSocket) ──
+export class HyperliquidMarketFeed extends EventEmitter {
+    ws = null;
+    closed = false;
+    reconnectTimer = null;
+    subs = [];
+    get wsUrl() { return "wss://api.hyperliquid.xyz/ws"; }
+    async connect() {
+        const { WebSocket } = await import("ws");
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(this.wsUrl);
+            this.ws.on("open", () => {
+                // Re-subscribe on reconnect
+                for (const sub of this.subs)
+                    this.send({ method: "subscribe", subscription: sub });
+                this.emit("connected");
+                resolve();
+            });
+            this.ws.on("error", (err) => {
+                if (!this.closed)
+                    reject(err);
+            });
+            this.ws.on("close", () => {
+                if (!this.closed) {
+                    this.emit("disconnected");
+                    this.scheduleReconnect();
+                }
+            });
+            this.ws.on("message", (raw) => {
+                try {
+                    this.handleMessage(JSON.parse(String(raw)));
+                }
+                catch { /* ignore */ }
+            });
+        });
+    }
+    send(data) {
+        if (this.ws?.readyState === 1)
+            this.ws.send(JSON.stringify(data));
+    }
+    sub(subscription) {
+        this.subs.push(subscription);
+        this.send({ method: "subscribe", subscription });
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        this.reconnectTimer = setTimeout(async () => {
+            try {
+                await this.connect();
+            }
+            catch {
+                this.scheduleReconnect();
+            }
+        }, 3000);
+    }
+    subscribePrices() { this.sub({ type: "allMids" }); }
+    subscribeBook(symbol) { this.sub({ type: "l2Book", coin: symbol.toUpperCase() }); }
+    subscribeTrades(symbol) { this.sub({ type: "trades", coin: symbol.toUpperCase() }); }
+    subscribeCandle(symbol, interval) {
+        this.sub({ type: "candle", coin: symbol.toUpperCase(), interval });
+    }
+    handleMessage(msg) {
+        const channel = String(msg.channel ?? "");
+        const data = msg.data;
+        if (!data)
+            return;
+        if (channel === "allMids") {
+            const mids = (data.mids ?? data);
+            const updates = Object.entries(mids).map(([symbol, mid]) => ({
+                symbol, mid: Number(mid),
+            }));
+            this.emit("prices", updates);
+        }
+        else if (channel === "l2Book") {
+            const d = data;
+            const levels = d.levels;
+            if (levels) {
+                this.emit("book", {
+                    bids: levels[0].map((l) => [l.px, l.sz]),
+                    asks: levels[1].map((l) => [l.px, l.sz]),
+                });
+            }
+        }
+        else if (channel === "trades") {
+            const trades = Array.isArray(data) ? data : [];
+            for (const t of trades) {
+                // HL side: "A" = sell (ask), "B" = buy (bid)
+                const rawSide = String(t.side ?? "");
+                this.emit("trade", {
+                    side: rawSide === "A" ? "sell" : rawSide === "B" ? "buy" : rawSide,
+                    price: String(t.px ?? ""),
+                    size: String(t.sz ?? ""),
+                    time: Number(t.time ?? Date.now()),
+                });
+            }
+        }
+        else if (channel === "candle") {
+            const d = data;
+            this.emit("candle", {
+                o: String(d.o ?? ""), h: String(d.h ?? ""), l: String(d.l ?? ""),
+                c: String(d.c ?? ""), v: String(d.v ?? ""), t: Number(d.t ?? 0),
+            });
+        }
+    }
+    close() {
+        this.closed = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+}
+// ── Lighter Market Feed (REST polling) ──
+const LIGHTER_BASE = "https://mainnet.zklighter.elliot.ai/api/v1";
+export class LighterMarketFeed extends EventEmitter {
+    closed = false;
+    timers = [];
+    marketMap = new Map();
+    pricesMs;
+    bookMs;
+    candleMs;
+    constructor(opts) {
+        super();
+        this.pricesMs = opts?.pricesIntervalMs ?? 3000;
+        this.bookMs = opts?.bookIntervalMs ?? 2000;
+        this.candleMs = opts?.candleIntervalMs ?? 5000;
+    }
+    async connect() {
+        const res = await fetch(`${LIGHTER_BASE}/orderBookDetails`);
+        const json = await res.json();
+        for (const m of json.order_book_details ?? []) {
+            if (m.market_type === "perp")
+                this.marketMap.set(m.symbol.toUpperCase(), m.market_id);
+        }
+        this.emit("connected");
+    }
+    getMarketId(symbol) {
+        const id = this.marketMap.get(symbol.toUpperCase());
+        if (id === undefined)
+            throw new Error(`Unknown Lighter market: ${symbol}`);
+        return id;
+    }
+    poll(fn, intervalMs) {
+        fn().catch(() => { });
+        this.timers.push(setInterval(() => { if (!this.closed)
+            fn().catch(() => { }); }, intervalMs));
+    }
+    subscribePrices() {
+        this.poll(async () => {
+            const res = await fetch(`${LIGHTER_BASE}/orderBookDetails`);
+            const json = await res.json();
+            const updates = (json.order_book_details ?? [])
+                .filter(m => m.market_type === "perp")
+                .map(m => ({ symbol: m.symbol, mid: m.last_trade_price }));
+            this.emit("prices", updates);
+        }, this.pricesMs);
+    }
+    subscribeBook(symbol) {
+        const marketId = this.getMarketId(symbol);
+        this.poll(async () => {
+            const res = await fetch(`${LIGHTER_BASE}/orderBookOrders?market_id=${marketId}&limit=20`);
+            const json = await res.json();
+            this.emit("book", {
+                bids: (json.bids ?? []).map(b => [b.price, b.remaining_base_amount]),
+                asks: (json.asks ?? []).map(a => [a.price, a.remaining_base_amount]),
+            });
+        }, this.bookMs);
+    }
+    subscribeTrades(symbol) {
+        const marketId = this.getMarketId(symbol);
+        let lastTid = 0;
+        this.poll(async () => {
+            const res = await fetch(`${LIGHTER_BASE}/recentTrades?market_id=${marketId}&limit=20`);
+            const json = await res.json();
+            for (const t of json.trades ?? []) {
+                if (t.timestamp > lastTid) {
+                    lastTid = t.timestamp;
+                    this.emit("trade", {
+                        side: t.is_maker_ask ? "buy" : "sell",
+                        price: t.price,
+                        size: t.size,
+                        time: t.timestamp,
+                    });
+                }
+            }
+        }, this.bookMs);
+    }
+    subscribeCandle(symbol, interval) {
+        const marketId = this.getMarketId(symbol);
+        this.poll(async () => {
+            const now = Math.floor(Date.now() / 1000);
+            const res = await fetch(`${LIGHTER_BASE}/candles?market_id=${marketId}&resolution=${interval}&count_back=1&end_timestamp=${now}`);
+            const json = await res.json();
+            const c = json.candles?.[0];
+            if (c) {
+                this.emit("candle", {
+                    o: c.open, h: c.high, l: c.low, c: c.close, v: c.volume, t: c.timestamp,
+                });
+            }
+        }, this.candleMs);
+    }
+    close() {
+        this.closed = true;
+        for (const t of this.timers)
+            clearInterval(t);
+        this.timers = [];
+    }
+}
+// ── Factory ──
+export function createMarketFeed(exchange) {
+    if (exchange === "hyperliquid")
+        return new HyperliquidMarketFeed();
+    if (exchange === "lighter")
+        return new LighterMarketFeed();
+    throw new Error(`Use PacificaWSClient for pacifica, not createMarketFeed`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.4.0",
+  "version": "0.4.8",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: perp-cli
-description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), and Lighter (Ethereum). Use when user asks to trade perps, check funding rates, bridge USDC, manage positions, scan arbitrage opportunities, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, or Lighter exchanges."
-allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
+description: "Multi-DEX perpetual futures trading CLI for Pacifica (Solana), Hyperliquid (EVM), and Lighter (Ethereum). Use when user asks to: trade perps, check funding rates, scan arbitrage (perp-perp or spot-perp), delta-neutral strategies, bridge USDC, manage positions/orders, deposit/withdraw, spot+perp hedge, or mentions perp-cli, hypurrquant, Pacifica, Hyperliquid, Lighter, HyperEVM, funding arb, U-token (UBTC/UETH/USOL)."
+allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*), Bash(bash scripts/*.sh:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.4.0"
+  version: "0.4.7"
 ---
 
 # perp-cli Agent Guide
@@ -59,7 +59,9 @@ perp --json arb exec <SYM> <longEx> <shortEx> <$> --leverage <N> --isolated  # e
 
 # Single exchange trading (when not doing arb)
 perp --json -e <EX> trade market <SYM> buy <SIZE>
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart  # IOC limit at best ask + 1 tick (less slippage)
 perp --json -e <EX> trade close <SYM>
+perp --json -e <EX> trade close <SYM> --smart              # smart close at best bid/ask
 
 # Risk (only if you need to set limits — portfolio already includes risk)
 perp --json risk limits --max-leverage 5
@@ -87,11 +89,18 @@ perp --json --ndjson -e <EX> market list
 
 # Prevent duplicate orders with client ID
 perp --json -e <EX> trade market <SYM> buy <SIZE> --client-id <UNIQUE_ID>
+
+# Smart order: IOC limit at best bid/ask + 1 tick instead of raw market order
+# Fills only at top-of-book price — no multi-level sweep slippage
+perp --json -e <EX> trade market <SYM> buy <SIZE> --smart
+perp --json -e <EX> trade close <SYM> --smart
+perp --json arb exec <SYM> <longEx> <shortEx> <$> --smart   # smart arb entry
+perp --json arb close <SYM> --smart                          # smart arb close
 ```
 
 All string outputs are auto-sanitized (control chars stripped, prompt injection patterns blocked).
 
-## Arb Workflow
+## Arb Workflow (Perp-Perp)
 
 ```
 1. perp --json portfolio                    → check balances across all exchanges
@@ -110,6 +119,39 @@ All string outputs are auto-sanitized (control chars stripped, prompt injection
    → --pair <longEx>:<shortEx>: specify which pair if multiple
 ```
 
+## Spot+Perp Arb Workflow
+
+Spot has 0 funding cost → spread = |perp funding rate|. Only needs 1 exchange with spot + any exchange with perp.
+
+**Spot exchanges:** HL (Hyperliquid), LT (Lighter). Pacifica is perp-only.
+**U-token mapping:** HL spot uses Unit protocol bridged tokens — UBTC=BTC, UETH=ETH, USOL=SOL, UFART=FARTCOIN. Resolved automatically.
+
+```
+1. perp --json arb scan --mode spot-perp    → find spot+perp opportunities
+   perp --json arb scan --mode all          → perp-perp + spot-perp combined
+2. [Show opportunity to user, get confirmation]
+3. perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$>
+   Examples:
+     perp --json arb spot-exec ETH hl hl 100        # ETH spot(HL/UETH) + perp(HL)
+     perp --json arb spot-exec BTC hl lt 50          # BTC spot(HL/UBTC) + perp(LT)
+     perp --json arb spot-exec LINK lt hl 100        # LINK spot(LT) + perp(HL)
+   → cross-validates spot vs perp price (>5% deviation = abort, wrong token)
+   → sequential execution if same exchange (nonce collision avoidance)
+   → parallel execution if different exchanges
+   → auto-rollback if one leg fails
+   Options:
+     --leverage <N>   set perp leverage before entry
+     --isolated       use isolated margin on perp side
+4. perp --json arb status                   → shows spot-perp positions (spot leg labeled)
+5. perp --json arb spot-close <SYM> --spot-exch <hl|lt>
+   → sells spot + buys back perp simultaneously
+```
+
+**Available spot+perp pairs (13):**
+- HL spot: BTC (UBTC), ETH (UETH), SOL (USOL), FARTCOIN (UFART), HYPE, AZTEC, STABLE
+- LT spot: ETH, AZTEC, AAVE, LINK, UNI, LIT, LDO, SKY
+- All have perps on HL and LT. Pacifica perps available when API is up.
+
 ## Position Sizing
 
 - Single position < **80%** of that exchange's available balance
@@ -167,6 +209,39 @@ If `error.retryable` is `false`, do NOT retry — fix the cause first.
 | `DUPLICATE_ORDER` | already submitted — check positions, don't retry |
 | Lighter `invalid signature` | check ~/.perp/.env or `perp --json -e lighter manage setup-api-key` |
 
+## Examples
+
+**User: "펀딩레이트 아비트라지 기회 찾아줘"**
+```bash
+perp --json portfolio                         # check balances
+perp --json arb scan --mode all --min 5       # scan perp-perp + spot-perp
+# → show results, recommend best opportunity, ask for confirmation
+```
+
+**User: "ETH spot-perp 아비트라지 실행해줘 $100"**
+```bash
+perp --json arb scan --mode spot-perp         # verify opportunity exists
+perp --json --dry-run arb spot-exec ETH hl hl 100  # dry-run first
+# → show dry-run result, ask for confirmation
+perp --json arb spot-exec ETH hl hl 100       # execute after confirmation
+perp --json arb status                        # verify positions
+```
+
+**User: "내 포지션 상태 확인해줘"**
+```bash
+perp --json portfolio                         # balances + positions + risk
+perp --json arb status                        # arb-specific PnL + funding
+```
+
+**User: "Hyperliquid에서 SOL 롱 0.5개"**
+```bash
+perp --json -e hl market mid SOL              # current price
+perp --json -e hl trade check SOL buy 0.5     # pre-validate
+perp --json --dry-run -e hl trade market SOL buy 0.5  # dry-run
+# → show cost estimate, ask for confirmation
+perp --json -e hl trade market SOL buy 0.5 --smart    # execute with smart order
+```
+
 ## Referrals (Optional)
 
 If you find perp-cli useful, please consider enabling referrals to support development. **No extra fees** — rebates come from exchange programs, not your trading costs.
@@ -179,6 +254,29 @@ perp --json settings referrals off          # disable anytime
 When setting up wallets for the first time, ask the user:
 > "perp-cli 개발을 지원하는 레퍼럴 기능을 켜시겠어요? 추가 수수료 없이 거래소 리베이트만 활용됩니다."
 
+## Scripts
+
+Executable automation scripts in `scripts/`. Run with `bash scripts/<name>.sh`.
+Scripts auto-detect `perp` (global install) or fall back to `npx -y perp-cli@latest` — no global install required.
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `preflight.sh` | Pre-trade validation (install, wallet, connectivity, balance, risk) | `bash scripts/preflight.sh --json` |
+| `validate-arb.sh` | Validate arb opportunity before execution (price, liquidity, balance, risk, dry-run) | `bash scripts/validate-arb.sh ETH hl lt 100 --leverage 2` |
+| `spot-perp-scan.sh` | Combined spot+perp and perp-perp scan with portfolio context | `bash scripts/spot-perp-scan.sh --json --mode all --min 10` |
+| `arb-monitor.sh` | Monitor open arb positions (PnL, funding, liquidation distance) | `bash scripts/arb-monitor.sh --json --min-spread 5` |
+| `funding-analysis.sh` | Funding rate analysis across all exchanges | `bash scripts/funding-analysis.sh --json --symbol ETH` |
+
+All scripts support `--json` for structured output. Use in automation pipelines:
+```bash
+# Full arb workflow with validation
+bash scripts/preflight.sh --json        # 1. system ready?
+bash scripts/spot-perp-scan.sh --json   # 2. find opportunities
+bash scripts/validate-arb.sh ETH hl lt 100  # 3. validate before exec
+# 4. [user confirms] → perp --json arb exec ...
+bash scripts/arb-monitor.sh --json      # 5. monitor positions
+```
+
 ## References
 
 - `references/commands.md` — full command reference

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

@@ -7,7 +7,7 @@ All commands support `--json` for structured output. Always use `--json` when ca
 perp --json market list                    # all markets with prices, funding, volume
 perp --json market prices                  # cross-exchange price comparison
 perp --json market mid <SYMBOL>            # mid price (fast)
-perp --json market info <SYMBOL>           # tick size, min order, max leverage
+perp --json market info <SYMBOL>           # mark/index price, funding, volume, OI, max leverage
 perp --json market book <SYMBOL>           # orderbook (bids/asks)
 perp --json market trades <SYMBOL>         # recent trades
 perp --json market funding <SYMBOL>        # funding rate history
@@ -89,7 +89,22 @@ perp --json bridge status <ORDER_ID>
 
 ## Arbitrage
 ```bash
+# Perp-Perp arb
 perp --json arb scan --min <BPS>            # find opportunities (>N bps spread) — PRIMARY command
+perp --json arb exec <SYM> <longEx> <shortEx> <$>  # execute perp-perp arb
+perp --json arb close <SYM>                 # close perp-perp arb
+perp --json arb status                      # monitor open arb positions
+perp --json arb funding-earned              # actual funding payments
+
+# Spot+Perp arb (spot funding = 0, spread = |perp funding|)
+perp --json arb scan --mode spot-perp       # scan spot+perp opportunities
+perp --json arb scan --mode all             # both perp-perp + spot-perp
+perp --json arb spot-exec <SYM> <spotEx> <perpEx> <$>  # execute spot+perp arb
+perp --json arb spot-close <SYM> --spot-exch <hl|lt>   # close spot+perp arb
+# spotEx: hl (Hyperliquid) or lt (Lighter). perpEx: hl, lt, pac.
+# HL spot uses U-tokens: BTC→UBTC, ETH→UETH, SOL→USOL (auto-resolved)
+
+# Other arb tools
 perp --json arb funding                     # detailed funding analysis
 perp --json arb dex                         # HIP-3 cross-dex arb (Hyperliquid)
 perp --json gap show                        # cross-exchange price gaps

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

@@ -173,7 +173,7 @@ Desired size: 1.0
 
 **CRITICAL: Each exchange has its own minimum order size and step size.**
 ```bash
-perp --json -e <EX> market info <SYM>    # check minOrderSize, stepSize
+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.
 

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

@@ -0,0 +1,74 @@
+#!/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
+# Returns JSON with position health + actionable recommendations
+
+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"
+fi
+
+JSON_MODE=false
+MIN_SPREAD=5
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON_MODE=true; shift ;;
+    --min-spread) MIN_SPREAD="$2"; shift 2 ;;
+    *) shift ;;
+  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
+  if $JSON_MODE; then
+    echo '{"ok":false,"error":"No arb positions or arb status unavailable"}'
+  else
+    echo "No open arb positions found."
+  fi
+  exit 0
+fi
+
+# 2. Get current spreads
+ARB_SCAN=$($PERP --json arb scan --min 0 2>/dev/null || echo '{"ok":false,"data":{"opportunities":[]}}')
+
+# 3. Get funding earned
+FUNDING=$($PERP --json arb funding-earned 2>/dev/null || echo '{"ok":false}')
+
+# 4. Get liquidation distances
+LIQ_DIST=$($PERP --json risk liquidation-distance 2>/dev/null || echo '{"ok":false}')
+
+# 5. Output combined analysis
+if $JSON_MODE; then
+  cat <<EOF
+{
+  "ok": true,
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "positions": $ARB_STATUS,
+  "currentSpreads": $ARB_SCAN,
+  "fundingEarned": $FUNDING,
+  "liquidationDistance": $LIQ_DIST,
+  "minSpreadThreshold": $MIN_SPREAD
+}
+EOF
+else
+  echo "=== Arb Position Monitor ==="
+  echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  echo ""
+  echo "--- Positions ---"
+  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."
+fi

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

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Funding rate analysis across all exchanges
+# Usage: ./funding-analysis.sh [--json] [--symbol ETH] [--top 10]
+# Fetches current + historical funding data for comparison
+
+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"
+fi
+
+JSON_MODE=false
+SYMBOL=""
+TOP=10
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON_MODE=true; shift ;;
+    --symbol) SYMBOL="$2"; shift 2 ;;
+    --top) TOP="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+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}')
+
+  if $JSON_MODE; then
+    cat <<EOF
+{
+  "ok": true,
+  "symbol": "$SYMBOL",
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "funding": $FUNDING,
+  "perpPerpArb": $SCAN,
+  "spotPerpArb": $SPOT_SCAN
+}
+EOF
+  else
+    echo "=== Funding Analysis: $SYMBOL ==="
+    echo ""
+    echo "--- Current Funding Rates ---"
+    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"
+    ' 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"
+    ' 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 funding 2>/dev/null || echo '{"ok":false}')
+
+  if $JSON_MODE; then
+    cat <<EOF
+{
+  "ok": true,
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "topN": $TOP,
+  "allOpportunities": $SCAN,
+  "fundingDetail": $FUNDING_DETAIL
+}
+EOF
+  else
+    echo "=== Funding Rate Overview (top $TOP) ==="
+    echo ""
+    echo "$SCAN" | jq -r "
+      .data // [] | .[0:$TOP] | .[] |
+      \"  \(.symbol) | \(.mode // \"perp\") | \(.netSpread // .spread)bps | \(.longExch // .longExchange)→\(.shortExch // .shortExchange)\"
+    " 2>/dev/null || echo "(no data)"
+  fi
+fi