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 |
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
# 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