OpenWhale

The programmable layer for composable, AI-native economic strategies

OpenWhale is a TypeScript framework for building automated economic strategies. Monitors, Strategies, and Executors are fully decoupled — the same strategy code runs on any venue, plugs into any data source, and can be written, audited, and evolved by an AI.

Why OpenWhale

• Fully decoupled layers — Monitors collect, Strategies decide, Executors act. Replace any layer without touching the others.
• Venue-agnostic by construction — a strategy never names an exchange. It declares account slots; the venue derives from whichever account you bind at activation. One strategy, any platform.
• The adapter matrix — venues plug in as cells of a (kind × venue) matrix (exchange/perp × binance, exchange/spot × hyperliquid, …). Domain packages define the vocabulary, venue packages fill the cells, and a data-driven ccxt roster ships twelve venues out of the box.
• AI as a programmer — LLM inference with structured output is built into the strategy layer, and the repo ships a skills/openwhale-dev skill that teaches any Claude the full framework contract so it can produce installable plugins with tests.
• Deep observability — every strategy run leaves a persistent decision trace: what it saw, which gate said no, what it emitted. Deactivate an instance or restart the gateway and the audit trail survives.
• PnL attribution built in — executors auto-claim the orders they place; a background collector joins venue fills (ground-truth realized PnL and fees) and funding income back to the claiming instance. Two instances trading the same symbol on the same account stay separable.
• Type-safe plugin architecture — every component implements a strict TypeScript interface. IDE support, safe refactoring, and AI-generated code the compiler validates.

Core concepts

Monitor (data collection)
    ↓ emit(key, data)
TriggerManager (cron + monitor conditions)
    ↓ StrategyContext
Strategy (rules / AI inference)  →  run trace persisted
    ↓ ExecutionInstruction[]
ExecutionQueue
    ↓
Executor (venue actions via adapter sessions)

The dashboard

• Instances — cards with folders, drag-drop ordering, emoji icons, and a live net-PnL badge per card; four live tabs per instance (Live Events scoped to the instance's own monitors, Executions, Runs, Logs). A full-page Board per instance adds click-to-rename, account rebinding, an editable parameter panel, and a PnL panel.
• Per-instance PnL — realized / fees / funding / net / unrealized cards backed by the attribution ledger, with drill-down tabs for by-symbol totals, raw venue fills, and fill-derived open positions priced at the venue mark. Funding events split across instances by the position each held at the settlement boundary.
• Run tracing — every run records its steps: gates, skips, sizing, emitted instructions, captured log lines. Runs with instructions or errors persist to disk; idle runs are heartbeat-sampled. Filter by outcome, search by content.
• Monitor boards — monitors declare dashboard panels via the plots() convention: line/bar/candles plus a sortable table kind, single- and multi-select pickers, record-window control.
• Params as forms — zod .meta() drives the UI: sections, sliders, unit suffixes, conditional visibility, searchable market pickers (single and multi), per-value availability verdicts against the bound venue, editable row-table list params for ladders, and sandboxed interactive illustrations that redraw live as you edit values.
• Scripts — plugins ship operator utilities (scripts: [...]) that run on demand against the live runtime and return a monospace report: plan previews, fit inspectors, one-off audits. Params render as a small form, with live-resolved dropdowns for runtime values such as instance ids.
• Compiler & Assistant — an experimental natural-language strategy compiler, plus the recommended path: point Claude at skills/openwhale-dev and have it write the plugin.

Code examples

A minimal strategy

const decls = {
  monitors: [{ name: 'exchange/ticker', label: 'price' }],
  executors: [{ name: 'exchange/perp-trading', label: 'perp' }],
  accounts: [{ account: PerpAccount, label: 'main' }],
} as const satisfies StrategyDeclarations

class MomentumStrategy extends BaseStrategy<typeof decls> {
  readonly strategyId = 'momentum'
  override readonly monitors = decls.monitors
  override readonly executors = decls.executors
  override readonly accounts = decls.accounts

  readonly baseParamsSchema = z.object({
    symbol: z.string().meta({ displayName: 'Symbol' }),
    threshold: z.number().meta({ displayName: 'Entry price' }),
  })

  async evaluate(context: StrategyContext) {
    const { symbol, threshold } = this.baseParamsSchema.parse(this.params.base)
    const tick = context.getData('price', `${this.accountVenue('main')}:${symbol}`)
    this.trace('tick:read', { tick })                    // lands in the run trace
    if (!tick || tick.price < threshold) return []

    return [
      this.instruction('perp', 'placeOrder', {
        symbol, side: 'buy', type: 'market', amount: 0.01,
      }),
    ]
  }
}

Assembling the runtime

const runtime = new OpenWhaleRuntime({ database, credentialStore })
runtime.loadPlugin(binancePlugin, {})
runtime.loadPlugin(hyperliquidPlugin, {})
await runtime.start()
await runtime.activate({
  strategyId: 'my-plugin/momentum',
  credentials: { main: 'My Binance' },       // the account binding decides the venue
  params: { base: { symbol: 'BTC/USDT:USDT', threshold: 60000 } },
})

AI-driven strategy with structured output

async evaluate(context: StrategyContext) {
  const data = await this.monitorData('market')?.readLatest(this.accountVenue('main'))

  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,
    }),
  ]
}

An operator script

export const planPreview: ScriptDefinition = {
  id: 'plan-preview',
  name: 'Plan preview',
  paramsSchema: z.object({ instance: z.string().default('') }),
  paramOptions: async (runtime) => ({ instance: await listMyInstances(runtime) }),
  run: async ({ params, runtime }) => ({ text: await renderPlan(runtime, params) }),
}

Plugins

A plugin is a package with a default-exported factory returning its registrations:

export default definePlugin((ctx) => ({
  name: 'my-plugin',
  version: '1.0.0',
  monitorImplementations: [ /* contract / implementation / instance model */ ],
  executors: [ /* … */ ],
  strategies: [ /* … */ ],
  scripts: [ /* operator utilities for the Scripts page */ ],
  credentialTypes: [ /* venue credential recipes: schema, raw opt-in, connectivity test */ ],
  adapters: [ /* (kind × venue) matrix cells */ ],
  accounts: [ /* account implementations */ ],
}))

Install from the dashboard's Plugins page — a built .js/.mjs bundle, a GitHub repository (owner/repo, or paste the address bar; optional branch/tag/commit), or an npm name or local path — or runtime.loadPlugin() in code. Components register namespaced (my-plugin/momentum); hot reload is supported.

A GitHub install is cloned and built by npm, so a repo shipping only TypeScript sources needs a prepare script in its package.json ("prepare": "npm run build"); private repos need OPENWHALE_GITHUB_TOKEN set on the engine.

A plugin's declared name is its default namespace — the my-plugin/ every id it registers is prefixed w