OpenWhale

The programmable layer for composable, AI-native economic strategies

中文说明 →

OpenWhale is a TypeScript framework for automated trading strategies. Monitors collect, Strategies decide, Executors act; the three are decoupled, so one strategy runs on any venue and against any data source, and can be written, audited and evolved by an AI.

---

Quick start

Development mode with hot reload. For a server see DEPLOYMENT.md.

Prerequisites: Node.js ≥ 20, pnpm ≥ 9 (npm i -g pnpm), git.

1. Clone and install

git clone https://github.com/OpenWhale-Org/OpenWhale.git
cd OpenWhale
pnpm install

2. Configure

cp .env.example .env

Edit .env — three variables are required on first boot:

OPENWHALE_MASTER_KEY=<random secret>     # encrypts stored credentials; generate with: openssl rand -hex 32
OPENWHALE_ADMIN_USER=admin               # first dashboard account
OPENWHALE_ADMIN_PASSWORD=<password>

The master key cannot be recovered — losing it means re-entering every API key. The admin variables create the first user; remove them after signing in. Everything else in .env.example is optional (ports, venue proxy, allowed origins).

3. Build and start

pnpm build
pnpm dev          # gateway on :3001, dashboard on :3000, both with hot reload

pnpm dev:gateway / pnpm dev:dashboard start one side only.

4. Sign in

Open http://localhost:3000 and sign in with the admin user. The dashboard offers a guided tour on first visit: a credential on the Hyperliquid testnet, an account, a copy-trading instance — no real funds.

5. Trade

Credentials → Accounts → Strategies → New strategy. A strategy instance binds params to accounts; activate it and follow it on Instances (live events, executions, runs, PnL).

Docker instead of steps 1–3:

cp .env.example .env         # same three variables
docker compose up -d --build

State lives in the openwhale-data volume; details in DEPLOYMENT.md.

The gateway holds the runtime and all secrets; the dashboard is a frontend that proxies /api/* to it (OPENWHALE_GATEWAY_URL, default http://localhost:3001).

Venue proxy

OPENWHALE_HTTPS_PROXY=http://127.0.0.1:7897        # REST + WebSocket, every venue
OPENWHALE_HTTPS_PROXY_BINANCEUSDM=off              # per venue: ccxt id upper-cased; `off` = direct

HTTPS_PROXY and NODE_USE_ENV_PROXY are not honoured — ccxt uses its own fetch. The variable is namespaced so that order traffic never changes route through an unrelated proxy setting.

Authentication

Enforced by the gateway: every /api/* route requires a session; the dashboard only carries the cookie. Sessions are opaque SQLite tokens (7-day expiry, revocable); passwords are scrypt-hashed; there are no roles. Before exposing the gateway: terminate TLS in front of it (the session cookie is Secure), keep port 3001 off the public internet, set OPENWHALE_ALLOWED_ORIGIN only for cross-origin frontends. Details in DEPLOYMENT.md.

---

Why OpenWhale

• Decoupled layers — Monitor → Strategy → Executor. Replace any layer without touching the others.
• Venue-agnostic — strategies declare account slots; the venue is resolved from the bound account at activation.
• Adapter matrix — venues are cells of a (kind × venue) matrix (exchange/perp × binance, …). Domain packages define kinds, venue packages fill cells; a data-driven ccxt roster ships twelve venues.
• AI as a programmer — structured-output LLM inference inside strategies, and a skills/openwhale-dev skill that teaches Claude the framework contract.
• Run tracing — every run persists what it saw, which gate refused, what it emitted. Survives restarts.
• PnL attribution — executors claim the orders they place; fills, fees and funding are joined back to the instance. Two instances on one account stay separable.
• Type-safe plugins — every component implements a strict TypeScript interface.

---

Core concepts

Concept	Definition
Monitor	Collects data and emits keyed records (venue:symbol). A contract with one or more implementations; users create per-key instances. Emits persist as JSONL and drive triggers.
Strategy	Pure decision logic. Declares monitor / executor / account dependencies by label, receives triggers, returns ExecutionInstruction[]. Params: base (required) and tunable (defaulted) zod schemas.
Executor	Turns instructions into venue actions through adapter sessions — retries, idempotent client order ids, latency and slippage capture. Credential slots resolve to sessions (by kind) or raw credential data (raw: true); optional: true slots may stay unbound.
Instance	Strategy + params + account bindings, activated as a unit. Live events, executions, runs and logs hang off it.
Account	A named binding of a credential to an account implementation (generic or venue-specialized). Strategies read balances and positions through it.
Trigger	Cron schedules and monitor conditions (multi-source AND within a window). Subscriptions keep monitors collecting without waking the strategy; addMonitorSource adds sources discovered at runtime.
Portfolio journal	Optional instance-scoped history: idempotent snapshots, fills, decisions, market bars. Core stores them and derives equity, drawdown and trade reports.

Monitor ──emit(key, data)──▶ TriggerManager ──StrategyContext──▶ Strategy ──ExecutionInstruction[]──▶ ExecutionQueue ──▶ Executor
                                                                     └─ run trace persisted

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