1.2 KillSwitch

1. Bot Identity

Operational profile

2. Purpose

KillSwitch is the top-level emergency stop for the entire trading system. It can be triggered automatically when intraday or weekly drawdown exceeds a threshold, when the order-reject rate spikes above a circuit-breaker level, or when a market data feed is lost with open positions. It can also be triggered manually via the Admin UI. Once active, KillSwitch rejects every incoming OrderIntent without exception until a manual reset is performed (if require_manual_reset=true) or the trigger condition clears. It does not modify orders — it only blocks them entirely.

3. Why This Bot Matters

• Runaway loss not stopped automatically

  Without a drawdown circuit breaker, a strategy that enters a losing streak continues to trade, compounding losses until a human intervenes — which may be too late.

• API or wallet misbehaviour not detected

  A spike in order rejections from the exchange or a wallet desync can indicate a broken execution path. Continuing to submit orders under these conditions risks unintended positions or double-orders.

• Data feed lost with open positions

  If the CLOB WebSocket feed dies and positions remain open, the system cannot monitor or hedge those positions. The safe action is to halt new orders until the feed is restored.

• No single manual override path

  In an incident, teams need a single, reliable mechanism to stop all trading immediately. Without a centralised kill signal, individual strategy shutdowns may be missed.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "intraday_drawdown_pct": 12 }

if (intradayDrawdownPct > p.hard) killswitch.activate('INTRADAY_DRAWDOWN_EXCEEDED');

{ "weekly_drawdown_pct": 20 }

if (weeklyDrawdownPct > p.hard) killswitch.activate('WEEKLY_DRAWDOWN_EXCEEDED');

{ "reject_rate_circuit": 30 }

if (rejectRate5min > p.hard) killswitch.activate('ORDER_BOOK_UNAVAILABLE');

{ "require_manual_reset": true }

if (!p.require_manual_reset && triggerConditionCleared) killswitch.deactivate();

8. Default Configuration

{
  "bot_id": "risk.kill_switch",
  "version": "1.0.0",
  "mode": "hard_guard",
  "defaults": {
    "intraday_drawdown_pct": 12,
    "weekly_drawdown_pct": 20,
    "reject_rate_circuit": 30,
    "require_manual_reset": true
  },
  "locked": {
    "require_manual_reset": {
      "immutable": true
    },
    "intraday_drawdown_pct": {
      "max": 20
    },
    "weekly_drawdown_pct": {
      "max": 30
    }
  }
}

9. Implementation Flow

1. On each OrderIntent received, check the KillSwitch active flag in shared state before any other processing.
2. If active flag is set, immediately return REJECT with reason_code matching the trigger (e.g. STRATEGY_BUDGET_EXCEEDED for drawdown, ORDER_BOOK_UNAVAILABLE for reject-rate or feed loss) — do not consult any other data.
3. In a parallel monitoring loop, continuously read rolling intraday and weekly drawdown from PortfolioGuard.
4. If intraday_drawdown_pct or weekly_drawdown_pct hard limit is breached, atomically set the active flag and record the trigger reason, timestamp, and metric value.
5. In the same monitoring loop, count order reject events from the CLOB over a rolling 5-minute window; if reject_rate_circuit hard limit is breached, set the active flag.
6. Monitor the CLOB WebSocket connection status; if the connection has been dead for more than 30 seconds and open positions exist, set the active flag with reason ORDER_BOOK_UNAVAILABLE.
7. Listen for manual kill signal from Admin UI; on receipt, set the active flag immediately with reason MANUAL_KILL regardless of metric levels.
8. When KillSwitch is active, emit a system-level alert to the monitoring stack on every rejected order.
9. If require_manual_reset=true, ignore all automatic condition-clearing events; wait for explicit Admin UI reset.
10. On reset, clear the active flag, log the reset timestamp and operator action, and resume the normal guardrail pipeline.

10. Reference Implementation

Runs two concurrent loops: a fast per-intent check that reads a single Redis key, and a background monitor that watches P&L, reject rate, and WS feed health. The Redis key is the single source of truth for the active flag.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

