# perp-cli Command Reference All commands support `--json` for structured output. Always use `--json` when calling from an agent. ## Global Flags `--json` (required for agents) | `-e ` (exchange) | `--dex ` (HIP-3) | `-w, --wallet ` | `--dry-run` | `--fields ` | `--ndjson` ## Market Data (read-only, safe) ```bash perp --json -e market list # all markets with prices, funding, volume perp --json market prices # cross-exchange price comparison perp --json -e market mid # mid price (fast) perp --json -e market info # mark/index price, funding, volume, OI, max leverage perp --json -e market book # orderbook (bids/asks) perp --json -e market trades # recent trades perp --json -e market funding # funding rate history perp --json -e market kline # OHLCV candles (1m,5m,15m,1h,4h,1d) perp --json market hip3 # list HIP-3 deployed perp dexes (Hyperliquid) ``` ## Account (read-only, safe) ```bash perp --json -e account balance # perp balance + spot holdings + 24h funding perp --json -e account positions # open positions perp --json -e account orders # open/pending orders perp --json -e account history # order history perp --json -e account trades # trade fill history perp --json -e account funding-history # funding payments perp --json -e account settings # per-market leverage & margin mode perp --json -e account margin # position margin info perp --json -e account pnl # realized + unrealized + funding perp --json -e account twap-orders # active TWAP orders perp --json portfolio # cross-exchange unified view perp --json portfolio --arb # full dashboard with arb top 5 ``` ## Trading (requires user confirmation) ```bash # Market orders perp --json -e trade market perp --json -e trade buy # shorthand market buy perp --json -e trade sell # shorthand market sell perp --json -e trade buy --smart # IOC limit at best ask (less slippage) # Split execution (orderbook-aware, for large orders) perp --json -e trade split perp --json -e trade split buy 5000 --max-slippage 0.5 --max-slices 5 --delay 2000 --min-slice 200 perp --json -e trade market buy --split # split via flag # Limit / stop / TPSL perp --json -e trade limit perp --json -e trade stop perp --json -e trade tpsl --tp

--sl

# Order management perp --json -e trade edit perp --json -e trade cancel [orderId] perp --json -e trade cancel-all perp --json -e trade cancel-stop perp --json -e trade cancel-twap perp --json -e trade status # check order state perp --json -e trade fills [SYMBOL] # recent fills # Pre-flight validation perp --json -e trade check perp --json -e trade check --leverage 3 # NOTE: trade check does NOT read exchange-set leverage. Always pass --leverage explicitly. # Position management perp --json -e trade close # close single position perp --json -e trade close-all # close all positions perp --json -e trade flatten # cancel all orders + close all positions perp --json -e trade reduce # reduce by percentage perp --json -e trade leverage [--isolated] # Advanced orders perp --json -e trade scale-tp --levels ':,:' perp --json -e trade scale-in --levels ':,:' perp --json -e trade pnl-track # real-time PnL tracker perp --json trade twap # native TWAP order # Spot helpers (Hyperliquid / Lighter) perp --json -e trade spot-buy perp --json -e trade spot-sell perp --json -e trade spot-balance # Multi-leg atomic execution perp --json trade multi ``` ## Funds (deposit, withdraw, transfer, bridge, rebalance) All fund movement lives under `perp funds`. ### Exchange in/out ```bash perp --json funds deposit pacifica perp --json funds deposit hyperliquid perp --json funds deposit lighter ethereum # L1 direct (min 1 USDC) perp --json funds deposit lighter cctp arbitrum # CCTP (min 5 USDC) perp --json funds deposit lighter info # all Lighter deposit routes perp --json funds withdraw pacifica perp --json funds withdraw hyperliquid perp --json funds withdraw lighter perp --json funds transfer

