perps

Universal CLI for perpetual DEXes.

npm install -g @raintree-technology/perps
perps --help

Install Paths

Canonical install path:

npm install -g @raintree-technology/perps

GitHub install path (for source snapshots and pre-release testing):

npm install github:raintree-technology/perps

The package includes lifecycle build hooks so git installs produce runnable CLI artifacts (dist/) automatically.

Supported Exchanges

| Exchange | Chain | Status | Onboarding | |----------|-------|--------|------------| | Hyperliquid | Arbitrum L2 | Full | Guide | | Aevo | Ethereum | Full | Guide | | Decibel | Aptos L1 | Full | Guide | | Orderly | Arbitrum / Optimism / Polygon / Base | Full | Guide | | Paradex | StarkNet L2 | Full | Guide |

Plus 100+ CEXes via CCXT passthrough and prediction markets via PMXT (Polymarket, Kalshi, Limitless).

Each onboarding guide covers credentials, fees, rate limits, order types, and testnet setup. See the full exchange docs index.

Quick Start

# Interactive setup (testnet by default)
perps setup wizard

# Market data
perps markets ls
perps arb funding BTC
perps arb compare

# Trading
perps order market buy BTC 0.01 --idempotency-key demo-001
perps order limit sell ETH 0.25 3200 --idempotency-key demo-002

# Cross-exchange funding rate arbitrage
perps arb execute BTC -s 1000 --dry-run --yes

# Agent gateway (HTTP API for bots)
perps agent serve
curl http://127.0.0.1:4020/capabilities

# Raw data from any CCXT exchange
perps data ccxt binanceusdm fetchTicker --args '["BTC/USDT:USDT"]' --json

Security Model

Credentials are handled with care:

• Testnet by default — mainnet requires explicit --mainnet flag or *_NETWORK=mainnet env var
• Encrypted at rest — setup flows (including perps setup wizard and perps setup decibel-key) store secrets in an AES-256-GCM local vault (~/.perp/)
• Owner-only permissions — all credential files are chmod 600, directories chmod 700
• Env vars supported — standard HYPERLIQUID_PRIVATE_KEY, AEVO_SIGNING_KEY, etc. for CI/automation
• No telemetry, no phoning home — your keys and trades stay on your machine

Programmatic API

Use perps as a library in your own TypeScript/Node.js projects:

import { HyperliquidAdapter } from "@raintree-technology/perps/adapters"

const hl = new HyperliquidAdapter()
await hl.connect({ testnet: true })

const markets = await hl.getMarkets()
const ticker = await hl.getTicker("BTC-PERP")
const funding = await hl.getFundingRate("ETH-PERP")

await hl.disconnect()

All five adapters implement the same PerpDEXAdapter interface — swap HyperliquidAdapter for AevoAdapter, ParadexAdapter, OrderlyAdapter, or DecibelAdapter and the code works the same.

Authentication

# Recommended: interactive wizard
perps setup wizard

# Decibel key helper: guide + validate + store in encrypted vault (env export optional)
perps setup decibel-key
perps setup decibel-key --env-file .env.local

# Or set env vars directly
export HYPERLIQUID_PRIVATE_KEY="0x..."

| Exchange | Reads | Trading | |----------|-------|---------| | Hyperliquid | HYPERLIQUID_WALLET_ADDRESS | HYPERLIQUID_PRIVATE_KEY | | Aevo | AEVO_API_KEY + AEVO_API_SECRET | + AEVO_SIGNING_KEY | | Decibel | Market data: DECIBEL_API_BEARER_TOKEN; account reads: + DECIBEL_API_WALLET_ADDRESS | + DECIBEL_API_WALLET_PRIVATE_KEY | | Orderly | ORDERLY_ACCOUNT_ID + ORDERLY_KEY + ORDERLY_SECRET | + ORDERLY_TRADING_SECRET | | Paradex | PARADEX_ACCOUNT_ADDRESS + PARADEX_PRIVATE_KEY | same |

Network overrides: HYPERLIQUID_NETWORK, AEVO_NETWORK, DECIBEL_NETWORK, ORDERLY_NETWORK, PARADEX_NETWORK (values: testnet or mainnet).

Capabilities

See CAPABILITIES.md for the full reference — every command, option, exchange feature matrix, adapter interface, and programmatic API.

Command Surface

perps markets --help          # Market data + read commands (ls/get/ticker/tickers/funding-rate/funding-rates)
perps order --help            # Order lifecycle + advanced reads (get/open/trades/position/history/public-trades)
perps arb --help              # Cross-exchange arbitrage
perps account --help          # Portfolio (positions, balances)
perps agent --help            # HTTP agent gateway
perps risk --help             # Risk management (rules, audit, analytics)
perps operator --help         # Kill switch (halt, resume)
perps strategy --help         # Strategy registry
perps signal --help           # Trade signals
perps replay --help           # Execution replay
perps data --help             # Raw exchange data (ccxt, pmxt)
perps setup --help            # Onboarding wizard
perps setup decibel-key --help # Decibel bearer key bootstrap + vault storage
perps config --help           # Settings (show, get, set)
perps doctor                  # Health check

Every command supports --json for machine-readable output and --help for usage details.

Advanced order commands are feature-gated per exchange and exposed directly when supported:

perps order batch-place --help
perps order batch-cancel --help
perps order cancel-all-after --help
perps order mmp --help
perps order twap --help

Agent-friendly mode:

# Non-interactive execution
perps setup wizard --yes --json

# Machine-readable responses with schema version
perps markets ls --json

JSON payloads are schema-versioned, and failures return deterministic exit codes.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 2 | Validation error | | 4 | Auth/credential error | | 5 | Data unavailable | | 6 | No opportunity | | 7 | Execution error | | 8 | Partial execution | | 9 | User cancelled |

Development

git clone https://github.com/raintree-technology/perps.git
cd perps
corepack enable && pnpm install

pnpm dev --help          # Run from source
pnpm test                # Run tests (1600+)
pnpm build               # Compile to dist/
pnpm smoke               # Local health checks
pnpm smoke:network       # + live network reachability

Contributing

See CONTRIBUTING.md for guidelines. Please read our Code of Conduct. For vulnerability reports, see SECURITY.md.

Author

Raintree Technology

License

MIT | Changelog

Disclaimer

This software is provided as-is. Trading perpetual contracts involves substantial risk of loss and is not suitable for every investor. The authors and contributors are not responsible for any financial losses, missed trades, or other damages arising from the use of this software. You are solely responsible for your own trading decisions and for securing your own private keys. Use at your own risk.