perp-cli 0.4.2 → 0.4.8

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

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

@@ -0,0 +1,98 @@
+#!/bin/bash
+# Pre-flight validation for perp-cli operations
+# Checks: install, wallet, connectivity, balances, risk
+# Usage: ./preflight.sh [--json]
+# Returns JSON with { ready: bool, checks: [...], issues: [...] }
+
+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
+[[ "${1:-}" == "--json" ]] && JSON_MODE=true
+
+issues=()
+checks=()
+
+add_check() {
+  local name="$1" status="$2" detail="$3"
+  checks+=("{\"name\":\"$name\",\"status\":\"$status\",\"detail\":\"$detail\"}")
+  [[ "$status" == "fail" ]] && issues+=("$name: $detail")
+}
+
+# 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'))"
+else
+  add_check "install" "fail" "perp-cli not found — run: 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
+  add_check "wallet" "pass" "Wallet configured"
+else
+  add_check "wallet" "fail" "No wallet configured — run: perp wallet set <exchange> <key>"
+fi
+
+# 3. Exchange connectivity
+HEALTH_OUT=$($PERP --json health 2>/dev/null || echo '{"ok":false}')
+if echo "$HEALTH_OUT" | grep -q '"ok":true'; then
+  add_check "connectivity" "pass" "Exchanges reachable"
+else
+  add_check "connectivity" "warn" "Some exchanges 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
+  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
+  add_check "risk" "pass" "Trading allowed (canTrade=true)"
+elif echo "$RISK_OUT" | grep -q '"canTrade":false'; then
+  add_check "risk" "fail" "Trading blocked — check risk violations"
+else
+  add_check "risk" "warn" "Could not check risk status"
+fi
+
+# Output
+READY=true
+[[ ${#issues[@]} -gt 0 ]] && READY=false
+
+if $JSON_MODE; then
+  CHECKS_JSON=$(IFS=,; echo "${checks[*]}")
+  ISSUES_JSON=$(printf '%s\n' "${issues[@]}" | jq -R . | jq -s .)
+  echo "{\"ready\":$READY,\"checks\":[$CHECKS_JSON],\"issues\":$ISSUES_JSON}"
+else
+  echo "=== perp-cli Pre-flight Check ==="
+  for c in "${checks[@]}"; do
+    name=$(echo "$c" | jq -r .name)
+    status=$(echo "$c" | jq -r .status)
+    detail=$(echo "$c" | jq -r .detail)
+    case "$status" in
+      pass) icon="✓" ;;
+      warn) icon="⚠" ;;
+      fail) icon="✗" ;;
+    esac
+    printf "  %s %-15s %s\n" "$icon" "$name" "$detail"
+  done
+  echo ""
+  if $READY; then
+    echo "Ready to trade."
+  else
+    echo "Issues found:"
+    for i in "${issues[@]}"; do echo "  - $i"; done
+  fi
+fi

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

@@ -0,0 +1,83 @@
+#!/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
+
+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
+MODE="all"
+MIN_SPREAD=10
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON_MODE=true; shift ;;
+    --mode) MODE="$2"; shift 2 ;;
+    --min) MIN_SPREAD="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+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
+  if $JSON_MODE; then
+    echo '{"ok":false,"error":"Cannot fetch portfolio — check wallet setup"}'
+  else
+    echo "ERROR: Cannot fetch portfolio. Check wallet setup first."
+  fi
+  exit 1
+fi
+
+# 2. Run appropriate scan
+SCAN_RESULT=$($PERP --json arb scan --mode "$MODE" --min "$MIN_SPREAD" 2>/dev/null || echo '{"ok":false}')
+
+# 3. Get exchange health for context
+HEALTH=$($PERP --json health 2>/dev/null || echo '{"ok":false}')
+
+if $JSON_MODE; then
+  cat <<EOF
+{
+  "ok": true,
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "mode": "$MODE",
+  "minSpread": $MIN_SPREAD,
+  "portfolio": $PORTFOLIO,
+  "scan": $SCAN_RESULT,
+  "health": $HEALTH
+}
+EOF
+else
+  echo "=== Spot+Perp Arb Scanner ==="
+  echo "Mode: $MODE | Min spread: ${MIN_SPREAD} bps"
+  echo ""
+
+  # Show balances
+  echo "--- Balances ---"
+  echo "$PORTFOLIO" | jq -r '
+    .data.exchanges // [] | .[] |
+    "  \(.exchange): $\(.balance // .equity // "N/A")"
+  ' 2>/dev/null || echo "  (unable to parse)"
+  echo ""
+
+  # Show opportunities
+  echo "--- Opportunities ---"
+  echo "$SCAN_RESULT" | jq -r '
+    .data // [] | .[] |
+    "  \(.symbol) | \(.mode // "perp-perp") | spread: \(.netSpread // .spread)bps | \(.longExch // .longExchange)→\(.shortExch // .shortExchange)"
+  ' 2>/dev/null || echo "  (no opportunities or parse error)"
+
+  # 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)"
+fi

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