// ---- FAST PATH: called on every OrderIntent ----
FUNCTION checkKillSwitch(intent):
  state = FETCH redis.GET('killswitch:state')  // O(1) Redis read
  IF state.active:
    EMIT RiskVote(decision=HARD_REJECT,
                  reason=KILL_SWITCH_ACTIVE,
                  trigger_reason=state.trigger_reason,
                  activated_at=state.activated_at)
    RETURN
  // Pass through — other guardrails take over
  EMIT RiskVote(decision=APPROVE)

// ---- BACKGROUND MONITOR: runs every 5s ----
FUNCTION monitorLoop():
  WHILE true:
    // 1. Intraday drawdown
    drawdown = FETCH internal.portfolio_guard.drawdown_pct()
    IF drawdown > params.intraday_drawdown_pct.hard:
      activate('INTRADAY_DRAWDOWN_EXCEEDED')

    // 2. Weekly drawdown
    weeklyDrawdown = FETCH internal.portfolio_guard.weekly_drawdown_pct()
    IF weeklyDrawdown > params.weekly_drawdown_pct.hard:
      activate('WEEKLY_DRAWDOWN_EXCEEDED')

    // 3. Order reject rate
    rejectRate = FETCH internal.clob_reject_counter.rate_5min()
    IF rejectRate > params.reject_rate_circuit.hard:
      activate('ORDER_BOOK_UNAVAILABLE')

    // 4. WebSocket feed health
    wsDead = FETCH ws_market.seconds_since_last_message()
    openPositions = FETCH internal.portfolio_guard.open_position_count()
    IF wsDead > 30 AND openPositions > 0:
      activate('ORDER_BOOK_UNAVAILABLE')

    // 5. Data feed staleness
    IF drawdown IS NULL AND wsDead > 60:
      activate('STALE_MARKET_DATA')  // fail-safe: unknown system health

    SLEEP 5

// ---- ACTIVATE / DEACTIVATE ----
FUNCTION activate(triggerReason):
  state = { active: true, trigger_reason: triggerReason, activated_at: now_iso() }
  redis.SET('killswitch:state', state)  // atomic write
  EMIT alert(P0, 'KillSwitchActivated', state)

FUNCTION deactivate(operator):
  IF params.require_manual_reset:
    // Only admin UI can call this
    redis.SET('killswitch:state', { active: false, reset_by: operator, reset_at: now_iso() })
  ELSE:
    IF triggerConditionCleared():
      redis.SET('killswitch:state', { active: false })

Helpers used

SDK calls used

• redis.GET('killswitch:state')
• redis.SET('killswitch:state', state)
• internal.portfolio_guard.drawdown_pct()
• internal.portfolio_guard.weekly_drawdown_pct()
• ws_market.seconds_since_last_message()

Complexity: O(1) per intent (single Redis read); background monitor O(1) per cycle

11. Wire Examples

Input — what arrives on the wire

OrderIntent arriving while KillSwitch is active — internal

{
  "intent_id": "int_8e9f0a1b2c3d4e5f",
  "market_id": "0x4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "side": "BUY",
  "size_usd": 500,
  "generated_at": "2026-05-09T09:11:00Z"
}

Redis KillSwitch state (active) — internal

{
  "active": true,
  "trigger_reason": "INTRADAY_DRAWDOWN_EXCEEDED",
  "trigger_metric": 0.132,
  "activated_at": "2026-05-09T09:10:00Z",
  "require_manual_reset": true
}

Output — what the bot emits

RiskVote — HARD_REJECT (KillSwitch active, drawdown breach)

{
  "guard_id": "risk.kill_switch",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "KILL_SWITCH_ACTIVE",
  "message": "KillSwitch is active. Intraday drawdown of 13.2% exceeded the 12% circuit breaker. All new orders are rejected. Manual reset required.",
  "constraints": {},
  "trigger_reason": "INTRADAY_DRAWDOWN_EXCEEDED",
  "trigger_metric": 0.132,
  "activated_at": "2026-05-09T09:10:00Z",
  "inputs_used": [
    "redis.killswitch_state"
  ],
  "checked_at": "2026-05-09T09:11:05Z"
}

