{"id":46821113,"url":"https://github.com/hypurrquant/perp-cli","last_synced_at":"2026-05-01T23:04:50.531Z","repository":{"id":343131559,"uuid":"1176407372","full_name":"hypurrquant/perp-cli","owner":"hypurrquant","description":" Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid, Lighter (Ethereum). 18 MCP tools for AI-powered trading","archived":false,"fork":false,"pushed_at":"2026-04-29T18:13:50.000Z","size":2485,"stargazers_count":25,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T19:31:27.842Z","etag":null,"topics":["ai-agent","arbitrage","claude","cli","defi","ethereum","funding-rate","hyperliquid","mcp-server","perpetual-futures","solana","trading-cli"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hypurrquant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T01:47:45.000Z","updated_at":"2026-04-28T03:25:24.000Z","dependencies_parsed_at":"2026-04-02T12:09:29.582Z","dependency_job_id":null,"html_url":"https://github.com/hypurrquant/perp-cli","commit_stats":null,"previous_names":["hypurrquant/perp-cli"],"tags_count":119,"template":false,"template_full_name":null,"purl":"pkg:github/hypurrquant/perp-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypurrquant%2Fperp-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypurrquant%2Fperp-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypurrquant%2Fperp-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypurrquant%2Fperp-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypurrquant","download_url":"https://codeload.github.com/hypurrquant/perp-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypurrquant%2Fperp-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32515839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","arbitrage","claude","cli","defi","ethereum","funding-rate","hyperliquid","mcp-server","perpetual-futures","solana","trading-cli"],"created_at":"2026-03-10T09:03:34.899Z","updated_at":"2026-05-01T23:04:50.515Z","avatar_url":"https://github.com/hypurrquant.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# perp-cli\n\n[![npm version](https://img.shields.io/npm/v/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)\n[![npm downloads](https://img.shields.io/npm/dw/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)\n[![license](https://img.shields.io/npm/l/perp-cli.svg)](https://github.com/hypurrquant/perp-cli/blob/main/LICENSE)\n\nMulti-DEX perpetual futures CLI — **Pacifica** (Solana), **Hyperliquid** (HyperEVM), **Lighter** (Ethereum), **Aster** (BNB Chain).\n\n```bash\nnpm install -g perp-cli       # global install\nperp --json portfolio\n\n# Or without global install (restricted environments)\nnpx -y perp-cli --json portfolio\n```\n\n## Features\n\n- **4 Exchanges** — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter, Aster\n- **Funding Rate Arb** — perp-perp + spot-perp scan \u0026 one-command dual-leg execution\n- **Portfolio** — single call returns balances, positions, risk level across all exchanges\n- **Funds** — deposit, withdraw, transfer, multi-provider bridge (cctp/relay/debridge), inter-exchange rebalance — all in one group\n- **Bots** — TWAP, grid, DCA, trailing-stop with background job management\n- **Agent-First Design** — `--json`, `--fields`, `--ndjson`, `--dry-run`, runtime schema introspection\n- **Safety** — pre-trade validation, response sanitization, client-id deduplication\n\n## Setup\n\n```bash\n# Set exchange keys\nperp wallet set pac \u003cSOLANA_KEY\u003e     # Pacifica\nperp wallet set hl \u003cEVM_KEY\u003e         # Hyperliquid\nperp wallet set lt \u003cEVM_KEY\u003e         # Lighter (API key auto-generated)\nperp wallet set aster \u003cAPI_KEY\u003e      # Aster (BNB Chain)\n\n# Or interactive setup wizard\nperp setup\n\n# Verify\nperp wallet show\n```\n\nSame EVM key works for both Hyperliquid and Lighter.\n\n\u003e **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 \u003cn\u003e` for managed agent slots. Valid range: 4–254.\n\n## Command Groups\n\n| Group | Description |\n|-------|-------------|\n| `market` | Prices, orderbook, funding, klines, HIP-3 dexes |\n| `account` | Balance, positions, orders, margin |\n| `trade` | Market/limit/stop orders, close, scale, split execution |\n| `arb` | Funding rate arb — scan, exec, close, monitor (perp-perp \u0026 spot-perp) |\n| `strategy` | 19 bot algorithms (grid, dca, twap, APEX, REFLECT, presets) + nested scripted plans |\n| `funds` | Deposit, withdraw, transfer, cross-chain bridge (multi-provider), inter-exchange rebalance |\n| `risk` | Risk limits, liquidation distance, guardrails |\n| `wallet` | Multi-wallet management \u0026 on-chain balances |\n| `history` | Execution log, PnL, performance breakdown |\n| `manage` | Margin mode, subaccount, API keys, builder |\n| `portfolio` | Cross-exchange unified overview |\n| `dashboard` | Live web dashboard |\n| `settings` | CLI settings (referrals, defaults) |\n| `backtest` | Strategy backtesting |\n| `background` | Background process supervisor (tmux sessions for strategies, alerts, etc.) |\n| `alerts` | Telegram funding rate alerts with background daemon |\n| `agent` | Schema introspection, capabilities, health check |\n| `setup` | Interactive setup wizard (alias: `init`) |\n| `status` | Unified dashboard: balances, positions, arb opps |\n\n## Core Commands\n\n```bash\n# Portfolio (balances + positions + risk across all exchanges)\nperp --json portfolio\n\n# Market data\nperp --json -e \u003cEX\u003e market list\nperp --json -e \u003cEX\u003e market book \u003cSYM\u003e\nperp --json -e \u003cEX\u003e market mid \u003cSYM\u003e              # fast mid-price lookup\nperp --json -e \u003cEX\u003e market funding \u003cSYM\u003e\nperp --json -e \u003cEX\u003e market kline \u003cSYM\u003e 1h          # candlestick data\nperp --json -e hl market hip3                       # list HIP-3 deployed dexes\n\n# Trading\nperp --json -e \u003cEX\u003e trade buy \u003cSYM\u003e \u003cSIZE\u003e          # shortcut for market buy\nperp --json -e \u003cEX\u003e trade sell \u003cSYM\u003e \u003cSIZE\u003e         # shortcut for market sell\nperp --json -e \u003cEX\u003e trade market \u003cSYM\u003e buy \u003cSIZE\u003e --smart  # IOC limit (less slippage)\nperp --json -e \u003cEX\u003e trade split \u003cSYM\u003e buy 5000      # orderbook-aware split (large orders)\nperp --json -e \u003cEX\u003e trade close \u003cSYM\u003e\nperp --json -e \u003cEX\u003e trade flatten                    # close ALL positions on exchange\nperp --json -e \u003cEX\u003e trade reduce \u003cSYM\u003e 50            # reduce position by 50%\nperp --json -e \u003cEX\u003e trade cancel \u003cSYM\u003e               # cancel by symbol (or orderId)\nperp --json -e \u003cEX\u003e trade tpsl \u003cSYM\u003e long            # set take-profit / stop-loss\nperp --json -e \u003cEX\u003e trade leverage \u003cSYM\u003e \u003cN\u003e\n\n# Account\nperp --json -e \u003cEX\u003e account balance\nperp --json -e \u003cEX\u003e account positions\nperp --json -e \u003cEX\u003e account pnl                      # realized + unrealized + funding\nperp --json -e \u003cEX\u003e account funding                  # personal funding payment history\nperp --json -e \u003cEX\u003e account settings                 # per-market leverage \u0026 margin mode\n\n# Funding rate arbitrage\nperp --json arb scan --min 5                         # perp-perp opportunities\nperp --json arb scan --mode spot-perp                # spot+perp opportunities\nperp --json arb scan --rates                         # funding rates across all exchanges\nperp --json arb scan --basis                         # cross-exchange basis opportunities\nperp --json arb scan --gaps                          # cross-exchange price gaps\nperp --json arb scan --hip3                          # HIP-3 cross-dex funding spreads\nperp --json arb scan --live                          # continuous live monitoring\nperp --json arb exec \u003cSYM\u003e \u003clongEx\u003e \u003cshortEx\u003e \u003c$\u003e   # perp-perp dual-leg entry\nperp --json arb exec \u003cSYM\u003e spot:\u003cexch\u003e \u003cperpEx\u003e \u003c$\u003e  # spot+perp entry\nperp --json arb config                               # show arb defaults\nperp --json arb history                              # past arb trade performance (alias: log)\n\n# Funds (deposit, withdraw, transfer, bridge, rebalance)\nperp --json funds deposit hyperliquid 100\nperp --json funds withdraw pacifica 50\nperp --json funds transfer 100 \u003cADDRESS\u003e             # HL internal transfer (instant)\nperp --json funds bridge quote --from solana --to arbitrum --amount 100\nperp --json funds bridge send --from solana --to arbitrum --amount 100   # auto-cheapest provider\nperp --json funds bridge exchange --from pacifica --to hyperliquid --amount 100\nperp --json funds rebalance check                    # balances across exchanges\nperp --json funds rebalance plan                     # compute optimal moves\nperp --json funds rebalance execute --auto-bridge    # withdraw → bridge → deposit\nperp --json funds info                               # all routes \u0026 limits\n\n# Risk\nperp --json risk limits --max-leverage 5\nperp --json risk liquidation-distance\n\n# Strategies (19 bot algorithms + nested scripted plans)\nperp strategy list-strategies                        # list all available strategies\nperp strategy run \u003cstrategy\u003e [symbol]                # run any strategy\nperp strategy apex [symbol]                          # APEX autonomous orchestrator\nperp strategy reflect                                # trading performance analysis\nperp strategy preset-list                            # list strategy presets\nperp --json strategy twap \u003cSYM\u003e buy \u003cSIZE\u003e 30m\nperp --json strategy grid \u003cSYM\u003e --range 5 --grids 10 --size 100\nperp strategy plan example                           # scripted multi-step plan format\nperp --json strategy plan validate \u003cFILE\u003e            # validate scripted plan\nperp --json strategy plan execute \u003cFILE\u003e --dry-run   # dry-run scripted plan\n\n# Background process supervisor (tmux)\nperp background list                                 # list running jobs\nperp background stop \u003cID\u003e                            # stop a job\nperp background logs \u003cID\u003e -f                         # follow logs\n\n```\n\n## Telegram Alerts\n\nFunding rate alerts via Telegram with background daemon support.\n\n```bash\n# Interactive setup (BotFather token + chat ID auto-detection)\nperp alerts setup\n\n# Add alert rules\nperp alerts add ETH 30              # alert when ETH funding \u003e 30% annualized\nperp alerts add --all 50            # alert for any symbol \u003e 50%\n\n# Test \u0026 manage\nperp alerts test                    # send test message\nperp alerts list                    # show active rules\n\n# Run daemon\nperp alerts start                   # foreground\nperp alerts start --background      # tmux background daemon\nperp alerts stop                    # stop background daemon\n```\n\nSetup flow: BotFather token → bot validation → send `/start` to bot → auto-detect chat ID → test message.\n\nExchange flag: `-e hyperliquid` / `-e pacifica` / `-e lighter` / `-e aster` (aliases: `hl`, `pac`, `lt`).\n\nGlobal flags: `--json`, `--fields \u003cf\u003e`, `--ndjson`, `--dry-run`, `--dex \u003cname\u003e` (HIP-3), `-w, --wallet \u003cname\u003e`.\n\n## MCP Server\n\n[![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)\n\nperp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts) for Claude Desktop, Cursor, and other MCP clients.\n\n**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.\n\n```json\n{\n  \"mcpServers\": {\n    \"perp-cli\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"perp-cli\", \"perp-mcp\"]\n    }\n  }\n}\n```\n\nOptional: add keys for trading and account data:\n```json\n{\n  \"env\": {\n    \"PACIFICA_PRIVATE_KEY\": \"your-solana-key\",\n    \"HYPERLIQUID_PRIVATE_KEY\": \"your-evm-key\",\n    \"LIGHTER_PRIVATE_KEY\": \"your-evm-key\",\n    \"ASTER_API_KEY\": \"your-api-key\"\n  }\n}\n```\n\n**Read-only tools (no keys):** `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `arb_scan`, `health_check`\n\n**Account \u0026 trading tools (keys required):** `get_balance`, `get_positions`, `portfolio`, `trade_preview`, `trade_execute`, `trade_close`, `get_funding_analysis`, `get_pnl_analysis`, `get_arb_compare`\n\n**Resources:** `market://prices`, `market://funding-rates`, `perp://schema`\n\n**Prompts:** `trading-guide`, `arb-strategy`\n\n## AI Agent Skill\n\nInstall as a skill for Claude Code, Cursor, Codex, Gemini CLI, etc.:\n\n```bash\n# Using npx (recommended)\nnpx skills add hypurrquant/perp-cli\n\n# Or via Claude Code slash command\n/install-skill hypurrquant/perp-cli\n```\n\nSee [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md) for the full agent guide.\n\n## Agent-First CLI Design\n\nBuilt following [agent-first CLI principles](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/):\n\n```bash\n# Every command returns structured JSON envelope\nperp --json portfolio\n# → { \"ok\": true, \"data\": {...}, \"meta\": { \"timestamp\": \"...\" } }\n\n# Filter output to specific fields (saves tokens)\nperp --json --fields totalEquity,risk portfolio\n\n# Stream large lists as NDJSON (one JSON per line)\nperp --json --ndjson -e hl market list\n\n# Pre-validate before executing\nperp --json -e hl trade check BTC buy 0.01\nperp --json --dry-run -e hl trade market BTC buy 0.01\n\n# Idempotent orders with client ID\nperp --json -e hl trade market BTC buy 0.01 --client-id my-unique-id\n```\n\nAll responses are auto-sanitized (control chars stripped, prompt injection patterns blocked).\nErrors include `retryable` flag — only retry when `true`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypurrquant%2Fperp-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypurrquant%2Fperp-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypurrquant%2Fperp-cli/lists"}