hypurrquant/perp-cli

Multi-DEX perpetual futures CLI — **Pacifica** (Solana), **Hyperliquid** (HyperEVM), **Lighter** (Ethereum), **Aster** (BNB Chain), **Lighter RH** (Robinhood chain), **Ondo Perps** (off-chain), **Arcus** (Robinhood chain), **QFEX** (off-chain, TradFi perps).
Features
- **8 Venues** — trade on Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus, QFEX (bridge / perp-perp arb cover the original four)
- **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
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.
Lighter RH, Ondo Perps, Arcus
These venues have no wallet set private-key path — register an agent / API key instead:
No master wallet on this computer — import a key created on the exchange website
Create the agent / API key on the venue's website, then import it. The master wallet never has to be
on this machine; it is identified only by its public address. The key is read from a hidden prompt or
stdin (never argv) and **checked against the venue before anything is stored** — a refused check stores
nothing; a venue that cannot be checked without the master is reported as unverified, never as verified.
Trading works with the imported key. **Deposits, withdrawals, transfers, bridge, referral set and agent
approvals need the master**: without it they fail with NO_SIGNER_AVAILABLE ("do it on the exchange
website, or add the master with perp wallet import"). The CLI cannot revoke or rotate an imported key —
revoke it on the website; perp wallet agent revoke --local-only removes the local copy,
and wallet agent import --agent-name --replace swaps in a new website-created key.
perp setup offers the same choice per venue: approve with this computer's master wallet, or import a
website-created key (Step 1 can skip the master wallet).
Secrets are stored once (see docs/SSOT_RULES.md Rule #3): Lighter RH → ~/.perp/lighter-rh-agents/, Ondo → ~/.perp/ondo-agents/ .json, Arcus → OWS wallet agent-arcus- ; imported EVM / Solana / Ed25519 keys → OWS wallet agent-{hl,aster,pac,arcus}-import- (empty passphrase, like approved agent wallets), imported Lighter keys → the network-tagged Lighter keystore. A missing wallet/key now fails with KEY_NOT_FOUND / NO_SIGNER_AVAILABLE instead of silently falling back to read-only.
Venues
| Venue | -e id (aliases) | Trading | Notes |
|-------|-------------------|---------|-------|
| Pacifica | pacifica (pac) | yes | Solana |
| Hyperliquid | hyperliquid (hl) | yes | HyperEVM; HIP-3 dexes via --dex |
| Lighter | lighter (lt) | yes | Ethereum L2 |
| Aster | aster (ast) | yes | BNB Chain; funding interval is per symbol |
| Lighter RH | lighter-rh (lrh, rh) | yes | Lighter engine on the Robinhood chain, USDG collateral |
| Ondo Perps | ondo (ondo-perps) | yes | Off-chain engine; limit TIF GTC (default) / IOC / ALO; restricted: US, PA |
| QFEX | qfex (qf) | yes (see **QFEX** below) | Custodial, off-chain engine; equities / indices / commodities, cross margin, USDC; limit TIF GTC (default) / IOC / FOK / ALO; testnet = QFEX UAT; restricted: US, GB, ES and others |
| Arcus | arcus | yes | Robinhood chain, USDG collateral; limit TIF GTC (default, sent as GTT) / IOC / FOK / ALO; restricted: US, CA, GB; **access whitelist** — unlisted addresses are rejected (request access at arcus.xyz) |
- **Time in force:** trade limit defaults to GTC on every venue (common names GTC | IOC | FOK | ALO; a TIF the venue does not offer → CAPABILITY_UNSUPPORTED). Lighter post-only (ALO) is disabled until verified on the venue.
- **TP/SL on an entry:** trade market|buy|sell|limit ... --tp --sl means the same on every venue — *protect this entry's verified fill*. The direction is checked before anything is sent (long: tp > reference > sl; short: the reverse; reference = mark for market entries, the limit price for limit entries). Ondo attaches the legs to the order; Arcus sends an entry+TP/SL batch; Hyperliquid / Lighter / Aster verify the entry fill, then place reduce-only TP/SL trigger orders sized to it (only market or --tif IOC entries — a resting entry → CAPABILITY_UNSUPPORTED); Pacifica verifies the fill, then sets position TP/SL (refused if the symbol already has a position or TP/SL — never overwritten). Entry outcome unknown → ORDER_PENDING and **no** TP/SL (the position may be unprotected); entry filled but a leg failed → ORDER_PARTIAL (not retryable) with the entry result and which legs were placed — do not re-enter, finish with trade tpsl.