The programmable layer for composable, AI-native economic strategies
# Add to your Claude Code skills
git clone https://github.com/OpenWhale-Org/OpenWhaleNo comments yet. Be the first to share your thoughts!
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.
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,
})
]
}
MockExecutor for simulation with one lineIAccount and express intent through ExecutionInstruction, never calling exchange SDKs directlyevaluate(); supports OpenAI, Anthropic, Google, Groq, xAI, and custom providersTriggerManager handles all scheduling and state.meta() to Zod schema fields; Dashboard renders typed form controls automatically, no per-strategy UI code needed| 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.
pnpm install
pnpm build
cd packages/hyperliquid
cp examples/.env.example examples/.env
Edit 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 store
pnpm example:copy-trading
cd packages/dashboard
cp .env.example .env.local # fill in OPENWHALE_MASTER_KEY
pnpm dev
Open 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.
MIT