# perp-cli [![npm version](https://img.shields.io/npm/v/perp-cli.svg)](https://www.npmjs.com/package/perp-cli) [![npm downloads](https://img.shields.io/npm/dw/perp-cli.svg)](https://www.npmjs.com/package/perp-cli) [![license](https://img.shields.io/npm/l/perp-cli.svg)](https://github.com/hypurrquant/perp-cli/blob/main/LICENSE) Multi-DEX perpetual futures CLI — **Pacifica** (Solana), **Hyperliquid** (HyperEVM), **Lighter** (Ethereum), **Aster** (BNB Chain). ```bash npm install -g perp-cli # global install perp --json portfolio # Or without global install (restricted environments) npx -y perp-cli --json portfolio ``` ## Features - **4 Exchanges** — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter, Aster - **Funding Rate Arb** — perp-perp + spot-perp scan & one-command dual-leg execution - **Portfolio** — single call returns balances, positions, risk level across all exchanges - **Funds** — deposit, withdraw, transfer, multi-provider bridge (cctp/relay/debridge), inter-exchange rebalance — all in one group - **Bots** — TWAP, grid, DCA, trailing-stop with background job management - **Agent-First Design** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection - **Safety** — pre-trade validation, response sanitization, client-id deduplication ## Setup ```bash # Set exchange keys perp wallet set pac # Pacifica perp wallet set hl # Hyperliquid perp wallet set lt # Lighter (API key auto-generated) perp wallet set aster # Aster (BNB Chain) # Or interactive setup wizard perp setup # Verify perp wallet show ``` Same EVM key works for both Hyperliquid and Lighter. > **Lighter API Key Index:** Indexes 0–3 are reserved by Lighter's frontend (web/mobile). perp-cli defaults to index `4`. Override with `LIGHTER_API_KEY_INDEX` env var, or use `perp wallet agent approve lighter --api-key-index ` for managed agent slots. Valid range: 4–254. ## Command Groups | Group | Description | |-------|-------------| | `market` | Prices, orderbook, funding, klines, HIP-3 dexes | | `account` | Balance, positions, orders, margin | | `trade` | Market/limit/stop orders, close, scale, split execution | | `arb` | Funding rate arb — scan, exec, close, monitor (perp-perp & spot-perp) | | `strategy` | 19 bot algorithms (grid, dca, twap, APEX, REFLECT, presets) + nested scripted plans | | `funds` | Deposit, withdraw, transfer, cross-chain bridge (multi-provider), inter-exchange rebalance | | `risk` | Risk limits, liquidation distance, guardrails | | `wallet` | Multi-wallet management & on-chain balances | | `history` | Execution log, PnL, performance breakdown | | `manage` | Margin mode, subaccount, API keys, builder | | `portfolio` | Cross-exchange unified overview | | `dashboard` | Live web dashboard | | `settings` | CLI settings (referrals, defaults) | | `backtest` | Strategy backtesting | | `background` | Background process supervisor (tmux sessions for strategies, alerts, etc.) | | `alerts` | Telegram funding rate alerts with background daemon | | `agent` | Schema introspection, capabilities, health check | | `setup` | Interactive setup wizard (alias: `init`) | | `status` | Unified dashboard: balances, positions, arb opps | ## Core Commands ```bash # Portfolio (balances + positions + risk across all exchanges) perp --json portfolio # Market data perp --json -e market list perp --json -e market book perp --json -e market mid # fast mid-price lookup perp --json -e market funding perp --json -e market kline 1h # candlestick data perp --json -e hl market hip3 # list HIP-3 deployed dexes # Trading perp --json -e trade buy # shortcut for market buy perp --json -e trade sell # shortcut for market sell perp --json -e trade market buy --smart # IOC limit (less slippage) perp --json -e trade split buy 5000 # orderbook-aware split (large orders) perp --json -e trade close perp --json -e trade flatten # close ALL positions on exchange perp --json -e trade reduce 50 # reduce position by 50% perp --json -e trade cancel # cancel by symbol (or orderId) perp --json -e trade tpsl long # set take-profit / stop-loss perp --json -e trade leverage # Account perp --json -e account balance perp --json -e account positions perp --json -e account pnl # realized + unrealized + funding perp --json -e account funding # personal funding payment history perp --json -e account settings # per-market leverage & margin mode # Funding rate arbitrage perp --json arb scan --min 5 # perp-perp opportunities perp --json arb scan --mode spot-perp # spot+perp opportunities perp --json arb scan --rates # funding rates across all exchanges perp --json arb scan --basis # cross-exchange basis opportunities perp --json arb scan --gaps # cross-exchange price gaps perp --json arb scan --hip3 # HIP-3 cross-dex funding spreads perp --json arb scan --live # continuous live monitoring perp --json arb exec <$> # perp-perp dual-leg entry perp --json arb exec spot: <$> # spot+perp entry perp --json arb config # show arb defaults perp --json arb history # past arb trade performance (alias: log) # Funds (deposit, withdraw, transfer, bridge, rebalance) perp --json funds deposit hyperliquid 100 perp --json funds withdraw pacifica 50 perp --json funds transfer 100
# HL internal transfer (instant) perp --json funds bridge quote --from solana --to arbitrum --amount 100 perp --json funds bridge send --from solana --to arbitrum --amount 100 # auto-cheapest provider perp --json funds bridge exchange --from pacifica --to hyperliquid --amount 100 perp --json funds rebalance check # balances across exchanges perp --json funds rebalance plan # compute optimal moves perp --json funds rebalance execute --auto-bridge # withdraw → bridge → deposit perp --json funds info # all routes & limits # Risk perp --json risk limits --max-leverage 5 perp --json risk liquidation-distance # Strategies (19 bot algorithms + nested scripted plans) perp strategy list-strategies # list all available strategies perp strategy run [symbol] # run any strategy perp strategy apex [symbol] # APEX autonomous orchestrator perp strategy reflect # trading performance analysis perp strategy preset-list # list strategy presets perp --json strategy twap buy 30m perp --json strategy grid --range 5 --grids 10 --size 100 perp strategy plan example # scripted multi-step plan format perp --json strategy plan validate # validate scripted plan perp --json strategy plan execute --dry-run # dry-run scripted plan # Background process supervisor (tmux) perp background list # list running jobs perp background stop # stop a job perp background logs -f # follow logs ``` ## Telegram Alerts Funding rate alerts via Telegram with background daemon support. ```bash # Interactive setup (BotFather token + chat ID auto-detection) perp alerts setup # Add alert rules perp alerts add ETH 30 # alert when ETH funding > 30% annualized perp alerts add --all 50 # alert for any symbol > 50% # Test & manage perp alerts test # send test message perp alerts list # show active rules # Run daemon perp alerts start # foreground perp alerts start --background # tmux background daemon perp alerts stop # stop background daemon ``` Setup flow: BotFather token → bot validation → send `/start` to bot → auto-detect chat ID → test message. Exchange flag: `-e hyperliquid` / `-e pacifica` / `-e lighter` / `-e aster` (aliases: `hl`, `pac`, `lt`). Global flags: `--json`, `--fields `, `--ndjson`, `--dry-run`, `--dex ` (HIP-3), `-w, --wallet `. ## MCP Server [![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli) perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts) for Claude Desktop, Cursor, and other MCP clients. **No API keys required for market data** — explore prices, orderbooks, funding rates, and arb opportunities without any setup. Add keys only when you want to trade. ```json { "mcpServers": { "perp-cli": { "command": "npx", "args": ["-y", "-p", "perp-cli", "perp-mcp"] } } } ``` Optional: add keys for trading and account data: ```json { "env": { "PACIFICA_PRIVATE_KEY": "your-solana-key", "HYPERLIQUID_PRIVATE_KEY": "your-evm-key", "LIGHTER_PRIVATE_KEY": "your-evm-key", "ASTER_API_KEY": "your-api-key" } } ``` **Read-only tools (no keys):** `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `arb_scan`, `health_check` **Account & trading tools (keys required):** `get_balance`, `get_positions`, `portfolio`, `trade_preview`, `trade_execute`, `trade_close`, `get_funding_analysis`, `get_pnl_analysis`, `get_arb_compare` **Resources:** `market://prices`, `market://funding-rates`, `perp://schema` **Prompts:** `trading-guide`, `arb-strategy` ## AI Agent Skill Drop-in skill for Claude Code, Cursor, Codex, Gemini CLI, and other agent CLIs. Bundles a non-interactive command guide, ops playbook, strategy framework, and reusable shell scripts (preflight, arb monitor, validation) so your agent stops at the right confirmation points and never wedges on interactive wizards. ### Install ```bash # Claude Code — slash command /install-skill hypurrquant/perp-cli # Cursor / Codex / generic agent CLIs — via npx npx skills add hypurrquant/perp-cli # Manual install (any agent that reads a Skills directory) git clone https://github.com/hypurrquant/perp-cli.git cp -R perp-cli/skills/perp-cli ~/.claude/skills/ # or your CLI's skills dir ``` The skill ships inside the npm package (`perp-cli/skills/perp-cli`), so a global install also makes it available locally: ```bash npm install -g perp-cli@latest ls "$(npm root -g)/perp-cli/skills/perp-cli" ``` ### What's in the skill | File | Purpose | |------|---------| | `SKILL.md` | Top-level agent guide — rules, workflows, examples | | `references/commands.md` | Full non-interactive command reference (every group) | | `references/agent-operations.md` | Setup flows, idempotency, error handling, common mistakes | | `references/strategies.md` | Funding-arb decision framework + risk management | | `scripts/preflight.sh` | Install + wallet + connectivity + risk readiness check | | `scripts/arb-monitor.sh` | Live monitor for open arb positions | | `scripts/spot-perp-scan.sh` | Scan spot+perp opportunities with balance context | | `scripts/funding-analysis.sh` | Cross-exchange funding overview / per-symbol drilldown | | `scripts/validate-arb.sh` | Pre-execution validation (price / balance / risk / dry-run) | See [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md) for the full agent guide. ## Agent-First CLI Design Built following [agent-first CLI principles](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/): ```bash # Every command returns structured JSON envelope perp --json portfolio # → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } } # Filter output to specific fields (saves tokens) perp --json --fields totalEquity,risk portfolio # Stream large lists as NDJSON (one JSON per line) perp --json --ndjson -e hl market list # Pre-validate before executing perp --json -e hl trade check BTC buy 0.01 perp --json --dry-run -e hl trade market BTC buy 0.01 # Idempotent orders with client ID perp --json -e hl trade market BTC buy 0.01 --client-id my-unique-id ``` All responses are auto-sanitized (control chars stripped, prompt injection patterns blocked). Errors include `retryable` flag — only retry when `true`. ## License MIT