Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hypurrquant/perp-cli

Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid, Lighter (Ethereum). 18 MCP tools for AI-powered trading
https://github.com/hypurrquant/perp-cli

ai-agent arbitrage claude cli defi ethereum funding-rate hyperliquid mcp-server perpetual-futures solana trading-cli

Last synced: 29 days ago
JSON representation

Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid, Lighter (Ethereum). 18 MCP tools for AI-powered trading

Awesome Lists containing this project

README 

          
# perp-cli



[![npm version](https://img.shields.io/npm/v/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)

[![npm downloads](https://img.shields.io/npm/dw/perp-cli.svg)](https://www.npmjs.com/package/perp-cli)

[![license](https://img.shields.io/npm/l/perp-cli.svg)](https://github.com/hypurrquant/perp-cli/blob/main/LICENSE)



Multi-DEX perpetual futures CLI — **Pacifica** (Solana), **Hyperliquid** (HyperEVM), **Lighter** (Ethereum), **Aster** (BNB Chain).



```bash

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



```bash

# Set exchange keys

perp wallet set pac      # Pacifica

perp wallet set hl          # Hyperliquid

perp wallet set lt          # Lighter (API key auto-generated)

perp wallet set aster       # 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 ` 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



```bash

# Portfolio (balances + positions + risk across all exchanges)

perp --json portfolio



# Market data

perp --json -e  market list

perp --json -e  market book 

perp --json -e  market mid               # fast mid-price lookup

perp --json -e  market funding 

perp --json -e  market kline  1h          # candlestick data

perp --json -e hl market hip3                       # list HIP-3 deployed dexes



# Trading

perp --json -e  trade buy            # shortcut for market buy

perp --json -e  trade sell           # shortcut for market sell

perp --json -e  trade market  buy  --smart  # IOC limit (less slippage)

perp --json -e  trade split  buy 5000      # orderbook-aware split (large orders)

perp --json -e  trade close 

perp --json -e  trade flatten                    # close ALL positions on exchange

perp --json -e  trade reduce  50            # reduce position by 50%

perp --json -e  trade cancel                # cancel by symbol (or orderId)

perp --json -e  trade tpsl  long            # set take-profit / stop-loss

perp --json -e  trade leverage  



# Account

perp --json -e  account balance

perp --json -e  account positions

perp --json -e  account pnl                      # realized + unrealized + funding

perp --json -e  account funding                  # personal funding payment history

perp --json -e  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    <$>   # perp-perp dual-leg entry

perp --json arb exec  spot:  <$>  # 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 
             # 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  [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  buy  30m

perp --json strategy grid  --range 5 --grids 10 --size 100

perp strategy plan example                           # scripted multi-step plan format

perp --json strategy plan validate             # validate scripted plan

perp --json strategy plan execute  --dry-run   # dry-run scripted plan



# Background process supervisor (tmux)

perp background list                                 # list running jobs

perp background stop                             # stop a job

perp background logs  -f                         # follow logs



```



## Telegram Alerts



Funding rate alerts via Telegram with background daemon support.



```bash

# 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 `, `--ndjson`, `--dry-run`, `--dex ` (HIP-3), `-w, --wallet `.



## MCP Server



[![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)



perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts) for Claude Desktop, Cursor, and other MCP clients.



**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.



```json

{

  "mcpServers": {

    "perp-cli": {

      "command": "npx",

      "args": ["-y", "-p", "perp-cli", "perp-mcp"]

    }

  }

}

```



Optional: add keys for trading and account data:

```json

{

  "env": {

    "PACIFICA_PRIVATE_KEY": "your-solana-key",

    "HYPERLIQUID_PRIVATE_KEY": "your-evm-key",

    "LIGHTER_PRIVATE_KEY": "your-evm-key",

    "ASTER_API_KEY": "your-api-key"

  }

}

```



**Read-only tools (no keys):** `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `arb_scan`, `health_check`



**Account & trading tools (keys required):** `get_balance`, `get_positions`, `portfolio`, `trade_preview`, `trade_execute`, `trade_close`, `get_funding_analysis`, `get_pnl_analysis`, `get_arb_compare`



**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.:



```bash

# Using npx (recommended)

npx skills add hypurrquant/perp-cli



# Or via Claude Code slash command

/install-skill hypurrquant/perp-cli

```



See [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md) for the full agent guide.



## Agent-First CLI Design



Built following [agent-first CLI principles](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/):



```bash

# Every command returns structured JSON envelope

perp --json portfolio

# → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }



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

```



All responses are auto-sanitized (control chars stripped, prompt injection patterns blocked).

Errors include `retryable` flag — only retry when `true`.



## License



MIT