trader-mcp/Strategy_Contract.md

Strategy Contract

This is the canonical contract for trader-mcp strategies.

Purpose

A strategy defines behavior. It does not own persistence, lifecycle, or UI rendering. It must also expose a Hermes-facing report() snapshot with only decision-relevant data.

Strategy class

class Strategy:
    LABEL = "Human readable name"
    CONFIG_SCHEMA = {}
    STATE_SCHEMA = {}
    TICK_MINUTES = 1.0

    def __init__(self, context, config):
        self.context = context
        self.config = config
        self.state = self.init()

Responsibilities

Strategy

• decides what to do
• reads config
• mutates self.state
• returns structured render data

Not strategy responsibilities

• persistence
• lifecycle control
• config storage
• identity ownership
• direct access to engine internals

Configuration

• CONFIG_SCHEMA is declarative metadata
• config is supplied by the engine
• config changes are handled by reload or reconcile
• config should stay read-only from the strategy perspective, except for derived policy application inside the strategy

State

• self.state belongs to the instance
• STATE_SCHEMA declares what state is durable / persisted
• keep state serializable where practical
• do not depend on hidden global state
• the engine snapshots and restores state, not the strategy
• the engine may reapply stored policy on reconcile

Lifecycle

init() -> state created
on_tick() -> state updated
reload -> state restored from engine snapshot if available

Context

The context is capability-only.

Allowed:

• account data access
• balances and open orders
• price and market-data access
• order placement
• logging
• engine-mediated actions
• binding account_id and client_id into exec calls

Not allowed:

• persistence
• config storage
• lifecycle decisions
• strategy identity ownership
• market-regime ownership

Market regime is a data-layer artifact provided by crypto-mcp, not a Trader-owned query result.

UI output

Strategies return structured widgets, not HTML.

{
  "widgets": [
    {"type": "metric", "label": "PnL", "value": 123.45},
    {"type": "line_chart", "data": [...]}
  ]
}

Example

from src.trader_mcp.strategy_sdk import Strategy

class Strategy(Strategy):
    LABEL = "Hello World"
    CONFIG_SCHEMA = {"label": {"type": "string", "default": "hello world"}}
    STATE_SCHEMA = {"counter": {"type": "int", "default": 0}}

    def init(self):
        return {"counter": 0}