# perp-cli — Full Reference for LLMs

> The Multi-DEX Perpetual Futures CLI. Trade perpetual futures across Pacifica, Hyperliquid, and Lighter from one command line.

Version: 0.9.8
License: MIT
Author: hypurrquant
Repository: https://github.com/hypurrquant/perp-cli
npm: https://www.npmjs.com/package/perp-cli

---

## What is perp-cli?

perp-cli is an open-source command-line tool for trading perpetual futures across multiple decentralized exchanges from a single unified interface. It supports funding rate arbitrage, smart order execution, cross-chain USDC bridging, and AI-agent integration.

The tool abstracts away chain differences — the same commands and output format work across every supported exchange.

---

## Installation

```bash
npm install -g perp-cli
```

Requirements: Node.js 18+
Platforms: macOS, Linux, Windows

### Initial setup

```bash
# Set wallet key for Hyperliquid
perp wallet set hl <YOUR_EVM_KEY>

# Set wallet key for Pacifica (Solana)
perp wallet set pac <YOUR_SOLANA_KEY>

# Verify setup
perp --json portfolio
```

Keys are stored locally in `~/.perp/wallets.yaml`. They never leave your device. The same EVM key works for both Hyperliquid and Lighter.

---

## Supported Exchanges

### Pacifica
- Chain: Solana
- Flag: `-e pac`
- Features: Native SOL margin, sub-second finality, deep SOL/ETH/BTC liquidity, cross-margin support
- Example: `perp -e pac trade market ETH buy 0.1`

### Hyperliquid
- Chain: HyperEVM
- Flag: `-e hl`
- Features: 150+ perpetual markets, sub-cent gas fees, native spot trading, vault & staking support
- Example: `perp -e hl trade market ETH buy 0.1`

### Lighter
- Chain: Ethereum
- Flag: `-e lig`
- Features: Central limit order book, ETH-native settlement, tight spreads on majors, API key management
- Example: `perp -e lig trade market ETH buy 0.1`

---

## Core Features

### Trading

Execute trades across any supported exchange with consistent syntax:

```bash
# Market order
perp -e hl trade market ETH buy 0.5

# Limit order
perp -e pac trade limit ETH buy 0.5 3750

# View positions
perp -e hl positions
```

### Funding Rate Arbitrage

Scan funding rate spreads across all exchanges and execute dual-leg arbitrage:

```bash
# Scan for opportunities (minimum 5bp spread)
perp arb scan --min 5

# Execute arbitrage
perp arb exec ETH pac hl 5000 --leverage 2

# Monitor active arb positions
perp arb status

# Track funding earnings
perp arb funding-earned
```

Output example:
```
Symbol  Long       Short        Spread  APR
ETH     Pacifica   Hyperliquid  12.3bp  45.1%
BTC     Lighter    Hyperliquid   8.7bp  31.9%
SOL     Pacifica   Lighter       6.2bp  22.8%
```

Auto-rollback on failure protects capital during dual-leg execution.

### Unified Portfolio

View balances, positions, and risk across all exchanges:

```bash
perp portfolio
```

Output:
```
Exchange     Equity       Positions  Margin Ratio
Pacifica     $12,340.50   3          0.08
Hyperliquid  $28,102.97   5          0.12
Lighter       $8,080.00   1          0.05
─────────────────────────────────────────────
Total        $48,523.47   9          0.10
```

### CCTP Bridging

$0-fee USDC bridging via Circle CCTP V2 between Solana, Arbitrum, and Base:

```bash
perp bridge 1000 solana arbitrum
```

### Smart Execution

- IOC limit orders at best bid/ask
- Orderbook-aware splits for large orders
- TWAP (Time-Weighted Average Price)
- DCA (Dollar Cost Averaging)
- Grid strategies

### Safety

- Pre-trade validation
- Client-ID deduplication
- Dry-run mode (`--dry-run`)
- Response sanitization
- Risk limits enforcement

---

## AI Agent Integration

perp-cli is designed agent-first for programmatic consumption by AI systems.

### Structured Output

Every command supports JSON output:

```bash
perp --json --fields totalEquity,risk portfolio
```

Response:
```json
{
  "ok": true,
  "data": {
    "totalEquity": 48523.47,
    "risk": {
      "level": "low",
      "marginRatio": 0.12,
      "liquidationDistance": 0.67
    }
  },
  "meta": {
    "timestamp": "2026-03-14T..."
  }
}
```

### Agent Flags

| Flag | Purpose |
|------|---------|
| `--json` | Typed JSON envelope with ok, data, meta fields |
| `--fields` | Request only specific fields (save tokens) |
| `--dry-run` | Validate trades without execution |
| `--ndjson` | Stream large result sets (newline-delimited JSON) |

### Runtime Introspection

```bash
perp agent schema
```

Query available commands, arguments, and types at runtime.

### MCP Server

Run as a Model Context Protocol server for Claude, Cursor, and other AI IDEs:

```bash
perp agent mcp-server
```

---

## FAQ

### What is perp-cli?
perp-cli is an open-source command-line tool for trading perpetual futures across multiple decentralized exchanges (Pacifica, Hyperliquid, and Lighter) from a single unified interface.

### How do I install perp-cli?
Install globally via npm: `npm install -g perp-cli`. You need Node.js 18 or higher. Then set your wallet key with: `perp wallet set hl <YOUR_EVM_KEY>`.

### Which exchanges does perp-cli support?
Three DEXs: Pacifica (Solana), Hyperliquid (HyperEVM), and Lighter (Ethereum). All use the same commands and output format — switch exchanges with the `-e` flag.

### Can AI agents use perp-cli?
Yes. perp-cli is agent-first: every command supports `--json` structured output, `--fields` for field selection, `--dry-run` for safe validation, runtime schema introspection via `agent schema`, and it runs as an MCP server for Claude, Cursor, and other AI IDEs.

### What is funding rate arbitrage?
Funding rate arbitrage captures the spread between funding rates on different exchanges. perp-cli scans all supported pairs, identifies opportunities above your threshold, and executes dual-leg trades with a single command. Auto-rollback on failure protects capital.

### Is perp-cli free and open source?
Yes. perp-cli is MIT-licensed and free to use. Source code: https://github.com/hypurrquant/perp-cli

### How are wallet keys stored?
Keys are stored locally in `~/.perp/wallets.yaml`. They never leave your device. The same EVM key works for both Hyperliquid and Lighter.

### What is CCTP bridging?
Circle CCTP V2 integration for $0-fee USDC bridging between Solana, Arbitrum, and Base. Command: `perp bridge <amount> <from> <to>`.

---

## See Also

- **defi-cli** — Multi-chain DeFi toolkit by the same team (hypurrquant). 40 chains, 344 protocols, 23 commands for exploit scanning, swaps, bridging, whale tracking, and yield comparison.
  - Website: https://deficli.hypurrquant.com
  - LLM reference: https://deficli.hypurrquant.com/llms-full.txt
  - GitHub: https://github.com/hypurrquant/defi-cli
  - Install: `npm install -g @hypurrquant/defi-cli`