1.17 MarketHaltDetector

1. Bot Identity

Operational profile

2. Purpose

Watches for market-level halt conditions across Polymarket — wide-spread blowouts, missing best bid/ask, locked or crossed books, and sudden order-rate collapse. When any halt condition fires, MarketHaltDetector quarantines the affected market_id so no new OrderIntent for that market can pass the Risk pipeline. It does not pause the whole system — only the affected market. Cleared automatically once conditions normalise for a configurable cool-off window, or manually via the Admin UI.

3. Why This Bot Matters

• Submitting orders into a halted book

  Orders sent into a market with no two-sided liquidity end up either rejected by the CLOB or filled at runaway prices once the book reopens.

• Treating wide-spread events as normal

  A market with a 30%+ inside spread is structurally untradeable; trading it anyway invites massive slippage and unfair fills.

• Manual halt management

  Without automated detection, ops staff must monitor every market by hand — which does not scale past a handful of markets.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "halt_spread_pct": 30 }

if (spreadPct(book) > p.halt_spread_pct) halt.activate(marketId, 'WIDE_SPREAD');

{ "trades_silent_ms": 60000 }

if (now - lastTradeMs > p.trades_silent_ms && bookHasLiquidity()) halt.activate(marketId, 'TRADE_SILENCE');

{ "cooloff_ms": 120000 }

if (healthyFor(marketId) > p.cooloff_ms) halt.clear(marketId);

{ "min_depth_usd": 250 }

if (topDepthUsd(book) < p.min_depth_usd) halt.activate(marketId, 'THIN_BOOK');

8. Default Configuration

{
  "halt_spread_pct": 30,
  "trades_silent_ms": 60000,
  "cooloff_ms": 120000,
  "min_depth_usd": 250
}

9. Implementation Flow

— not yet authored —

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

for each book_tick:
  if spread_pct(book) > p.halt_spread_pct: halt(market_id, 'WIDE_SPREAD'); continue
  if now - last_trade[market_id] > p.trades_silent_ms and depth_usd(book) > 0: halt(market_id, 'TRADE_SILENCE'); continue
  if depth_usd_top(book) < p.min_depth_usd: halt(market_id, 'THIN_BOOK'); continue
  if all_rules_clean_for(market_id, p.cooloff_ms): clear(market_id)
for each OrderIntent o:
  if is_halted(o.market_id): emit RiskVote(REJECT, RISK_MARKET_HALT); else PASS

11. Wire Examples

Input — what arrives on the wire

{
  "intent_id": "intent_001",
  "market_id": "0xabc",
  "side": "BUY",
  "size_usd": 100
}

Output — what the bot emits

{
  "vote": "REJECT",
  "reason_code": "RISK_MARKET_HALT",
  "explain": "Halted: inside spread 41% > 30% threshold."
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "vote": "REJECT",
  "market_id": "0xabc",
  "reason_code": "RISK_MARKET_HALT",
  "explain": "Halted: inside spread 41% > 30% threshold for 18s.",
  "ts_ms": 1715260000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Dashboards

• 1.17 overview dashboard

16. Developer Reporting

"Per halt activation: market_id, rule (WIDE_SPREAD/TRADE_SILENCE/THIN_BOOK), measured value, threshold, ts_ms, expected cooloff_until_ms."

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Per market_id: { halted: bool, halted_since_ms, last_rule, healthy_since_ms }. Persisted in fast key-value store; survives restart.

State stores

Cold-start recovery

Cold-start hydrates from fast KV; missing keys default to safe fallback.

On restart

All in-flight decisions are re-evaluated; no bot decision is trusted across restart without re-emit.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Requires (graph.requires)

intel.orderflowanalyzer

Required before (graph.required_before)

risk.killswitch exec.smart_router

23. Security Surfaces

Reads CLOB WebSocket; emits RiskVote internally only.

Signing surface

None — bot does not sign or submit.

Abuse vectors considered

• Admin UI 'force clear' endpoint requires Risk role + audit log entry.

Mitigations

• Rate-limit per source
• Audit-log every override
• Require role-based authz on admin paths

24. Polymarket V2 Compatibility

25. Versioning & Migration

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

Symptoms: many simultaneous halts → check upstream feed health. Single stuck market → manually clear via Admin UI then investigate the persistent rule violation.

On-call actions

Manual overrides

• polytraders bot pause 1.17 — Disables the bot's enforcement layer; downstream consumers fall back to safe defaults.

Healthcheck

GET /healthz/market_halt_detector → 200 if last successful evaluation < 60s ago.

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%