Trading Playbook Engine

The Trading Playbook Engine is the strategist of the RiskState stack. It answers:

Is there a setup I trade?

It is a registry of pre-defined, locked setups (playbooks). A playbook fires only when three things agree at once:

its own conditions match the live data,
the Market Structure Engine aligns (the navigator votes ALIGN, not CONFLICT), and
the RiskState gate permits.

That triple-confirmation, governed is what neither a raw signal feed nor a trading bot provides.

Open the live Trading Playbook Engine →

The viewer is free and read-only. It shows the strategy registry and what is firing now — and deliberately shows no fund positions, NAV, or money. It is the strategist layer, not a fund dashboard.

The same registry and firing feed is available programmatically — see Consuming it via API for GET /api/playbook-data (the public endpoint behind the viewer), built for developers, trading agents, and downstream systems.

What it shows

Strategy registry — every playbook with its thesis, side (long / short / trim / dca), asset, class, priority, horizon, cooldown, and its sizing and exit rules (as rules, never dollar amounts).
Firing now — for the selected asset, which setups currently fire, each annotated with the Market Structure Engine's vote (ALIGN / NEUTRAL / CONFLICT) and the risk gate verdict (ALLOW / RESIZE / BLOCK).
Conviction — the proposed size as a fraction of NAV (relative conviction only — never a dollar figure).

The three engines

Each answers a different question, and a playbook only fires when all three agree:

Engine	Role	Question
Market Structure Engine	Navigator	are we near an inflection?
Trading Playbook Engine	Strategist	is there a setup I trade?
RiskState	Governor	how much is allowed?

A playbook proposes a candidate intent; the navigator confirms the terrain; the governor sizes and permits it. Only when all three agree does a governed intent exist.

Why a registry, not signals

Playbooks are pre-defined and locked — their conditions are fixed in advance, so each fire is measurable against a stable definition. This is what lets the stack accumulate an auditable track record (every governed decision is hashed with its forward return) rather than a stream of one-off calls.

Consuming it via API

The Trading Playbook Engine surface is also available over HTTP — the same feed the viewer renders. It exposes strategy IP only: the playbook registry and what is firing now. By design it carries no fund positions, NAV, or dollar amounts — sizing is expressed as rules and relative conviction (% of NAV), never money.

View the open-source client on GitHub → — typed TypeScript + Python client, response types, runnable examples, and an offline fixture.

Endpoint

GET https://api.riskstate.ai/api/playbook-data

Authentication

None. The endpoint is public and read-only. It degrades gracefully — if the upstream feed is unreachable it returns source: "unavailable" with empty arrays (a clean empty state) rather than an error. Responses are cached ~30s and carry evaluated_at (the upstream evaluation timestamp, shared with the cockpit feed so the two stay in sync).

curl https://api.riskstate.ai/api/playbook-data

What it returns

{
  "ok": true,
  "schema": "playbook_view_v1",
  "source": "live",
  "count": 10,
  "evaluated_at": "2026-06-29T12:00:00.000Z",
  "playbooks": [ /* registry */ ],
  "firing": { "BTC": [ /* … */ ], "ETH": [ /* … */ ] }
}

Field	Type	Description
`ok`	boolean	`true` when the live feed resolved.
`schema`	string	Response schema version (`playbook_view_v1`).
`source`	string	`"live"` or `"unavailable"`.
`count`	number	Number of playbooks in the registry.
`playbooks`	array	The strategy registry (see below).
`firing`	object	`{ BTC: [...], ETH: [...] }` — which setups currently fire per asset (see below).

playbooks[] — registry entry (one per locked setup):

Field	Type	Description
`id` / `name` / `version`	string	Identifier, display name, and version of the playbook.
`class`	string	Setup class (e.g. reversal, continuation).
`side`	string	`LONG` / `SHORT` (open exposure) · `TRIM` (defensive reduce) · `DCA` (phased accumulate).
`asset`	string	`BTC` or `ETH`.
`status`	string	Lifecycle status — one of `draft` · `live` · `paused` · `retired`. Only active specs (not `paused` / `retired`) are evaluated and returned. The public viewer displays `draft` as tracked (registered & paper-evaluated, not yet deploying live capital).
`thesis`	string	The setup's rationale.
`priority`	number	Resolution priority when multiple setups compete.
`horizon_days`	number	Intended holding horizon.
`cooldown_hours`	number	Minimum time between fires.
`sizing`	object	Sizing rules — e.g. `fraction_of_api_max` (size as a fraction of the RiskState max) and `scale_in` tranches. Never a dollar amount.
`exits`	object	Exit rules — stop (structural reference + fallback %) and targets (structural reference / fallback R:R / exit %).

firing.BTC[] / firing.ETH[] — firing now (governed evaluation, per asset):

Field	Type	Description
`playbook_id`	string	Which registry entry this refers to.
`would_fire`	boolean	The playbook's own conditions match the live data.
`structure_blocked`	boolean	The Market Structure Engine vetoed it (navigator CONFLICT).
`suppressed`	boolean	Suppressed by resolution (e.g. a higher-priority setup won).
`structure_gate`	object	`{ vote, reason }` — the navigator's verdict (`ALIGN` / `NEUTRAL` / `CONFLICT`).
`gate_status`	string	The RiskState risk-gate verdict — `ALLOW` / `RESIZE` / `BLOCK` (or `INDETERMINATE`). Shown on every firing setup, so a setup can be firing yet gate-blocked — the registry tracks performance both with and without the gate.
`size_pct_nav`	number	Proposed conviction as a percentage of NAV — relative only, never a dollar figure.

A setup is actively firing when would_fire is true and it is neither suppressed nor structure_blocked — i.e. all three engines agree.

trading-playbook-engine on GitHub — the open-source integration kit (TS + Python client, types, examples).
Market Structure Engine — the navigator the playbooks require for confluence (and its /v1/market-structure API).
Methodology — how the risk gate sizes and permits a candidate intent.
API Reference — the core /v1/risk-state endpoint the risk gate is built on.
Audit Log — how governed decisions are recorded and verified.