Supports perpetual futures trading, market data access, and account management on Ethereum-based exchanges such as Lighter.
Enables interaction with Solana-based perpetual futures exchanges like Pacifica for trading, portfolio management, and market analysis.
Provides tools to configure and manage automated funding rate alerts via a Telegram bot and background daemon.
Facilitates background job management for long-running trading bots and alert systems using tmux sessions.
perp-cli
Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum).
npm install -g perp-cli # global install
perp --json portfolio
# Or without global install (restricted environments)
npx -y perp-cli --json portfolioFeatures
3 Exchanges — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter
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, CCTP bridge, internal transfer in one group
Bots — TWAP, grid, DCA, trailing-stop with background job management
Agent-First Design —
--json,--fields,--ndjson,--dry-run, runtime schema introspectionSafety — pre-trade validation, response sanitization, client-id deduplication
Setup
# Set exchange keys
perp wallet set hl <EVM_KEY> # Hyperliquid
perp wallet set pac <SOLANA_KEY> # Pacifica
perp wallet set lt <EVM_KEY> # Lighter (API key auto-generated)
# Verify
perp wallet showSame 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 withLIGHTER_API_KEY_INDEXenv var or--key-indexflag onmanage setup-api-key. Valid range: 4–254.
Command Groups
Group | Description |
| Prices, orderbook, funding, klines, HIP-3 dexes |
| Balance, positions, orders, margin |
| Market/limit/stop orders, close, scale, split execution |
| Funding rate arb — scan, exec, close, monitor (perp-perp & spot-perp) |
| TWAP, grid, DCA, trailing-stop bots |
| Deposit, withdraw, transfer, CCTP bridge |
| Cross-chain USDC bridge (deBridge DLN) |
| Risk limits, liquidation distance, guardrails |
| Multi-wallet management & on-chain balances |
| Execution log, PnL, performance breakdown |
| Margin mode, subaccount, API keys, builder |
| Cross-exchange unified overview |
| Live web dashboard |
| CLI settings (referrals, defaults) |
| Strategy backtesting |
| Multi-step composite execution plans |
| Cross-exchange balance management |
| Background job management (tmux) |
| Telegram funding rate alerts with background daemon |
| Schema introspection, capabilities, health check |
Core Commands
# Portfolio (balances + positions + risk across all exchanges)
perp --json portfolio
# Market data
perp --json -e <EX> market list
perp --json -e <EX> market book <SYM>
perp --json -e <EX> market mid <SYM> # fast mid-price lookup
perp --json -e <EX> market funding <SYM>
perp --json -e <EX> market kline <SYM> 1h # candlestick data
perp --json -e hl market hip3 # list HIP-3 deployed dexes
# Trading
perp --json -e <EX> trade buy <SYM> <SIZE> # shortcut for market buy
perp --json -e <EX> trade sell <SYM> <SIZE> # shortcut for market sell
perp --json -e <EX> trade market <SYM> buy <SIZE> --smart # IOC limit (less slippage)
perp --json -e <EX> trade split <SYM> buy 5000 # orderbook-aware split (large orders)
perp --json -e <EX> trade close <SYM>
perp --json -e <EX> trade flatten # close ALL positions on exchange
perp --json -e <EX> trade reduce <SYM> 50 # reduce position by 50%
perp --json -e <EX> trade cancel <SYM> # cancel by symbol (or orderId)
perp --json -e <EX> trade tpsl <SYM> long # set take-profit / stop-loss
perp --json -e <EX> trade leverage <SYM> <N>
# Account
perp --json -e <EX> account balance
perp --json -e <EX> account positions
perp --json -e <EX> account pnl # realized + unrealized + funding
perp --json -e <EX> account funding # personal funding payment history
perp --json -e <EX> 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 <SYM> <longEx> <shortEx> <$> # perp-perp dual-leg entry
perp --json arb exec <SYM> spot:<exch> <perpEx> <$> # spot+perp entry
perp --json arb config # show arb defaults
perp --json arb history # past arb trade performance (alias: log)
# Funds (deposit, withdraw, transfer)
perp --json funds deposit hyperliquid 100
perp --json funds withdraw pacifica 50
perp --json funds transfer 100 <ADDRESS> # HL internal transfer
perp --json funds info # all routes & limits
# Risk
perp --json risk limits --max-leverage 5
perp --json risk liquidation-distance
# Bots
perp --json bot twap <SYM> buy <SIZE> 30m
perp --json bot grid <SYM> --range 5 --grids 10 --size 100
# Bridge (cross-chain USDC)
perp --json bridge quote --from solana --to arbitrum --amount 100
perp --json bridge send --from solana --to arbitrum --amount 100Telegram Alerts
Funding rate alerts via Telegram with background daemon support.
# 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 daemonSetup flow: BotFather token → bot validation → send /start to bot → auto-detect chat ID → test message.
Exchange flag: -e hyperliquid / -e pacifica / -e lighter (aliases: hl, pac, lt).
Global flags: --json, --fields <f>, --ndjson, --dry-run, --dex <name> (HIP-3), -w, --wallet <name>.
MCP Server
perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts) for Claude Desktop, Cursor, and other MCP clients.
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": ["-y", "-p", "perp-cli", "perp-mcp"],
"env": {
"HYPERLIQUID_PRIVATE_KEY": "your-evm-key",
"PACIFICA_PRIVATE_KEY": "your-solana-key"
}
}
}
}Tools: market data, portfolio, orderbook, funding rates, arb scanning, trade preview/execute (with dry-run safety), funding analysis, PnL analysis, arb comparison.
Resources: market://prices, market://funding-rates, perp://schema
Prompts: trading-guide, arb-strategy
AI Agent Skill
Install as a skill for Claude Code, Cursor, Codex, Gemini CLI, etc.:
# Using npx (recommended)
npx skills add hypurrquant/perp-cli
# Or via Claude Code slash command
/install-skill hypurrquant/perp-cliSee skills/perp-cli/SKILL.md for the full agent guide.
Agent-First CLI Design
Built following agent-first CLI principles:
# Every command returns structured JSON envelope
perp --json portfolio
# → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }
# Runtime schema introspection (don't guess commands — query this)
perp --json agent schema
# 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-idAll responses are auto-sanitized (control chars stripped, prompt injection patterns blocked).
Errors include retryable flag — only retry when true.
License
MIT