flowchart LR
    subgraph HOST["Your machine"]
        A["MCP host<br/>(Claude Desktop / Cursor)"]
        subgraph TB["tradebox-mcp"]
            G["Guardrail engine<br/>(allow / deny)"]
            R["Recorder<br/>(JSONL blackbox)"]
        end
        C["CCXT MCP server<br/>(child process)"]
        L[("~/.tradebox/logs/<br/>YYYY-MM-DD.jsonl")]
    end
    X["Exchange<br/>(Binance, …)"]

    A -- "stdio (JSON-RPC / MCP)" --> G
    G -- "allowed calls only" --> C
    G -.-> R
    R -.-> L
    C -- "HTTPS (your API keys<br/>never leave this hop)" --> X

sequenceDiagram
    participant Agent as Agent (LLM)
    participant TB as tradebox
    participant Broker as CCXT MCP
    participant Ex as Exchange

    Note over Agent,Ex: ✅ order within limits
    Agent->>TB: createOrder BTC/USDT, $150
    TB->>TB: classify → trade.place<br/>guardrails → ALLOW
    TB->>Broker: forward
    Broker->>Ex: place order
    Ex-->>Broker: filled
    Broker-->>TB: result
    TB->>TB: log call + result (JSONL)
    TB-->>Agent: result

    Note over Agent,Ex: ⛔ order over the limit
    Agent->>TB: createOrder DOGE/USDT, $520
    TB->>TB: classify → trade.place<br/>guardrails → DENY (allowed_symbols)
    TB->>TB: log the denial
    TB-->>Agent: "Order denied: DOGE/USDT is not<br/>in allowed_symbols (BTC/USDT, ETH/USDT)."
    Note over Agent: agent reads the reason<br/>and adjusts — no crash loop

mkdir -p ~/.tradebox
cp config.example.yaml ~/.tradebox/config.yaml
chmod 600 ~/.tradebox/config.yaml

# ~/.tradebox/config.yaml (minimal)
downstreams:
  ccxt:
    command: npx
    args: ["-y", "@lazydino/ccxt-mcp", "--config", "~/.tradebox/ccxt-accounts.json"]
    # ccxt-accounts.json holds your exchange keys (see config.example.yaml).
    # Use a read + trade key. NEVER enable withdrawals on it.

guardrails:
  allowed_symbols: ["BTC/USDT", "ETH/USDT"]
  max_order_notional: 200        # $ per single order
  max_orders_per_hour: 6
  max_daily_loss: 100            # trips the circuit breaker (UTC day)
  dry_run: true                  # ON by default — flip to false to go live

{
  "mcpServers": {
    "trading": {
      "command": "npx",
      "args": ["-y", "tradebox-mcp", "run", "--config", "~/.tradebox/config.yaml"]
    }
  }
}

stateDiagram-v2
    [*] --> Trading
    Trading --> Locked : realized daily PnL ≤ −max_daily_loss
    Trading --> Locked : operator runs "tradebox stop"
    Locked --> Trading : operator runs "tradebox resume"
    Locked --> Locked : every trade.* call → denied<br/>(reads still pass through)

    note right of Locked
        The lock survives restarts —
        state is a projection of the log,
        so a crash never resets the breaker.
    end note

{"ts":"2026-08-25T12:00:00.123Z","event":"tool_call","server":"ccxt","tool":"createOrder","category":"trade.place","args":{"symbol":"BTC/USDT","side":"buy","type":"limit","amount":0.02,"price":58900},"decision":"allow","latency_ms":840,"result":{"order_id":"123","filled":0.02,"avg_price":58895}}
{"ts":"2026-08-25T12:05:01.000Z","event":"tool_call","server":"ccxt","tool":"createOrder","category":"trade.place","args":{"symbol":"DOGE/USDT","side":"buy","amount":50000},"decision":"deny","rule":"allowed_symbols","latency_ms":2}
{"ts":"2026-08-25T12:05:04.500Z","event":"reasoning","text":"DOGE blocked. Holding BTC, waiting for the 58K retest."}
{"ts":"2026-08-25T13:00:00.000Z","event":"guardrail_trip","rule":"max_daily_loss","value":-102.5,"limit":-100,"action":"trading_locked"}

$ tradebox report --window 7d

AGENT BEHAVIOR REPORT              2026-08-18 → 2026-08-25
──────────────────────────────────────────────────────────
                      baseline (7d)    last 24h        Δ
orders/day                  4.2            11        ×2.6  ⚠
avg order notional        $145           $410        ×2.8  ⚠
symbols traded        BTC 82% · ETH 18%  +SOL 37%          ⚠ new symbol
avg hold time             3.1 h          22 min      ÷8.5  ⚠
denied calls                 0             7    max_order_notional ×5
realized PnL              +$83           −$61
──────────────────────────────────────────────────────────
⚠ BEHAVIORAL DRIFT: the agent is behaving differently than
  it did 7 days ago. Model update? Prompt change? Check
  before it costs you.

tradebox run --config <path>    start the proxy (spawned by your MCP host)
tradebox report [--window 7d]   behavior + drift report from local logs
tradebox stop                   PANIC — deny all trading immediately
tradebox resume                 clear the panic / daily-loss lock

export interface GuardrailRule {
  name: string;
  // return null to pass; return a string to deny (the reason is sent to the LLM)
  check(call: ClassifiedToolCall, state: SessionState, cfg: Config): string | null;
}