openwhale-org/openwhale/openwhale-dev

OpenWhale Plugin Development

**Calibrated against @openwhaleorg/core v0.2.3 on main (re-verified 2026-09-03: every template signature

checked against packages/framework/core/src).** If the installed core is newer, verify signatures against

the framework source before trusting a template verbatim.

OpenWhale is an AI-native trading framework: Monitor → Trigger → Strategy → Queue → Executor. You are writing a plugin package — an npm package whose default export is a definePlugin({...}) manifest. The user installs it from the Dashboard (Plugins page → local path or npm spec) into a running Gateway; no framework code is ever modified.

The 8 concepts (fixed vocabulary — never invent others)

Core rule everything hangs off: the venue × kind matrix. kind = domain column, venue = the place you trade/read ('binance', 'boros', 'evm'). A cell (kind, venue) names the credential types that open it (credentialTypes, default [venue] — the CEX case). Generic implementations claim a column, specializations claim a cell, specialization wins. type is the deprecated spelling of venue.

What are you being asked to write?

• A trading strategy from a description → references/spec.md FIRST. A description leaves a

dozen decisions unsaid — fills, restarts, sizing base, idempotency — and each one you guess is a rebuild or a loss. Interview the user in rounds until nothing is assumed, write the spec, get it confirmed, then references/strategy.md for the class. Skip the interview only when the user hands you a spec in that shape already.

• A trading strategy, spec in hand → references/strategy.md. Usually also needs an executor if

the action isn't covered by the shared exchange/perp-trading / exchange/spot-trading executors.

• A data feed / market watcher → references/monitor.md.
• An order-execution service → references/executor.md.
• Support for a new exchange/venue → references/plugin.md §Venue plugin (credential type +

adapter cells; optionally a specialized Account).

• A new domain (new kind) → references/plugin.md §New kind (AdapterKindMap merge + mock cell +

generic Account).

• Packaging / install / project scaffold → references/plugin.md §Packaging.
• An operator utility for the Scripts page → a ScriptDefinition in the plugin's scripts: []

array — see references/plugin.md §Scripts. definePlugin accepts scripts directly; a report that wants a page rather than a text block uses core's reportPage shell.

• Tests → references/testing.md. Always write them; every template there runs offline.

Working code to copy from: packages/strategies/examples (@openwhaleorg/examples) — five venue-agnostic strategies (momentum breakout, mean reversion, scheduled accumulation, an LLM-driven analyst, copy-trading) over a tested indicators.ts. Read the one closest to the ask before writing: they show the account-slot / accountVenue idiom, store-based idempotency, and the discipline that risk limits live in code even when a model produces the signal.

Since 2026-08-26 (newest first)

• Text in more than one language (core ≥ 0.2.3). Every user-facing string in a manifest, a

decorator or a param's .meta() is a Text: a string, or { en, 'zh-CN' }. The gateway resolves it per request; our strategies carry both languages on every string; a plugin may ship language packs (definePlugin({ i18n })) instead. (references/strategy.md §Text)

• Picker fields (core ≥ 0.2.3). An object param with meta({ picker: { source: 'strategy', id } })

renders as a button and a card dialog whose options pickerOptions(id, ctx) computes — for a value that is a whole decision (the four legs of a carry), where a preset would scatter it over fields. (references/strategy.md §Picker fields)

• Quick and pinned parameters (core ≥ 0.2.3). .meta({ quick: true }) lists a field on the quick

panel at the top of the instance board; .meta({ pinned: true }) (three at most) makes it editable from the instance list. Strategy defaults; the operator may override per instance. (references/strategy.md §Quick and pinned parameters)

• Illustrations get live figures (core ≥ 0.2.3). illustrationData(ctx) on a strategy is called,

debounced, for the form's current values, and its answer reaches every paramsIllustrations frame as data in the ow-params message — quotes, an estimate, a venue limit, drawn live as the operator types. (references/strategy.md §Illustrations)

• Live presets with cards (core ≥ 0.2.3). A strategy may compute its presets — presets(ctx)

with keyless adapters, the bound slots and the form's current values — and give each a card (title, headline figure, rows, badges, tone; or html for a custom drawing). The Dashboard then offers a picker dialog laid out in the order returned; static paramPresets without cards stay a dropdown. Results are cached by presetSource.ttlMs. (references/strategy.md §Presets)

• Lifecycle hooks — `onActivate` / `onDeactivate` (core ≥ 0.2.3). A strategy gets a moment of