RiskVote — APPROVE (KillSwitch not active)

{
  "guard_id": "risk.kill_switch",
  "decision": "APPROVE",
  "severity": "INFO",
  "reason_code": null,
  "inputs_used": [
    "redis.killswitch_state"
  ],
  "checked_at": "2026-05-09T10:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.kill_switch",
  "decision": "REJECT",
  "severity": "HARD",
  "reason_code": "STRATEGY_BUDGET_EXCEEDED",
  "message": "KillSwitch is active. Intraday drawdown of 13.2% exceeded the 12% circuit breaker. All new orders are rejected. Manual reset required.",
  "constraints": {},
  "trigger_reason": "INTRADAY_DRAWDOWN_EXCEEDED",
  "trigger_metric": 0.132,
  "activated_at": "2026-05-09T09:10:00Z",
  "inputs_used": [
    "portfolio_guard.drawdown",
    "admin_ui.kill_flag"
  ],
  "checked_at": "2026-05-09T09:11:05Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Risk overview / KillSwitch status
• Grafana — Incident timeline / KillSwitch activations

Log levels

16. Developer Reporting

{
  "bot_id": "risk.kill_switch",
  "decision": "REJECT",
  "reason_code": "STRATEGY_BUDGET_EXCEEDED",
  "trigger_reason": "INTRADAY_DRAWDOWN_EXCEEDED",
  "inputs_used": [
    "portfolio_guard.drawdown"
  ],
  "metrics": {
    "intraday_drawdown_pct": 13.2,
    "weekly_drawdown_pct": 8.4,
    "reject_rate_5min": 4.1,
    "ws_dead_seconds": 0,
    "open_positions": 3
  },
  "activated_at": "2026-05-09T09:10:00Z",
  "require_manual_reset": true,
  "checked_at": "2026-05-09T09:11:05Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Stores a single active flag and trigger metadata in Redis. This key is the authoritative source of truth for all guardrails.

State stores

Cold-start recovery

On cold start, read Redis key. If key is missing (first deploy or Redis flush), default to active=false and log a WARNING.

On restart

Redis state is re-read immediately. If Redis is unreachable on startup, the bot activates with trigger_reason=STALE_MARKET_DATA until Redis is reachable.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

0.1 0.2 0.3 0.4 0.5 0.6 2.1 2.2 2.3 2.4 2.5 2.6 2.8 4.1 4.10 4.11 4.12 4.13 4.14 4.15 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 1.1 1.10 1.11 1.12 1.13 1.14 1.15 1.16 1.3 1.4 1.5 1.6 1.7 1.8 1.9 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 3.1 3.10 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 3.2 3.20 3.21 3.22 3.23 3.24 3.3 3.4 3.5 3.6 3.7 3.8 3.9

External services

23. Security Surfaces

KillSwitch holds no secrets and makes no signed calls. Its only write target is the internal Redis key. The Admin UI kill flag channel must be authenticated and audit-logged.

Signing surface

This bot does NOT sign anything.

Abuse vectors considered

• Unauthorized Redis write to clear the active flag and resume trading without operator review
• Race condition where two activations compete and one clears the trigger_reason

Mitigations

• Redis SET is atomic; activation is monotonic when require_manual_reset=true
• Admin UI kill-flag channel requires authenticated operator session and is audit-logged
• Deactivation via Admin UI requires explicit confirmation and logs operator identity

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

KillSwitch is the most critical bot in the system. Every activation is a P0 incident requiring immediate operator attention. Never auto-reset without confirming root cause.

On-call actions

Manual overrides

• polytraders bot reset killswitch — Clears the active flag in Redis after operator confirms root cause resolved. Requires Risk pod lead sign-off and is audit-logged.
• polytraders bot status killswitch — Prints current Redis state including trigger_reason, activated_at, and require_manual_reset flag.

Healthcheck

GET /health → 200 if Redis is reachable and key read latency < 5ms.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%