@@ -0,0 +1,112 @@
+#!/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
+# Returns JSON validation report
+
+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
+
+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>}"
+SIZE="${4:?Usage: validate-arb.sh <SYMBOL> <LONG_EX> <SHORT_EX> <SIZE_USD>}"
+LEVERAGE=""
+
+shift 4
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --leverage) LEVERAGE="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+checks=()
+pass=true
+
+add_result() {
+  local name="$1" ok="$2" detail="$3"
+  checks+=("{\"check\":\"$name\",\"ok\":$ok,\"detail\":\"$detail\"}")
+  [[ "$ok" == "false" ]] && pass=false
+}
+
+# 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"')
+
+if [[ "$LONG_PRICE" == "0" || "$SHORT_PRICE" == "0" ]]; then
+  add_result "price" "false" "Cannot fetch price: long=$LONG_PRICE short=$SHORT_PRICE"
+else
+  # Check deviation
+  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"
+  else
+    add_result "price" "true" "long=$LONG_PRICE short=$SHORT_PRICE dev=${DEVIATION}%"
+  fi
+fi
+
+# 2. Balance check on both exchanges
+LONG_BAL=$($PERP --json -e "$LONG_EX" account info 2>/dev/null | jq -r '.data.available // .data.equity // "0"')
+SHORT_BAL=$($PERP --json -e "$SHORT_EX" account info 2>/dev/null | jq -r '.data.available // .data.equity // "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"
+else
+  add_result "balance_short" "true" "$SHORT_EX balance=$SHORT_BAL"
+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}')
+
+if echo "$LONG_INFO" | grep -q '"ok":true' && echo "$SHORT_INFO" | grep -q '"ok":true'; 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
+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
+  add_result "risk" "true" "Within risk limits"
+else
+  add_result "risk" "false" "Risk check failed — review risk limits"
+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
+  add_result "dry_run" "true" "Dry-run succeeded"
+else
+  DRY_ERR=$(echo "$DRY_RUN" | jq -r '.error.message // .error // "unknown"' 2>/dev/null)
+  add_result "dry_run" "false" "Dry-run failed: $DRY_ERR"
+fi
+
+# Output
+CHECKS_JSON=$(IFS=,; echo "${checks[*]}")
+cat <<EOF
+{
+  "ok": true,
+  "symbol": "$SYM",
+  "longExchange": "$LONG_EX",
+  "shortExchange": "$SHORT_EX",
+  "sizeUsd": $SIZE,
+  "allPassed": $pass,
+  "checks": [$CHECKS_JSON]
+}
+EOF

package/skills/perp-cli/templates/arb-scan.sh

@@ -1,15 +0,0 @@
-#!/bin/bash
-# Scan funding rate arbitrage opportunities
-# Usage: ./arb-scan.sh [min-spread-bps]
-# Example: ./arb-scan.sh 20
-
-set -e
-
-MIN_SPREAD="${1:-10}"
-
-echo "=== Funding Rate Arbitrage Scanner ==="
-echo "Minimum spread: ${MIN_SPREAD} bps"
-echo ""
-
-echo "1. Opportunities (>= ${MIN_SPREAD} bps):"
-perp --json arb scan --min "$MIN_SPREAD"

package/skills/perp-cli/templates/open-position.sh

@@ -1,38 +0,0 @@
-#!/bin/bash
-# Open a perp position with pre-flight checks
-# Usage: ./open-position.sh <exchange> <symbol> <side> <size>
-# Example: ./open-position.sh hl BTC buy 0.01
-
-set -e
-
-EX="${1:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
-SYM="${2:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
-SIDE="${3:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
-SIZE="${4:?Usage: open-position.sh <exchange> <symbol> <side> <size>}"
-
-echo "=== Pre-flight checks ==="
-echo "1. Account info:"
-perp --json -e "$EX" account info
-
-echo "2. Current price:"
-perp --json -e "$EX" market mid "$SYM"
-
-echo "3. Trade validation:"
-perp --json -e "$EX" trade check "$SYM" "$SIDE" "$SIZE"
-
-echo ""
-echo "=== Ready to execute ==="
-echo "  Exchange: $EX"
-echo "  Symbol:   $SYM"
-echo "  Side:     $SIDE"
-echo "  Size:     $SIZE"
-echo ""
-read -p "Confirm? (y/N): " CONFIRM
-
-if [ "$CONFIRM" = "y" ] || [ "$CONFIRM" = "Y" ]; then
-  perp --json -e "$EX" trade market "$SYM" "$SIDE" "$SIZE"
-  echo "=== Position verification ==="
-  perp --json -e "$EX" account positions
-else
-  echo "Cancelled."
-fi

package/skills/perp-cli/templates/wallet-setup.sh

@@ -1,17 +0,0 @@
-#!/bin/bash
-# Wallet setup for perp-cli
-# Usage: ./wallet-setup.sh <exchange> <private-key>
-# Exchanges: hl (Hyperliquid), pac (Pacifica), lt (Lighter)
-
-set -e
-
-EXCHANGE="${1:?Usage: wallet-setup.sh <exchange> <private-key>}"
-KEY="${2:?Usage: wallet-setup.sh <exchange> <private-key>}"
-
-echo "Setting up wallet for $EXCHANGE..."
-perp --json wallet set "$EXCHANGE" "$KEY"
-
-echo "Verifying..."
-perp --json wallet show
-
-echo "Done. Wallet configured for $EXCHANGE."