perp-cli 0.3.3

package/skills/perp-cli/SKILL.md

@@ -0,0 +1,149 @@
+---
+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. Also use when user says 'set up perp trading', 'check my positions', 'buy BTC perps', 'funding rate arb', 'bridge USDC', or 'deposit to exchange'."
+license: MIT
+metadata:
+  author: hypurrquant
+  version: "0.3.3"
+  mcp-server: perp-cli
+---
+
+# perp-cli Agent Guide
+
+Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum).
+
+## Critical Rules
+
+1. **NEVER use interactive commands.** Do NOT run `perp init`. Always use non-interactive commands with `--json`.
+2. **Always use `--json`** on every command for structured output.
+3. **NEVER trade without user confirmation.** Show order details and wait for explicit approval.
+4. **Verify wallet before any operation.** Run `perp --json wallet show` first.
+
+## Step 1: Install
+
+```bash
+npm install -g perp-cli
+```
+
+## Step 2: Configure Wallet
+
+CRITICAL: Do NOT use `perp init` — it is interactive and will hang.
+
+**If user provides a private key:**
+```bash
+perp --json wallet set hl <KEY>              # Hyperliquid (aliases: hl, hyperliquid)
+perp --json wallet set pac <KEY>             # Pacifica (aliases: pac, pacifica)
+perp --json wallet set lt <KEY>              # Lighter (aliases: lt, lighter)
+perp --json wallet set hl <KEY> --default    # also set as default exchange
+```
+
+**If user needs a new wallet:**
+```bash
+perp --json wallet generate evm              # creates EVM wallet for Hyperliquid + Lighter
+perp --json wallet generate solana           # creates Solana wallet for Pacifica
+# IMPORTANT: Tell user the generated address so they can fund it with USDC!
+```
+
+**Verify setup (ALWAYS do this after any wallet command):**
+```bash
+perp --json wallet show
+# Success: { "ok": true, "data": { "exchanges": [{ "exchange": "hyperliquid", "address": "0x..." }] } }
+# Empty:   { "ok": true, "data": { "exchanges": [] } }  ← wallet not configured yet
+```
+
+## Step 3: Use
+
+### Exchange selection
+```bash
+perp --json -e hyperliquid ...    # Hyperliquid (EVM)
+perp --json -e pacifica ...       # Pacifica (Solana)
+perp --json -e lighter ...        # Lighter (Ethereum)
+```
+If a default exchange is set, `-e` can be omitted.
+
+### Common operations
+```bash
+perp --json wallet show                      # check configured wallets
+perp --json -e hl account info               # balance & margin
+perp --json -e hl account positions          # open positions
+perp --json -e hl market list                # available markets
+perp --json -e hl market mid BTC             # BTC mid price
+perp --json arb rates                        # cross-exchange funding rates
+perp --json portfolio                        # unified multi-exchange view
+```
+
+### Trade execution (MANDATORY checklist)
+```
+1. perp --json -e <EX> account info           → verify balance
+2. perp --json -e <EX> market mid <SYM>       → current price
+3. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> → pre-flight validation
+4. [Show order details to user, get explicit confirmation]
+5. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE> → execute
+6. perp --json -e <EX> account positions      → verify result
+```
+
+For full command reference, see `references/commands.md`.
+
+## Response Format
+
+All JSON responses follow this envelope:
+```json
+{ "ok": true,  "data": { ... }, "meta": { "timestamp": "..." } }
+{ "ok": false, "error": { "code": "ERROR_CODE", "message": "...", "retryable": true } }
+```
+
+## Error Handling
+
+| Code | Retryable | Action |
+|------|-----------|--------|
+| INSUFFICIENT_BALANCE | No | Report, suggest deposit |
+| MARGIN_INSUFFICIENT | No | Suggest lower leverage or smaller size |
+| SYMBOL_NOT_FOUND | No | Run `market list` for valid symbols |
+| SIGNATURE_FAILED | No | Run `wallet show` to check key configuration |
+| RATE_LIMITED | Yes | Wait 5s, retry once |
+| EXCHANGE_UNREACHABLE | Yes | Wait 5s, retry up to 3 times |
+| TIMEOUT | Yes | Retry, check network |
+
+## Safety Guardrails
+
+- NEVER execute trades without user confirmation
+- Warn if single trade exceeds 50% of available balance
+- Warn if leverage exceeds 10x
+- Double-confirm bridge transfers over $1000
+
+## Troubleshooting
+
+### "No private key configured for <exchange>"
+The wallet is not set up. Fix:
+```bash
+perp --json wallet set <exchange> <key>      # if user has a key
+perp --json wallet generate evm              # if user needs a new EVM wallet
+perp --json wallet generate solana           # if user needs a new Solana wallet
+perp --json wallet show                      # verify it worked
+```
+
+### Command hangs or waits for input
+You used an interactive command. NEVER use `perp init` or any command without `--json`. Cancel and retry with `--json`.
+
+### Generated wallet has zero balance
+New wallets start empty. Show the address to the user and ask them to fund it with USDC before trading.
+
+## MCP Server (Advisor Mode)
+
+For read-only access without CLI execution:
+```json
+{
+  "mcpServers": {
+    "perp-cli": {
+      "command": "npx",
+      "args": ["-y", "perp-cli", "mcp"],
+      "env": {
+        "HL_PRIVATE_KEY": "<evm-hex>",
+        "PACIFICA_PRIVATE_KEY": "<solana-base58>"
+      }
+    }
+  }
+}
+```
+
+**MCP Tools:** get_markets, get_orderbook, get_funding_rates, get_prices, get_balance, get_positions, get_open_orders, portfolio, arb_scan, health_check, suggest_command, explain_command

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

