Docs
GitHub

Circuit Breakers

Circuit breakers are automatic safety mechanisms that halt trading when predefined risk thresholds are exceeded. KlawTrade includes seven independent circuit breaker triggers -- each monitoring a different dimension of risk. When any single breaker trips, all trading stops immediately and open positions are optionally flattened.

This system runs independently of the 14-check risk management gate that evaluates individual trades. Circuit breakers protect against systemic risk -- scenarios where the overall portfolio or trading environment becomes dangerous.

The 7 Circuit Breaker Triggers

1. Consecutive Losses

Trips when the strategy hits a streak of losing trades in a row. A long losing streak often signals that market conditions have shifted away from the strategy's edge.

Default threshold: 5 consecutive losses

2. Daily Loss Limit

Trips when total losses for the current trading day exceed a percentage of portfolio equity. Prevents a single bad day from causing outsized damage.

Default threshold: -3% of portfolio equity

3. Weekly Loss Limit

Trips when cumulative losses for the current week exceed a percentage of portfolio equity. Catches scenarios where daily losses are just under the daily limit but accumulate dangerously over multiple days.

Default threshold: -7% of portfolio equity

4. Max Drawdown

Trips when the portfolio drops a set percentage from its all-time high watermark. This is the ultimate capital preservation trigger -- it catches prolonged declines that daily and weekly limits might not.

Default threshold: -15% from equity high watermark

5. VIX Spike

Trips when the CBOE Volatility Index (VIX) exceeds a configured level. Extreme VIX readings indicate market-wide panic and elevated tail risk. Trading during these events often produces unpredictable fills and outsized slippage.

Default threshold: VIX above 35

6. Max Open Positions

Trips when the number of concurrent open positions exceeds a limit. Too many simultaneous positions increase correlation risk and make it harder to manage exits during fast-moving markets.

Default threshold: 10 open positions

7. System Errors

Trips when repeated system errors occur within a time window -- for example, broker API failures, data feed disconnections, or order rejections. This prevents the engine from trading in a degraded state where it cannot reliably execute or monitor positions.

Default threshold: 3 errors within 5 minutes

Configuring Thresholds

All circuit breaker thresholds are configurable in your config/settings.yaml file. See the Configuration guide for the full schema.

circuit_breakers:
  consecutive_losses: 5
  daily_loss_pct: -3.0
  weekly_loss_pct: -7.0
  max_drawdown_pct: -15.0
  vix_threshold: 35
  max_positions: 10
  system_errors:
    count: 3
    window_minutes: 5
  on_trip:
    action: "halt"            # halt or flatten_and_halt
    notify:
      - email
      - dashboard
    cooldown_minutes: 60      # minimum wait before manual reset

What Happens When a Breaker Trips

When any circuit breaker threshold is exceeded, the following sequence executes automatically:

  1. Trading halts -- the strategy engine immediately stops generating new signals and placing orders
  2. Positions flatten (optional) -- if configured with flatten_and_halt, all open positions are closed with market orders
  3. Alert fires -- notifications are sent via email and displayed on the dashboard
  4. Cooldown starts -- a configurable cooldown period begins before the system can be reset
  5. Event logged -- the trip is recorded in the trade log with the trigger type, threshold, and actual value

Recovery and Reset

After a circuit breaker trips, trading does not resume automatically. This is by design -- the system requires human review before restarting. To reset:

klawtrade circuit-breaker reset

You can also reset from the dashboard by clicking the reset button in the circuit breaker panel. The reset is blocked until the cooldown period has elapsed.

To check the current status of all circuit breakers:

$ klawtrade circuit-breaker status

Circuit Breaker Status
─────────────────────────────────────────
Consecutive Losses:  2 / 5       OK
Daily Loss:         -1.2% / -3%  OK
Weekly Loss:        -2.8% / -7%  OK
Max Drawdown:       -4.1% / -15% OK
VIX Level:          18.5 / 35    OK
Open Positions:     4 / 10       OK
System Errors:      0 / 3        OK
─────────────────────────────────────────
Status: ALL CLEAR

Best Practices

  • Start conservative -- use tight thresholds while you learn the system, then relax them as you gain confidence in your strategies
  • Use flatten_and_halt for live trading -- in simulation you can use halt alone, but with real money you generally want positions closed when a breaker trips
  • Enable email notifications -- you may not always be watching the dashboard when a breaker trips
  • Review every trip -- treat each circuit breaker event as a learning opportunity. Analyze what caused it before resetting
  • Backtest with circuit breakers on -- include circuit breakers in your backtests to see how they would have affected historical performance

Next Steps

  • Risk Management -- learn about the per-trade risk checks that complement circuit breakers
  • Dashboard -- monitor circuit breaker status in real time
  • Configuration -- full reference for all circuit breaker settings
  • CLI Reference -- circuit-breaker subcommand documentation