# HL internal transfer (instant) perp --json funds info # combined routes & limits ``` ### Cross-chain bridge (multi-provider router: cctp / relay / debridge — auto-cheapest) ```bash perp --json funds bridge chains # supported chains perp --json funds bridge quote --from --to --amount perp --json funds bridge send --from --to --amount perp --json funds bridge send --from --to --amount --provider cctp perp --json funds bridge exchange --from --to --amount # between exchanges perp --json funds bridge status ``` ### Inter-exchange rebalance (orchestrated withdraw → bridge → deposit) ```bash 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 rebalance execute --withdraw-only # only withdraw, manual rest ``` ## Arbitrage All scan modes are routed through `arb scan`. Legacy aliases (`arb rates`, `arb prices`, `arb dex`, `arb spot-exec`, `arb spot-close`) are removed. ```bash # Scan (read-only, safe) perp --json arb scan # default --mode all (perp-perp + spot-perp) perp --json arb scan --mode perp-perp --min 10 # perp-only with min annual % perp --json arb scan --mode spot-perp --min 10 # spot+perp only perp --json arb scan --rates # funding rates across exchanges perp --json arb scan --basis [SYMBOL] # cross-exchange basis perp --json arb scan --gaps # cross-exchange price gaps perp --json arb scan --hip3 # HIP-3 cross-dex spreads perp --json arb scan --history [SYMBOL] # historical funding perp --json arb scan --compare # compare a symbol across exchanges perp --json arb scan --positions # position funding impact perp --json arb scan --live --interval 60 # continuous monitoring perp --json arb scan --top 10 --hold-days 7 --bridge-cost 0 --size 100 # cost-aware filtering # Execute (perp-perp or spot+perp via spot: prefix) perp --json arb exec # perp-perp dual-leg entry perp --json arb exec spot:hl hl # spot+perp via HL spot perp --json arb exec spot:lt pac # spot+perp via LT spot perp --json arb exec \ --leverage 2 --isolated --smart --reconcile --max-slippage 0.5 # Close perp --json arb close # close perp-perp arb perp --json arb close --pair : # disambiguate by pair perp --json arb close --spot-exch hl --perp-exch hl # close spot+perp legs perp --json arb close --smart # IOC limits at best price # Status / history / config / rebalance perp --json arb status # open arb positions + PnL + funding earned perp --json arb status --period 7 --symbol BTC # filter funding lookback / symbol perp --json arb history # alias: arb log perp --json arb history --period 30 # past arb trade performance perp --json arb config # show arb defaults perp --json arb rebalance --check # cross-exchange balance distribution perp --json arb rebalance --target 50:50 --amount 1000 --dry-run # Auto-execute daemon perp --json arb auto --min-spread 30 --close-spread 5 --size 100 --max-positions 5 perp --json arb auto --background # tmux session perp --json arb auto --hip3 --min-oi 50000 --min-grade C # HIP-3 mode perp --json arb auto --dry-run # simulate ``` ## Wallet Management ```bash perp --json wallet generate evm # generate EVM wallet perp --json wallet generate solana # generate Solana wallet perp --json wallet import [privateKey] # import an existing key perp --json wallet set hl # set Hyperliquid key perp --json wallet set pac # set Pacifica key perp --json wallet set lt # set Lighter key (auto-generates API key) perp --json wallet set aster # set Aster API key perp --json wallet set hl --default # set + make default exchange perp --json wallet show # public addresses for active wallet perp --json wallet list # all named wallets perp --json wallet use # set active wallet perp --json wallet rename perp --json wallet remove perp --json wallet balance # on-chain USDC balances perp --json wallet solana
# check arbitrary Solana address perp --json wallet arbitrum
# check arbitrary Arbitrum address perp --json wallet migrate # migrate legacy ~/.perp/.env config perp --json wallet rotate # rotate keys + transfer assets perp --json wallet backup # encrypted backup perp --json wallet restore # restore from backup perp --json wallet deposit # deposit prompt for a stored wallet perp --json wallet setup # **interactive — DO NOT use from agent** ``` ### Agent wallet (DEX-side delegation) ```bash perp --json wallet agent approve [--master ] [--api-key-index ] perp --json wallet agent list [exchange] perp --json wallet agent revoke perp --json wallet agent rotate [oldAgentName] perp --json wallet agent verify [exchange] [agentName] ``` ### Exchange settings (`wallet manage`) ```bash perp --json wallet manage margin perp --json wallet manage withdraw
# generic on-exchange withdraw perp --json wallet manage account-mode [standard|big-blocks] # Hyperliquid only perp --json wallet manage sub create perp --json wallet manage sub list perp --json wallet manage sub transfer perp --json wallet manage lake create perp --json wallet manage lake deposit perp --json wallet manage lake withdraw perp --json wallet manage builder approve perp --json wallet manage builder revoke perp --json wallet manage builder list perp --json wallet manage builder overview perp --json wallet manage builder trades perp --json wallet manage builder leaderboard perp --json wallet manage builder update-fee perp --json wallet manage referral claim # Pacifica perp --json wallet manage apikey create perp --json wallet manage apikey list perp --json wallet manage apikey revoke ``` ### OWS (Open Wallet Standard) API key + policy — optional, scoped agent tokens ```bash perp --json wallet key create perp --json wallet key list perp --json wallet key revoke perp --json wallet policy create perp --json wallet policy list perp --json wallet policy show perp --json wallet policy delete ``` ## Risk & Analytics ```bash perp --json risk status # portfolio risk overview (level, violations, canTrade) perp --json risk health # health-check summary perp --json risk liquidation-distance # % distance from liquidation for ALL positions perp --json risk limits # view current risk limits perp --json risk limits --min-liq-distance 30 --max-leverage 5 # set risk limits perp --json risk check --notional 1000 --leverage 3 # pre-trade risk check ``` ## History (execution log + analytics) ```bash perp --json history list # execution audit trail perp --json history stats # aggregated execution stats perp --json history positions # position lifetime tracking perp --json history prune # purge old entries perp --json history summary # trading performance summary perp --json history pnl # P&L breakdown by exchange perp --json history funding # funding payment aggregation perp --json history report # full performance report (summary + pnl + funding) perp --json history compare # compare strategies / accounts perp --json history snapshot # equity snapshot perp --json history track # PnL tracking helper perp --json history perf --period daily # daily PnL breakdown perp --json history perf --period weekly # weekly PnL breakdown perp --json history perf --period summary # performance summary stats ``` ## Strategies (`perp strategy` — 20 algorithms + nested scripted plans) ```bash perp --json strategy list-strategies # list all 20 strategies perp --json strategy run [SYMBOL] # run any registered strategy perp --json strategy run funding-auto # multi-exchange funding arb perp --json strategy apex [SYMBOL] # APEX orchestrator perp --json strategy reflect # performance analysis perp --json strategy preset-list perp --json strategy preset [SYMBOL] perp --json strategy start # YAML/JSON config-driven perp --json strategy quick-grid perp --json strategy quick-dca perp --json strategy quick-arb perp --json strategy delta-neutral perp --json strategy twap perp --json strategy grid --range --grids --size perp --json strategy dca perp --json strategy trailing-stop perp --json strategy funding-arb # legacy alias for run funding-arb # Scripted execution plans (one-shot multi-step) perp --json strategy plan example perp --json strategy plan validate perp --json strategy plan execute --dry-run ``` ### Available Strategies (20) - **Market Making:** `simple-mm`, `engine-mm`, `avellaneda-mm`, `regime-mm`, `grid-mm`, `liquidation-mm` - **Signal/Directional:** `momentum-breakout`, `mean-reversion`, `aggressive-taker` - **Arbitrage:** `funding-arb`, `funding-arb-v2`, `funding-auto`, `basis-arb`, `spot-perp-arb` - **Infrastructure:** `hedge-agent`, `rfq-agent`, `claude-agent` - **Classic:** `grid`, `dca`, `apex` ## Background Process Supervisor (tmux) ```bash perp --json background list # list running jobs (default subcommand) perp --json background stop # stop a job perp --json background logs # view logs (use -f to follow) perp --json background remove # remove a job entry perp --json background clean # purge all stopped/done jobs ``` ## Backtest ```bash perp --json backtest funding-arb # backtest funding arb on historical data perp --json backtest grid # backtest grid strategy ``` ## Alerts (Telegram / Discord) ```bash perp alerts setup # interactive setup wizard perp --json alerts test # send test message perp --json alerts add # add alert rule perp --json alerts add --all # alert for any symbol > N% perp --json alerts list # list active rules perp --json alerts remove # remove a rule perp alerts start [--background] # run daemon (tmux for background) perp alerts stop # stop background daemon ``` ## Settings ```bash perp --json settings show # show current CLI settings perp --json settings set # set a CLI default perp --json settings referrals on|off # toggle referral codes perp --json settings fees show # cached exchange fee table perp --json settings fees sync # refresh fee cache perp --json settings env show # show ~/.perp/.env values perp --json settings env set perp --json settings env remove perp --json settings env path # config file path ``` ## Init / Setup ```bash perp init # interactive — DO NOT use from agent perp setup # alias for init — DO NOT use from agent ``` Use `perp wallet set ` instead — non-interactive and agent-safe.