Perp Cli README

English | 한국어 | 中文 | 日本語

perp-cli

One CLI for perpetual futures across many DEXs — trade, compare funding, move funds and run bots from the terminal, or hand it to an AI agent (JSON output, MCP server, agent skill).

• Trade on 10 venues: Hyperliquid (incl. HIP-3 dexes), Pacifica, Lighter, Lighter RH, Aster, Ondo Perps, Arcus, QFEX, RISEx, TxFlow (bridge and perp-perp arb cover the original four: Pacifica, Hyperliquid, Lighter, Aster)
• Market data only: GRVT, Extended, Variational — plus Derive options data

Install

npm install -g perp-cli
perp --version

# Or without a global install
npx -y perp-cli --json portfolio

The package ships three executables: perp (the CLI), perp-mcp (the MCP server, stdio) and perp-guardrail (the signing guardrail).

Quick start

1. Look around — no keys needed.

perp -e hl market list                  # markets, prices, funding
perp -e hl market book BTC              # order book
perp arb scan --rates                   # funding rates across venues

2. Add a wallet. The setup wizard creates or imports an encrypted OWS vault wallet, picks venues and registers agent keys (it asks before every signature and never moves funds):

perp setup
perp wallet show

Keys are read from a hidden prompt or stdin — never from argv or ~/.perp/.env. One EVM key covers Hyperliquid, Lighter and Aster. For other paths (one-line key import, scriptable setup, keys created on the exchange website) see docs/setup.md.

3. Check your account and trade. Add -n testnet to any command to use testnet.

perp --json portfolio                                 # balances + positions + risk on every venue
perp --json --dry-run -e hl trade market BTC buy 0.001   # validate only, nothing is sent
perp --json -e hl trade market BTC buy 0.001          # market order (bounded by the slippage setting)
perp --json -e hl trade close BTC

AI Agent Skill

Drop-in skill for Claude Code, Cursor, Codex, Gemini CLI, and other agent CLIs. Bundles a non-interactive command guide, ops playbook, strategy framework, and reusable shell scripts (preflight, arb monitor, validation) so your agent stops at the right confirmation points and never wedges on interactive wizards.

Install

# Claude Code — slash command
/install-skill hypurrquant/perp-cli

# Cursor / Codex / generic agent CLIs — via npx
npx skills add hypurrquant/perp-cli

# Manual install (any agent that reads a Skills directory)
git clone https://github.com/hypurrquant/perp-cli.git
cp -R perp-cli/skills/perp-cli ~/.claude/skills/        # or your CLI's skills dir

The skill ships inside the npm package (perp-cli/skills/perp-cli), so a global install also makes it available locally:

npm install -g perp-cli@latest
ls "$(npm root -g)/perp-cli/skills/perp-cli"

What's in the skill

See skills/perp-cli/SKILL.md for the full agent guide.

Features

• Funding rate arb — perp-perp and spot-perp scans, one-command dual-leg entry and exit
• Portfolio — one call returns balances, positions and risk across every venue
• Funds — deposit, withdraw, transfer, multi-provider bridge (CCTP / Relay / deBridge), inter-exchange rebalance
• Bots — TWAP, grid, DCA, trailing stop and more, with background job management
• Agent-first — --json, --fields, --ndjson, --dry-run, runtime schema introspection
• Safety — pre-trade validation, a slippage bound on every market order, client-id deduplication, response sanitization

Venues

• Support matrix and per-venue notes — funding, WebSocket, deposit / withdraw, lookups by address, restricted regions
• Mainnet verification — which features have been run with real money
• Trading details — time in force, TP/SL, stops, slippage, spot trading, builder fees

Common commands

# Market data
perp --json -e <EX> market list | book <SYM> | funding <SYM> | kline <SYM> 1h

# Trading
perp --json -e <EX> trade buy <SYM> <SIZE> --tp <PX> --sl <PX>    # entry protected by TP/SL
perp --json -e <EX> trade limit <SYM> buy <PX> <SIZE>
perp --json -e <EX> trade close <SYM>                              # or: flatten (every position)

# Account
perp --json portfolio
perp --json -e <EX> account positions
perp --json account balance --address <ADDR>                       # any account, keyless

# Funding arb
perp --json arb scan --min 5
perp --json arb exec <SYM> <longEx> <shortEx> <USD>

# Funds
perp --json funds deposit hyperliquid 100
perp --json funds bridge send --from solana --to arbitrum --amount 100

Full list with every group: docs/commands.md. Global flags: --json, --fields <f>, --ndjson, --dry-run, -n testnet, -e <venue>, --dex <name> (HIP-3), -w, --wallet <name>.

Command Groups

Agent-First CLI Design

Built following agent-first CLI principles:

# 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 (Hyperliquid: a 128-bit cloid, 0x + 32 hex; --auto-id generates one)
perp --json -e hl trade market BTC buy 0.01 --client-id 0x1234567890abcdef1234567890abcdef
perp --json -e hl trade status c:0x1234567890abcdef1234567890abcdef

All responses are auto-sanitized (control chars stripped, prompt injection patterns blocked). Errors include retryable flag — only retry when true.

MCP Server

perp-mcp serves 31 tools to Claude Desktop, Cursor and other MCP clients. Market data needs no keys; for account and trading tools run perp setup first (the server reads the same wallet). Never put private keys in the MCP config.

{
  "mcpServers": {
    "perp-cli": {
      "command": "npx",
      "args": ["-y", "-p", "perp-cli", "perp-mcp"]
    }
  }
}

Testnet, the full tool list, resources and prompts: docs/mcp.md.

Documentation

License

MIT