The programmable layer for composable, AI-native economic strategies
OpenWhale is a TypeScript framework for building automated economic strategies. Monitor, Strategy, and Executor are fully decoupled — the same strategy code runs on any exchange, plugs into any data source, and can be generated or evolved by an AI at runtime.
- Fully decoupled layers — Monitor, Strategy, and Executor are independent. Replace any layer without touching the others.
- Exchange-agnostic strategies — Strategy code has zero knowledge of which exchange it runs on. One strategy, any platform.
- AI as a programmer — LLM inference is built into the strategy layer. AI generates type-safe TypeScript strategies that are compiled, hot-loaded, and can evolve automatically — no token cost per tick.
- Structured trigger system — Combine Cron schedules with multi-source Monitor conditions (AND logic, time window). Express "fire only when A and B both happen within 60 seconds" without polling.
- Type-safe plugin architecture — Every Monitor, Executor, and Strategy implements a strict TypeScript interface. IDE support, safe refactoring, and AI-generated code that the type system validates at compile time.
class MomentumStrategy extends BaseStrategy {
readonly strategyId = 'momentum'
async evaluate(context: StrategyContext) {
const { symbol, threshold } = this.params.base
const tick = context.getData('price', symbol)
if (!tick || tick.price < threshold) return []
return [
this.instruction('perp', 'placeOrder', {
symbol, side: 'buy', type: 'market', amount: 0.01,
})
]
}
}const runtime = new OpenWhaleRuntime({ database, credentialStore })
runtime.loadPlugin(hyperliquidPlugin)
await runtime.start()
await runtime.activate({
strategyId: 'hyperliquid/copy-trading',
params: { base: { targetAddress: '0x...', ratio: 0.5 } },
})async evaluate(context: StrategyContext) {
const data = context.getData('price', 'BTC/USDC:USDC')
const { action, confidence } = await this.llm({
messages: [{ role: 'user', content: JSON.stringify(data) }],
schema: z.object({
action: z.enum(['buy', 'sell', 'hold']),
confidence: z.number(),
}),
})
if (action === 'hold' || confidence < 0.7) return []
return [
this.instruction('perp', 'placeOrder', {
symbol: 'BTC/USDC:USDC', side: action, type: 'market', amount: 0.01,
})
]
}- Plugin architecture — exchanges, account types, monitors, and executors register through standard interfaces; the framework manages lifecycle and dependency injection
- Composable by design — Monitor / Strategy / Executor mix and match freely; swap
MockExecutorfor simulation with one line - Exchange-agnostic strategies — strategies access accounts through
IAccountand express intent throughExecutionInstruction, never calling exchange SDKs directly - Built-in LLM inference — call LLMs with structured output (Zod schema) directly inside strategy
evaluate(); supports OpenAI, Anthropic, Google, Groq, xAI, and custom providers - Structured trigger system — Cron + Monitor condition AND combinations with time windows;
TriggerManagerhandles all scheduling and state - Auto-derived param UI — attach
.meta()to Zod schema fields; Dashboard renders typed form controls automatically, no per-strategy UI code needed - Hot-reload compiled strategies — AI-generated TypeScript strategies are compiled with esbuild and loaded at runtime without restart
- Persistent storage — Monitor data auto-persisted as JSONL; built-in KV store per strategy instance; SQLite adapter included
| Scenario | Description |
|---|---|
| Copy Trading | Monitor a target wallet, mirror its trades proportionally with position caps |
| Cross-exchange Arbitrage | Trigger only when price spread AND funding rate conditions are met simultaneously |
| AI Market Making | LLM analyzes order book depth and volatility, dynamically adjusts bid/ask quotes |
| On-chain Event Response | Listen to smart contract events, trigger on-chain or off-chain actions automatically |
| Multi-condition Signal Strategy | Combine price, volume, and funding rate monitors — fire only when all conditions align within a time window |
| NFT / Token Launch Sniping | Monitor mempool or launchpad events, execute within milliseconds of a trigger |
| Yield Optimization | Monitor APY across protocols, rebalance positions when spread exceeds threshold |
Monitor (data collection)
↓ emit(key, data)
TriggerManager (trigger evaluation)
↓ StrategyContext
Strategy (rules / AI inference)
↓ ExecutionInstruction[]
ExecutionQueue
↓
Executor (trade execution)
Each layer is a pure interface. Monitors emit keyed data events. TriggerManager evaluates Cron + Monitor conditions and fires a StrategyContext. Strategies return ExecutionInstruction[] — they never call exchange APIs directly. Executors consume the queue and handle the actual API calls.
- Node.js ≥ 20, pnpm ≥ 8
- A Hyperliquid account with a wallet address and private key
pnpm install
pnpm buildcd packages/hyperliquid
cp examples/.env.example examples/.envEdit examples/.env:
HL_WALLET_ADDRESS=0x... # your wallet address
HL_PRIVATE_KEY=0x... # your private key
HL_TARGET_ADDRESS=0x... # address to copy trades from
MASTER_KEY=your-32-byte-hex # encryption key for credential storepnpm example:copy-tradingcd packages/dashboard
cp .env.example .env.local # fill in OPENWHALE_MASTER_KEY
pnpm devOpen http://localhost:3000 to manage strategy instances, view monitor data, and configure credentials.
| Package | Description |
|---|---|
@openwhale/core |
Strategy engine core: Monitor, Trigger, Strategy, Executor, Runtime, Account, CompiledLoader |
@openwhale/hyperliquid |
Hyperliquid plugin: HyperliquidAdapter (ccxt.pro), HyperliquidAccount, UserTradesMonitor, PerpTradingExecutor, CopyTradingStrategy |
@openwhale/dashboard |
Next.js management dashboard: strategy instance management, registry browser, credential management, auto-rendered param forms |
@openwhale/assistant |
Personal assistant layer: session management, LLM conversation, tool calls (planned) |
@openwhale/mcp-server |
Expose the strategy engine as an MCP server (planned) |
A conversational compiler that guides users step by step to define strategy logic, then compiles Monitor / Strategy / Executor components into type-safe TypeScript. Runs static analysis, unit tests, and mock simulation automatically. Hot-loads the result into the runtime — ready to run out of the box.
Dual-agent optimization loop: an analysis agent reads runtime performance and historical monitor data to generate an optimization plan; an execution agent adjusts parameters or rewrites strategy code and validates the result through backtesting. Triggered automatically on a schedule, manually from the Dashboard, or conversationally through the Assistant.
A unified conversational interface for the full strategy lifecycle: create and manage instances, trigger the Compiler to build new strategies, trigger the Optimizer to tune existing ones, receive proactive alerts and performance reports. Includes basic information retrieval — market data, on-chain activity, news feeds, signal sources.
Expose the core engine capabilities as standard MCP tools, enabling external AI agents to drive strategy creation, activation, and optimization directly.
OpenWhale is in active early development. The core engine is working, and we're building the rest in the open. If you're a developer interested in composable strategy infrastructure, AI-native trading systems, or just want to run your own automated strategies — we'd love your contributions.
- Open an issue to discuss ideas or report bugs
- Submit a PR for fixes, new exchange plugins, or strategy examples
- Star the repo if you find it useful — it helps others discover the project
MIT