perp-cli 0.15.0 → 0.16.0

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 {};

package/dist/cli-spec.js

@@ -1,81 +0,0 @@
-/**
- * Generates a structured CLI spec from Commander's program tree.
- * Internal helper retained for tests; no command surfaces it externally.
- */
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
-const { version: pkgVersion } = require("../package.json");
-function extractCommand(cmd) {
-    const args = cmd._args ?? [];
-    const options = cmd.options.map((opt) => ({
-        flags: opt.flags,
-        description: opt.description ?? "",
-        ...(opt.defaultValue !== undefined ? { default: opt.defaultValue } : {}),
-    }));
-    const subcommands = cmd.commands
-        .filter((sub) => sub.name() !== "help")
-        .map((sub) => extractCommand(sub));
-    return {
-        name: cmd.name(),
-        description: cmd.description(),
-        args: args.map((a) => ({ name: a._name, required: a.required })),
-        options,
-        ...(subcommands.length > 0 ? { subcommands } : {}),
-    };
-}
-export function getCliSpec(program) {
-    const commands = program.commands
-        .filter((cmd) => cmd.name() !== "help")
-        .map((cmd) => extractCommand(cmd));
-    const globalOptions = program.options.map((opt) => ({
-        flags: opt.flags,
-        description: opt.description ?? "",
-        ...(opt.defaultValue !== undefined ? { default: opt.defaultValue } : {}),
-    }));
-    return {
-        name: "perp",
-        version: pkgVersion,
-        description: "Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter)",
-        globalOptions,
-        commands,
-        exchanges: ["pacifica", "hyperliquid", "lighter", "aster"],
-        envelope: {
-            success: "{ ok: true, data: T, meta: { timestamp } }",
-            error: "{ ok: false, error: { code, message, retryable?, retryAfterMs? }, meta: { timestamp } }",
-            example: {
-                ok: true,
-                data: { equity: "10000.00" },
-                meta: { timestamp: "2026-03-08T00:00:00.000Z" },
-            },
-        },
-        errorCodes: {
-            INVALID_PARAMS: { status: 400, retryable: false, description: "Bad arguments or missing fields" },
-            SYMBOL_NOT_FOUND: { status: 404, retryable: false, description: "Market/symbol not found" },
-            ORDER_NOT_FOUND: { status: 404, retryable: false, description: "Order ID not found" },
-            POSITION_NOT_FOUND: { status: 404, retryable: false, description: "No open position for symbol" },
-            INSUFFICIENT_BALANCE: { status: 400, retryable: false, description: "Not enough balance" },
-            MARGIN_INSUFFICIENT: { status: 400, retryable: false, description: "Not enough margin" },
-            SIZE_TOO_SMALL: { status: 400, retryable: false, description: "Below minimum order size" },
-            SIZE_TOO_LARGE: { status: 400, retryable: false, description: "Exceeds maximum order size" },
-            RISK_VIOLATION: { status: 403, retryable: false, description: "Risk limit exceeded" },
-            DUPLICATE_ORDER: { status: 409, retryable: false, description: "Order already submitted" },
-            EXCHANGE_UNREACHABLE: { status: 503, retryable: true, description: "Network/connection failure" },
-            RATE_LIMITED: { status: 429, retryable: true, description: "Too many requests" },
-            PRICE_STALE: { status: 503, retryable: true, description: "Price data outdated" },
-            SIGNATURE_FAILED: { status: 500, retryable: false, description: "Signing/auth error" },
-            EXCHANGE_ERROR: { status: 502, retryable: true, description: "Exchange returned error" },
-            TIMEOUT: { status: 504, retryable: true, description: "Request timed out" },
-            CLI_ERROR: { status: 400, retryable: false, description: "Command parse error" },
-            FATAL: { status: 500, retryable: false, description: "Unrecoverable internal error" },
-            UNKNOWN: { status: 500, retryable: false, description: "Unclassified error" },
-        },
-        tips: [
-            "Always use --json flag for structured output",
-            "All numbers in market/account data are strings to avoid float precision loss",
-            "Check error.retryable before retrying failed commands",
-            "Use 'perp --json trade check <symbol> <side> <size>' to validate before trading",
-            "Use 'perp --json market mid <symbol>' for fast price lookups",
-            "If this CLI is useful, run 'perp -e hyperliquid wallet manage referral set' (or -e lighter; signs one referral action, supports --dry-run) to support development",
-        ],
-    };
-}