@raintree-technology/perps 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Security
+- Replaced `elliptic` and `keccak256` with `@noble/curves` and `@noble/hashes` in Orderly adapter (CVE-2025-14505, CVE-2026-2739)
+- Removed `@types/elliptic` dev dependency
+- Upgraded `pmxtjs` from 2.10.0 to 2.14.1
+- Added dependency auditing section to SECURITY.md
+
+## [0.1.0] - 2026-02-23
+
+### Added
+- Initial public release
+- Universal CLI for perpetual DEXes (`perps` command)
+- Background data server (`perps-server` command)
+- Exchange adapters: Hyperliquid, Aevo, Orderly, Paradex, Decibel
+- Arbitrage tools: compare, spread, funding, execute, track
+- Order management: market, limit, trigger, cancel
+- Account management with multi-exchange support
+- Interactive onboarding wizard
+- Ink-based terminal UI
+- Agent gateway with x402 payments and EIP-8004 manifests
+- Risk management: limits, drawdown, position sizing
+- Execution journal and safety checks
+
+[Unreleased]: https://github.com/raintree-technology/perps/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/raintree-technology/perps/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Zachary Roth and Raintree Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# perps
+
+Universal CLI for perpetual DEXes — by [Raintree Technology](https://raintree.technology).
+
+[![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
+```
+
+## 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** — `perps setup wizard` stores keys in an AES-256-GCM encrypted 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
+
+# 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 | `DECIBEL_API_WALLET_ADDRESS` + `DECIBEL_API_BEARER_TOKEN` | + `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 ls --help       # List markets with funding, OI, volume
+perps order --help            # Place orders (market, limit, stop, take-profit)
+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 config --help           # Settings (show, get, set)
+perps doctor                  # Health check
+```
+
+Every command supports `--json` for machine-readable output and `--help` for usage details.
+
+## 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) ([@raintree_tech](https://x.com/raintree_tech)) — created by [Zachary Roth](https://zacharyr0th.com) ([@zacharyr0th](https://x.com/zacharyr0th))
+
+## 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.

package/dist/adapters/aevo.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Aevo Adapter
+ * Implements PerpDEXAdapter interface for Aevo DEX
+ *
+ * API Docs: https://docs.aevo.xyz/
+ * Base URL: https://api.aevo.xyz
+ */
+import { type PerpDEXAdapter, type ExchangeInfo, type ExchangeConfig, type Market, type Ticker, type OrderBook, type FundingRate, type Position, type Order, type Balance, type Trade, type OrderParams, type CancelOrderParams, type ModifyOrderParams, type FundingPayment, type PublicTrade, type SubscriptionCallbacks, type Unsubscribe, type MarginType, type MMPConfig, type MMPStatus, type TWAPParams, type TWAPStatus } from "./interface.js";
+export declare class AevoAdapter implements PerpDEXAdapter {
+    readonly info: ExchangeInfo;
+    private baseUrl;
+    private config;
+    private connected;
+    private marketsCache;
+    private readonly subscriptionTimers;
+    connect(config: ExchangeConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    private fetch;
+    private fetchAuthed;
+    private getAuthHeaders;
+    private fetchMarkets;
+    getMarkets(): Promise<Market[]>;
+    getMarket(symbol: string): Promise<Market | null>;
+    getTicker(market: string): Promise<Ticker>;
+    getTickers(): Promise<Ticker[]>;
+    getOrderBook(market: string, depth?: number): Promise<OrderBook>;
+    getFundingRate(market: string): Promise<FundingRate>;
+    getFundingRates(): Promise<FundingRate[]>;
+    getPositions(): Promise<Position[]>;
+    getPosition(market: string): Promise<Position | null>;
+    getOrders(market?: string): Promise<Order[]>;
+    getOrder(orderId: string): Promise<Order | null>;
+    getBalances(): Promise<Balance[]>;
+    getTrades(market?: string, limit?: number): Promise<Trade[]>;
+    placeOrder(params: OrderParams): Promise<Order>;
+    cancelOrder(params: CancelOrderParams): Promise<boolean>;
+    cancelAllOrders(market?: string): Promise<number>;
+    setLeverage(market: string, leverage: number): Promise<void>;
+    setMarginType(market: string, type: MarginType): Promise<void>;
+    modifyOrder(params: ModifyOrderParams): Promise<Order>;
+    batchPlaceOrders(paramsList: OrderParams[]): Promise<Order[]>;
+    batchCancelOrders(paramsList: CancelOrderParams[]): Promise<boolean[]>;
+    cancelAllAfter(_timeoutMs: number): Promise<void>;
+    getOrderHistory(market?: string, limit?: number): Promise<Order[]>;
+    getFundingHistory(market?: string, limit?: number): Promise<FundingPayment[]>;
+    getPublicTrades(market: string, limit?: number): Promise<PublicTrade[]>;
+    setMMP(config: MMPConfig): Promise<void>;
+    getMMP(market: string): Promise<MMPStatus>;
+    resetMMP(market: string): Promise<void>;
+    placeTWAP(_params: TWAPParams): Promise<TWAPStatus>;
+    cancelTWAP(_twapId: string): Promise<boolean>;
+    getTWAPStatus(_twapId: string): Promise<TWAPStatus | null>;
+    updateIsolatedMargin(_market: string, _amount: string): Promise<void>;
+    subscribe(callbacks: SubscriptionCallbacks): Unsubscribe;
+    subscribeOrderBook(market: string, callback: (book: OrderBook) => void): Unsubscribe;
+    subscribeTicker(market: string, callback: (ticker: Ticker) => void): Unsubscribe;
+    private normalizeSymbol;
+    private ensureAuth;
+    private resolveLimitPrice;
+    private toOrder;
+    private sizeToContracts;
+}
+export default AevoAdapter;