npm package: @raintree-technology/perps
Description: Universal CLI for perpetual DEXes
Author: Raintree Technology
Latest version: 0.1.4

# perps

Universal CLI for perpetual DEXes.

[![CI](https://github.com/raintree-technology/perps/actions/workflows/ci.yml/badge.svg)](https://github.com/raintree-technology/perps/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@raintree-technology/perps)](https://www.npmjs.com/package/@raintree-technology/perps)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/node/v/@raintree-technology/perps)](https://nodejs.org)

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

## Install Paths

Canonical install path:

```bash
npm install -g @raintree-technology/perps
```

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

```bash
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](docs/exchanges/hyperliquid.md) |
| Aevo | Ethereum | Full | [Guide](docs/exchanges/aevo.md) |
| Decibel | Aptos L1 | Full | [Guide](docs/exchanges/decibel.md) |
| Orderly | Arbitrum / Optimism / Polygon / Base | Full | [Guide](docs/exchanges/orderly.md) |
| Paradex | StarkNet L2 | Full | [Guide](docs/exchanges/paradex.md) |

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](docs/exchanges/README.md).

## Quick Start

```bash
# 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:

```typescript
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

```bash
# 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..."
```

<details>
<summary>Environment variables by exchange</summary>

| 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`).

</details>

## Capabilities

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

## Command Surface

```bash
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:

```bash
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:

```bash
# 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

```bash
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](CONTRIBUTING.md) for guidelines. Please read our [Code of Conduct](CODE_OF_CONDUCT.md). For vulnerability reports, see [SECURITY.md](SECURITY.md).

## Author

[Raintree Technology](https://raintree.technology)

## License

[MIT](LICENSE) | [Changelog](CHANGELOG.md)

## 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.