its own at each end: onActivate(ctx) after every setter and before the first trigger (take a baseline, set leverage, settle a quote left from the last activation); onDeactivate(ctx) after the run in flight has finished and BEFORE executor slots are removed (cancel what rests). Both may return instructions, which are fired inline and awaited — never queued. ctx.reason names the transition: activate | boot | restart | rollback | stop | delete | shutdown. A throwing onActivate fails the activation; a throwing onDeactivate is logged and teardown continues. Both show on the instance board as runs lifecycle:<reason>. (references/strategy.md)

• The framework version is settled at install. A plugin's peerDependencies range for

@openwhaleorg/* is checked against the running engine before anything is staged; a mismatch is refused with both versions and which side to move. Declare a real range (^0.2.2), never * — * is satisfied by an engine missing the exports you import, and the failure then surfaces at load as does not provide an export named …. The engine's framework copy is the only one: what npm fetches for the plugin is replaced by a link to it. (references/plugin.md §Packaging)

• `reportPage` — the HTML report shell (core ≥ 0.2.2). `reportPage({ title, eyebrow, h1, lede?,

ident?, figures?, body, footer? }) returns a self-contained page; esc / num / signed / cls are its helpers. Return it as a ScriptResult.files entry with mime: 'text/html' and the Scripts page renders it inline in a sandboxed iframe (external links need target="_blank"). (references/plugin.md` §Scripts)

• Scripts can be stopped. The page's Stop button reaches run() as ctx.signal (an

AbortSignal); check it between slow steps and return what you have. (references/plugin.md §Scripts)

• Install sources and rules — npm, GitHub owner/repo[#ref], a local path, or a built bundle;

a taken name gets a namespace at install; installing over an installed plugin is an overwrite that keeps instances/accounts/credentials; uninstall is refused while anything references the plugin. The full rule list is the README's §Plugins — this skill does not restate it.

• `this.trace(step, data?)` in a strategy records one decision step of the current run; the

Dashboard shows the trace per run, and it survives restarts. Use it at every gate, so a run that emitted nothing still says which condition refused. (references/strategy.md)

• `z.enum` params render as a dropdown; availabilityCheckers on a strategy validate a symbol

param against the venue's live market list. (references/strategy.md)

Since 2026-08-06

• `venue` replaces `type` on cells and account implementations — `{ kind, venue, credentialTypes?,

create }. On-chain venues list a shared key family (credentialTypes: ['web3/evm']) instead of a venue-issued key; a cell without credentialTypes accepts [venue]. (references/plugin.md`)

• Account params + declarative detail panels — @OwAccount({ paramsSchema, sections }): params

render on the account form and reach the constructor as a third argument; sections describes the detail tables/key-values the Dashboard draws from the class's own reader methods. (references/plugin.md)

• `paramsIllustrations` on a strategy — sandboxed HTML iframes rendered inside the param form, fed

the live field values via postMessage. (references/strategy.md)

• Brand marks — logo / icon / readme on the manifest; logo / icon / description /

managed on a credential type (managed hides it from the add-credential picker: created by a script, e.g. a venue's delegated agent key). (references/plugin.md)

• Scripts stream and attach — ctx.emit?.(line) feeds progress to the page while a run lasts;

ScriptResult.files offers downloads (inline content, report-sized). (references/plugin.md)

• `@openwhaleorg/web3` — kind 'web3/chain' (EVM read/sign session, ChainAccount wallet view),

credential types 'web3/evm' (wallet key) and 'web3/rpc'. On-chain venue packages depend on it for the wallet key family and never ship their own chain client.

Since 2026-07

• Optional executor credential slots — { label, type, raw: true, optional: true }: activation

proceeds with the slot unbound; read with this.rawIfBound(label) (undefined = unbound) and return a clear failed result instead of throwing. For side-channel executors (notifiers) gated by a strategy toggle. (references/executor.md)

• Automatic PnL attribution — record { orderId, symbol } on the same object anywhere in the

execution result's data (depth ≤ 6) and the framework claims the order for the instance; venue fills and funding then attribute automatically. Follow the convention for EVERY placed order, including resting/protective orders. (references/executor.md)

• Dynamic monitor sources — a live strategy may call

this.addMonitorSource(label, key, { trigger? }) to start collecting a key discovered at runtime. No-op (returns false) where unsupported. (references/strategy.md)

• `table` and `scatter` plot kinds — monitors may declare sortable table panels via

{ kind: 'table', columns: [...] }, and correlation panels (points + fitted trend line with a confidence band) via { kind: 'scatter' }. (references/monitor.md)

Read the reference file for each component you touch BEFORE writing code. The templates there are verified against the framework source — copy their shape exactly.

Hard rules (violating any of these breaks at load or runtime)