README.md
Multi-DEX perpetual futures trading MCP server
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 portfolio
Features
- 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 introspection - Safety — 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 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 withLIGHTER_API_KEY_INDEXenv var or--key-indexflag onmanage setup-api-key. 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) |
bot |
19 strategies, APEX orchestrator, REFLECT analytics, presets |
funds |
Deposit, withdraw, transfer, CCTP bridge |
bridge |
Cross-chain USDC bridge (deBridge DLN) |
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 |
plan |
Multi-step composite execution plans |
rebalance |
Cross-exchange balance management |
jobs |
Background job management (tmux) |
alerts |
Telegram funding rate alerts with background daemon |
agent |
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 -
Tools (5)
marketAccess market data including prices, orderbooks, funding rates, and klines.tradeExecute market, limit, and stop orders with support for advanced strategies.accountRetrieve balance, positions, PnL, and margin settings.arbScan and execute funding rate arbitrage opportunities.portfolioGet a unified overview of balances, positions, and risk across all exchanges.Environment Variables
LIGHTER_API_KEY_INDEXOverride the default Lighter API key index (4-254).Configuration
claude_desktop_config.json
{"mcpServers": {"perp-cli": {"command": "npx", "args": ["-y", "perp-cli", "--json"]}}}Try it
→Get a unified portfolio overview across all connected exchanges.
→Scan for current funding rate arbitrage opportunities between perp markets.
→Check the current mid-price and orderbook for ETH on Hyperliquid.
→Close all open positions on the Pacifica exchange.
→Set a take-profit and stop-loss for my current BTC long position.