Universal CLI for Perpetual DEXes

This article documents the private v0.1.4 build from February 2026. Commands and capabilities may change before another public release.

Perps is a TypeScript and Node.js CLI for perpetual DEX market data, execution, and automation.

The goal is simple: one command surface for data, trading, risk, and automation across multiple exchanges, without building a new integration every time.

Why we built this perpetual DEX CLI

Perp infrastructure is fragmented.

• Every exchange has different auth models and APIs.
• Teams rebuild the same market-data, order, and risk plumbing repeatedly.
• Automation becomes brittle when command output is inconsistent.

Perps standardizes that layer with a single CLI and adapter interface.

What shipped in v0.1.4

The package is more than a command wrapper around one exchange. It has five layers:

Layer	Responsibility
CLI	Human and scriptable commands for markets, accounts, orders, arbitrage, risk, and operations
Native adapters	A shared interface across Hyperliquid, Aevo, Decibel, Orderly, and Paradex
Raw connectors	Direct CCXT calls for 100+ exchange venues and PMXT calls for prediction markets
Local runtime	Encrypted credentials, configuration, SQLite-backed state, execution journals, and background data processes
Automation	JSON responses, stable exit codes, an HTTP agent gateway, strategies, signals, and execution replay

The package exposes two binaries: perps for the main command surface and perps-server for the background WebSocket server. It also exports the adapters as a TypeScript library.

There is no public installation path while the project remains in private development.

One interface, five native adapters

Every native adapter implements the same PerpDEXAdapter contract. That contract covers connection setup, markets, tickers, funding rates, balances, positions, orders, trades, and exchange capabilities. The point is not to pretend every venue works identically. It is to give callers one stable shape while each adapter reports which optional actions it can actually perform.

Adapter	Network family in the v0.1.4 package	Role
Hyperliquid	Hyperliquid	Native market data, account, and order workflows
Aevo	Ethereum ecosystem	Native market data and trading workflows
Decibel	Aptos	REST, WebSocket, account, and order workflows
Orderly	EVM networks	Native account and order workflows across supported Orderly networks
Paradex	Starknet	Native market data, account, and order workflows

Advanced actions are capability-gated. Batch placement, batch cancellation, TWAP, market-maker protection, isolated-margin adjustment, and cancel-all-after only appear where the adapter has direct support. This keeps an unsupported action from silently falling back to a different behavior.

Quick start

# Guided onboarding (testnet by default)
perps setup wizard

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

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

# Funding-rate arbitrage dry run
perps arb execute BTC -s 1000 --dry-run --yes

# Raw connector data without a new native adapter
perps data ccxt binanceusdm fetchTicker --args '["BTC/USDT:USDT"]' --json

The arbitrage commands split discovery from execution. funding scans rates, compare puts venues side by side, and execute prepares the paired trade. The --dry-run path is the experimental mode: it resolves the venues, sizes, and intended actions without sending live orders.

Agent-first automation for trading bots

Perps was designed for both humans and automation systems.

• --json across command groups for machine-readable output
• Schema-versioned payloads
• Deterministic non-zero exit codes for failure classes
• Idempotency keys on execution commands
• HTTP agent gateway (perps agent serve) for bot integration

That makes it practical to wire into scripted workflows, evaluators, and autonomous agents.

You can quickly inspect gateway capabilities with:

perps agent serve
curl http://127.0.0.1:4020/capabilities

The gateway exposes its capabilities before a caller acts. The package also includes execution traces, a replay command, trade-signal feedback, operator halt/resume controls, and a local kill-switch state. Those pieces make an automated action inspectable after the fact instead of leaving only terminal output behind.

Machine-readable output uses a schema version, and command failures map to a small exit-code contract:

Code	Meaning
0	Success
2	Validation error
4	Authentication or credential error
5	Requested data unavailable
6	No qualifying opportunity found
7	Execution failed
8	Execution completed only in part
9	User cancelled

That distinction matters in automation. A bot can treat “no opportunity” as a normal result, while stopping immediately on an authentication or partial execution error.

Security model for API keys and wallets

Credentials are treated as first-class operational risk:

• Testnet by default (mainnet requires explicit opt-in)
• AES-256-GCM encrypted local vault for stored secrets
• Owner-only file permissions (chmod 600 files, chmod 700 directories)
• Environment-variable based auth paths for CI and container workloads
• Idempotency keys on order commands to reduce duplicate execution risk
• Execution journals and safety checks around order workflows
• The project docs state there is no telemetry or phone-home behavior - a documented claim, auditable in the source, not something this article independently verified

The setup wizard defaults to testnet. Mainnet requires an explicit --mainnet flag or an exchange-specific network setting. Credentials can come from environment variables for automation or from the local encrypted vault. The Decibel flow also includes a token-validation and vault-storage helper because its bearer-token setup differs from wallet-only venues.

Command surface beyond order placement

Perps covers more than basic place/cancel commands:

• perps account for balances and positions
• perps risk for rules, audits, patterns, anomalies
• perps strategy for registered strategy introspection
• perps signal for signal tracking
• perps replay for execution replay
• perps operator for halt/resume controls
• perps doctor for health checks

For power users, advanced capabilities (batch operations, TWAP, MMP, cancel-all-after) are available where exchange adapters support them - which exchanges support which command is exactly what the repo's CAPABILITIES.md matrix documents, so check it before assuming a venue has, say, cancel-all-after.

Package architecture

The CLI and reusable exchange integrations live in the same TypeScript package. The public package exports its adapter layer, so another Node.js program can connect to an exchange without shelling out to the CLI:

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

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

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

await exchange.disconnect()

The same calling pattern applies to the Aevo, Decibel, Orderly, and Paradex adapters. Venue-specific authentication and feature differences stay behind the adapter boundary.

What can be used experimentally

The private build exposes the full command tree, but that does not make every path safe to use with funds. The practical experimental scope is:

1. Run public market-data commands with no credentials.
2. Use --json to test integrations against the output contract.
3. Configure testnet-only credentials through the setup wizard.
4. Exercise order and arbitrage flows with --dry-run.
5. Test authenticated execution only on an exchange testnet.

Mainnet execution should not be treated as verified. Exchange APIs, signing rules, package dependencies, and network endpoints may no longer match the February 2026 assumptions.

Why this matters for trading teams

Perps is best thought of as execution infrastructure, not just a command-line toy.

You can use it for:

• Manual operator workflows
• Scripted market-data and risk checks
• Agent-driven strategy loops
• Unified exchange integration in internal tooling

If you work across multiple perp venues, the concrete win is that adding a venue becomes an adapter/config change instead of another bespoke integration - one auth model, one output schema, one set of scripts to maintain.

As with any trading infrastructure, run this with strict operational controls. Keep this private build on testnet and dry-run use until every exchange integration is validated again.