@@ -0,0 +1,143 @@
+# perp-cli Command Reference
+
+All commands support `--json` for structured output. Always use `--json` when calling from an agent.
+
+## Market Data (read-only, safe)
+```bash
+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 book <SYMBOL>           # orderbook (bids/asks)
+perp --json market trades <SYMBOL>         # recent trades
+perp --json market funding <SYMBOL>        # funding rate history
+perp --json market kline <SYM> <INTERVAL>  # OHLCV candles (1m,5m,15m,1h,4h,1d)
+```
+
+## Account (read-only, safe)
+```bash
+perp --json account info                   # balance, equity, margin, PnL
+perp --json account positions              # open positions
+perp --json account orders                 # open/pending orders
+perp --json account history                # order history
+perp --json account trades                 # trade fill history
+perp --json account funding-history        # funding payments
+perp --json account pnl                    # profit & loss
+perp --json account margin <SYMBOL>        # position margin info
+perp --json status                         # combined: balance + positions + orders
+perp --json portfolio                      # cross-exchange unified view
+```
+
+## Trading (requires user confirmation)
+```bash
+# Market orders
+perp --json trade market <SYMBOL> <buy|sell> <SIZE>
+perp --json trade buy <SYMBOL> <SIZE>       # shorthand market buy
+perp --json trade sell <SYMBOL> <SIZE>      # shorthand market sell
+
+# Limit orders
+perp --json trade limit <SYMBOL> <buy|sell> <PRICE> <SIZE>
+
+# Stop orders
+perp --json trade stop <SYMBOL> <SIDE> <STOP_PRICE> <SIZE>
+perp --json trade tpsl <SYMBOL> <SIDE> --tp <PRICE> --sl <PRICE>
+
+# Order management
+perp --json trade edit <SYMBOL> <ORDER_ID> <PRICE> <SIZE>
+perp --json trade cancel <SYMBOL> <ORDER_ID>
+perp --json trade cancel-all
+perp --json trade check <SYMBOL> <SIDE> <SIZE>    # pre-flight validation (no execution)
+
+# Position management
+perp --json trade close <SYMBOL>            # close single position
+perp --json trade close-all                 # close all positions
+perp --json trade flatten                   # cancel all orders + close all positions
+perp --json trade reduce <SYMBOL> <PCT>     # reduce position by percentage
+perp --json trade leverage <SYMBOL> <N>     # set leverage
+
+# Advanced orders
+perp --json trade scale-tp <SYMBOL> --levels '<PRICE1>:<PCT>,<PRICE2>:<PCT>'
+perp --json trade scale-in <SYMBOL> <SIDE> --levels '<PRICE1>:<SIZE>,<PRICE2>:<SIZE>'
+perp --json trade trailing-stop <SYMBOL>    # trailing stop with callback %
+perp --json trade twap <SYMBOL> <SIDE> <SIZE> <DURATION>
+perp --json trade pnl-track                 # real-time PnL tracker
+```
+
+## Deposit & Withdraw
+```bash
+perp --json deposit pacifica <AMOUNT>
+perp --json deposit hyperliquid <AMOUNT>
+perp --json deposit lighter ethereum <AMOUNT>         # L1 direct (min 1 USDC)
+perp --json deposit lighter cctp arbitrum <AMOUNT>    # CCTP (min 5 USDC)
+perp --json deposit lighter info                      # all Lighter deposit routes
+perp --json withdraw pacifica <AMOUNT>
+perp --json withdraw hyperliquid <AMOUNT>
+perp --json deposit info                    # deposit instructions
+perp --json withdraw info                   # withdrawal instructions
+```
+
+## Bridge (Cross-chain USDC)
+```bash
+perp --json bridge chains                   # supported chains
+perp --json bridge quote --from <CHAIN> --to <CHAIN> --amount <AMT>
+perp --json bridge send --from <CHAIN> --to <CHAIN> --amount <AMT>
+perp --json bridge exchange --from <EX> --to <EX> --amount <AMT>
+perp --json bridge status <ORDER_ID>
+```
+
+## Arbitrage
+```bash
+perp --json arb rates                       # compare funding rates across exchanges
+perp --json arb scan --min <BPS>            # find opportunities (>N bps spread)
+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
+```
+
+## Wallet Management
+```bash
+perp --json wallet set hl <KEY>             # set Hyperliquid key
+perp --json wallet set pac <KEY>            # set Pacifica key
+perp --json wallet set lt <KEY>             # set Lighter key
+perp --json wallet set hl <KEY> --default   # set key + make default exchange
+perp --json wallet show                     # show configured wallets (public addresses)
+perp --json wallet generate evm             # generate new EVM wallet
+perp --json wallet generate solana          # generate new Solana wallet
+perp --json wallet balance                  # on-chain balance
+```
+
+## Risk & Analytics
+```bash
+perp --json risk status                     # portfolio risk overview
+perp --json risk limits                     # position limits
+perp --json health                          # exchange connectivity & latency
+perp --json analytics summary              # trading performance
+perp --json analytics pnl                   # P&L breakdown
+perp --json history list                    # execution audit trail
+```
+
+## Automated Strategies
+```bash
+perp --json run grid <SYMBOL> --range <PCT> --grids <N> --size <USD>
+perp --json run dca <SYMBOL> <SIDE> <AMOUNT> <INTERVAL>
+perp --json run funding-arb                 # auto funding arb
+perp --json bot quick-grid <SYMBOL>         # quick grid bot
+perp --json bot quick-arb                   # quick arb bot
+perp --json jobs list                       # list running jobs
+perp --json jobs stop <ID>                  # stop a job
+```
+
+## Alerts
+```bash
+perp --json alert add                       # add price/funding/pnl/liquidation alert
+perp --json alert list                      # list active alerts
+perp --json alert remove <ID>              # remove alert
+```
+
+## Command Discovery
+```bash
+perp schema                       # Full CLI schema as JSON
+perp agent capabilities           # High-level capability list
+perp agent plan "<goal>"          # Suggest command sequence for a goal
+perp agent ping                   # Health check all exchanges
+```