perp-cli

Multi-DEX perpetual futures CLI โ Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), Aster (BNB Chain).
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
# Set exchange keys
perp wallet set pac <SOLANA_KEY> # Pacifica
perp wallet set hl <EVM_KEY> # Hyperliquid
perp wallet set lt <EVM_KEY> # Lighter (API key auto-generated)
perp wallet set aster <API_KEY> # 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 <n> 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 |
outcome | Hyperliquid Outcome (HIP-4) โ binary/range contracts, USDH-quoted, no leverage |
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, agent wallets (wallet agent ...), margin mode / subaccount / API keys (wallet manage ...), on-chain balances |
history | Execution log, PnL, performance breakdown |
portfolio | Cross-exchange unified overview (replaces former account balance / status / dashboard) |
health | Adapter health check across all 4 DEX |
settings | CLI settings (referrals, defaults, fees) |
backtest | Strategy backtesting |
background | Background process supervisor (tmux sessions for strategies, alerts, etc.) |
alerts | Funding rate alerts (Telegram / Discord) with background daemon |
setup | Interactive setup wizard (alias: init) |
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
# Outcome markets (Hyperliquid HIP-4 โ fully-collateralized binary contracts, USDH-quoted, $10 min)
perp --json outcome list # active markets + Yes/No mid prices
perp --json outcome view <outcome> # symmetric Yes/No book + underlying gap + expiry
perp --json outcome book <outcome> <side> # one-side orderbook (e.g. '1 yes' or '1 0')
perp --json outcome positions # open outcome holdings
perp --json outcome orders # open outcome orders
perp --json outcome buy <outcome> <side> <usd> --dry-run # validate before submit
perp --json outcome buy <outcome> <side> <usd> # market buy in USDH notional
perp --json outcome sell <outcome> <side> <usd> --limit <px> --tif gtc
perp --json outcome cancel <outcome> <side> <oid>
# 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, bridge, rebalance)
perp --json funds deposit hyperliquid 100
perp --json funds withdraw pacifica 50
perp --json funds transfer 100 <ADDRESS> # 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 <strategy> [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 <SYM> buy <SIZE> 30m
perp --json strategy grid <SYM> --range 5 --grids 10 --size 100
perp strategy plan example # scripted multi-step plan format
perp --json strategy plan validate <FILE> # validate scripted plan
perp --json strategy plan execute <FILE> --dry-run # dry-run scripted plan
# Background process supervisor (tmux)
perp background list # list running jobs
perp background stop <ID> # stop a job
perp background logs <ID> -f # follow logs
Telegram 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 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 <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.