npm install -g perp-cli

perp --json wallet generate evm              # creates EVM wallet for Hyperliquid + Lighter
perp --json wallet generate solana           # creates Solana wallet for Pacifica

undefined

perp --json wallet set hl <EVM_PRIVATE_KEY>        # register EVM key → ready to trade immediately
perp --json wallet show                            # verify
perp --json -e hl account info                     # check balance

perp --json wallet set pac <SOLANA_PRIVATE_KEY>    # register Solana key → ready to trade immediately
perp --json wallet show                            # verify
perp --json -e pac account info                    # check balance

perp --json wallet set lt <EVM_PRIVATE_KEY>        # register EVM key

Same EVM key can be used for both Hyperliquid and Lighter:
```bash
perp --json wallet set hl <KEY>                    # same key
perp --json wallet set lt <KEY>                    # same key, different exchange binding

perp --json -e lighter manage setup-api-key        # manual retry

perp --json wallet show

undefined

perp --json -e hyperliquid ...    # Hyperliquid (EVM)
perp --json -e pacifica ...       # Pacifica (Solana)
perp --json -e lighter ...        # Lighter (Ethereum)

perp --json wallet show                      # check configured wallets
perp --json portfolio                        # unified multi-exchange view
perp --json arb scan --min 5                 # find funding arb opportunities (>5bps spread)

undefined

**All 3 exchanges are fully operational.** Do NOT say any exchange "requires additional setup" or "is not available" — if `wallet show` shows it configured, it's ready to trade.

arb scan returns: longExch, shortExch, netSpread
→ ALWAYS follow longExch/shortExch exactly. NEVER reverse the direction.
→ NEVER enter if netSpread ≤ 0 (= loss after fees)
→ Positive funding = longs pay shorts → be SHORT to receive
→ Negative funding = shorts pay longs → be LONG to receive

BEFORE ANY TRADE:
0. perp --json portfolio                       → check TOTAL equity + per-exchange balances
   - Single position notional < 25% of TOTAL equity
   - Each exchange MUST have sufficient balance for its leg
   - Notional ≠ margin required. Check available balance on EACH exchange.
   - If balance is insufficient, bridge first or reduce size.

1. perp --json risk status                     → check risk level (STOP if critical)
2. perp --json -e <EX> account info            → verify EXCHANGE-SPECIFIC balance
3. perp --json -e <EX> market mid <SYM>        → current price
4. perp --json -e <EX> trade leverage <SYM> <N> --isolated → set leverage + isolated margin FIRST
5. perp --json risk check --notional <$> --leverage <L> → risk pre-check
6. perp --json -e <EX> trade check <SYM> <SIDE> <SIZE> --leverage <L> → trade validation
   ⚠ trade check does NOT read exchange-set leverage. ALWAYS pass --leverage explicitly.
7. [Show order details + risk assessment to user, get explicit confirmation]
8. perp --json -e <EX> trade market <SYM> <SIDE> <SIZE>  → execute
9. perp --json -e <EX> account positions       → verify result + check liquidation price

Minimum order values (notional, enforced by exchange):
  - Hyperliquid: $10 minimum per order
  - Pacifica: varies by symbol (usually ~$1)
  - Lighter: varies by symbol

If your calculated size falls below the minimum, increase to meet it or skip the opportunity.
trade check returns valid: true/false but is ADVISORY — it does NOT block execution.
The exchange itself will reject orders below its minimum.

For funding arb, BOTH legs must have the EXACT SAME SIZE. Size mismatch = directional exposure.

1. Check orderbook depth on BOTH exchanges:
   perp --json -e <LONG_EX> market book <SYM>    → asks (you're buying)
   perp --json -e <SHORT_EX> market book <SYM>   → bids (you're selling)

2. Compute ORDER_SIZE:
   - fillable_long = sum of ask sizes at best 2-3 levels
   - fillable_short = sum of bid sizes at best 2-3 levels
   - ORDER_SIZE = min(fillable_long, fillable_short, desired_size)
   - Must be ≥ BOTH exchanges' minimum order value (e.g. HL requires ≥$10 notional)

3. Execute BOTH legs with the SAME ORDER_SIZE:
   perp --json -e <LONG_EX> trade market <SYM> buy <ORDER_SIZE>
   → verify fill via account positions
   perp --json -e <SHORT_EX> trade market <SYM> sell <ORDER_SIZE>
   → verify fill via account positions

4. Confirm matched: both positions must show identical size.
   If mismatch (partial fill), adjust the larger to match the smaller.

Every 15 minutes:
  perp --json risk status                      → overall risk level + violations
  perp --json risk liquidation-distance        → % from liq price for ALL positions
  perp --json -e <EX> account positions        → check each position P&L

Every 1 hour (at funding settlement):
  perp --json arb scan --min 5                  → is spread still profitable?
  perp --json portfolio                        → total equity across exchanges
  Compare both legs' unrealized P&L — they should roughly offset

Exit triggers:
  - Spread below breakeven (including fees) → show exit plan, get user approval
  - risk status level = "critical" or canTrade = false → reduce immediately
  - One leg closed unexpectedly → close the other leg IMMEDIATELY
  - Target hold duration reached → re-evaluate or exit

perp --json wallet show                        → configured wallets + addresses
perp --json wallet balance                     → on-chain USDC (in wallet, NOT on exchange)
perp --json -e <EX> account info               → exchange balance (available for trading)
perp --json portfolio                          → unified view: equity, margin, P&L per exchange

{ "ok": true,  "data": { ... }, "meta": { "timestamp": "..." } }
{ "ok": false, "error": { "code": "ERROR_CODE", "message": "...", "retryable": true } }

perp --json wallet set <exchange> <key>      # if user has a key
perp --json wallet generate evm              # if user needs a new EVM wallet
perp --json wallet generate solana           # if user needs a new Solana wallet
perp --json wallet show                      # verify it worked

{
  "mcpServers": {
    "perp-cli": {
      "command": "npx",
      "args": ["-y", "perp-cli", "mcp"],
      "env": {
        "HL_PRIVATE_KEY": "<evm-hex>",
        "PACIFICA_PRIVATE_KEY": "<solana-base58>"
      }
    }
  }
}