2.11 ExchangeStatusMonitor

1. Bot Identity

Operational profile

2. Purpose

ExchangeStatusMonitor treats Polymarket itself as a degradable dependency. It polls CLOB V2 endpoint health, watches for reject-rate spikes, and parses public maintenance signals. When degradation is confirmed, it emits ObservationReports that trigger pause or de-risk actions across the exec layer.

3. Why This Bot Matters

• Exchange degradation not detected

  Orders continue to be submitted to a degraded CLOB, accumulating 429 errors, failed acks, and stale fills.

• Maintenance window missed

  Orders submitted during a scheduled maintenance window are rejected without useful error context, causing unnecessary retries.

• Resume too early after incident

  Resuming order submission before the CLOB has fully recovered causes a second wave of errors and potentially double-fills on retry.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "pause_on_status": ["degraded", "maintenance"] }

if status in params.pause_on_status: emit(EXCHANGE_STATUS_PAUSE)

{ "flatten_on_status": ["outage"] }

if status in params.flatten_on_status: emit(EXCHANGE_STATUS_FLATTEN)

{ "poll_interval_s": 15 }

assert params.poll_interval_s <= params.hard

{ "resume_quarantine_min": 5 }

if params.resume_quarantine_min < params.hard: raise ConfigError

8. Default Configuration

{
  "bot_id": "exec.exchangestatusmonitor",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "pause_on_status": [
      "degraded",
      "maintenance"
    ],
    "flatten_on_status": [
      "outage"
    ],
    "poll_interval_s": 15,
    "resume_quarantine_min": 5
  },
  "locked": {
    "poll_interval_s": {
      "max": 60
    },
    "resume_quarantine_min": {
      "min": 1
    }
  }
}

9. Implementation Flow

1. Every poll_interval_s: GET clob_public /health; record status_code and latency.
2. If status_code != 200 or latency > 2000ms: increment consecutive_error_count.
3. After 3 consecutive errors: set exchange_status=degraded.
4. Optionally: fetch Polymarket public status page; parse for maintenance or outage keywords.
5. Read reject_rate from OrderLifecycleManager metrics; if reject_rate > 10% over 60s: treat as degraded signal.
6. Determine composite status: healthy, degraded, maintenance, or outage.
7. If status in pause_on_status: emit ObservationReport(EXCHANGE_STATUS_PAUSE).
8. If status in flatten_on_status: emit ObservationReport(EXCHANGE_STATUS_FLATTEN).
9. When status returns to healthy: start resume_quarantine_min timer; emit EXCHANGE_STATUS_RESUMING.
10. After quarantine completes: emit EXCHANGE_STATUS_HEALTHY; clear pause state.

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.

STATE: consecutiveErrors = 0, exchangeStatus = 'healthy',
       quarantineStartMs = None

FUNCTION pollExchange():
  t0 = now_ms()
  resp = clob_public.GET('/health', timeout=2000)
  latency = now_ms() - t0

  IF resp IS NULL OR resp.status_code != 200 OR latency > 2000:
    consecutiveErrors += 1
  ELSE:
    consecutiveErrors = 0

  // Reject-rate check
  rejectRate = FETCH metrics.reject_rate_60s()
  IF rejectRate > 0.10:
    consecutiveErrors = max(consecutiveErrors, 3)

  // Status determination
  IF consecutiveErrors >= 3:
    IF statusPage.contains('outage'):
      exchangeStatus = 'outage'
    ELSE:
      exchangeStatus = 'degraded'
  ELIF statusPage.contains('maintenance'):
    exchangeStatus = 'maintenance'
  ELSE:
    exchangeStatus = 'healthy'

  // Emit ObservationReport
  IF exchangeStatus IN params.flatten_on_status:
    EMIT ObservationReport(EXCHANGE_STATUS_FLATTEN)
  ELIF exchangeStatus IN params.pause_on_status:
    EMIT ObservationReport(EXCHANGE_STATUS_PAUSE)
  ELIF exchangeStatus == 'healthy' AND quarantineStartMs IS None:
    quarantineStartMs = now_ms()
    EMIT ObservationReport(EXCHANGE_STATUS_RESUMING)
  ELIF exchangeStatus == 'healthy':
    IF now_ms() - quarantineStartMs >= params.resume_quarantine_min * 60000:
      quarantineStartMs = None
      EMIT ObservationReport(EXCHANGE_STATUS_HEALTHY)

SCHEDULE pollExchange EVERY params.poll_interval_s

SDK calls used

• clob_public.GET('/health')
• statusPage.fetch('https://status.polymarket.com')

Complexity: O(1) per poll cycle

11. Wire Examples

Input — what arrives on the wire

Poll trigger + health response — internal scheduler + clob_public

{
  "poll_ts_ms": 1746770400000,
  "health_status_code": 503,
  "latency_ms": 2100,
  "consecutive_errors": 4
}

Output — what the bot emits

ObservationReport — EXCHANGE_STATUS_PAUSE

{
  "report_id": "rep_6f7a8b9c0d1e2f3a",
  "bot_id": "exec.exchangestatusmonitor",
  "exchange_status": "degraded",
  "verdict": "EXCHANGE_STATUS_PAUSE",
  "consecutive_errors": 4,
  "measured_at_ms": 1746770400000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "rep_6f7a8b9c0d1e2f3a",
  "trace_id": "trc_5e6f7a8b9c0d1e2f",
  "bot_id": "exec.exchangestatusmonitor",
  "exchange_status": "degraded",
  "verdict": "EXCHANGE_STATUS_PAUSE",
  "consecutive_errors": 4,
  "reject_rate_pct": 15.2,
  "measured_at_ms": 1746770400000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "exchange_status": "degraded",
  "consecutive_errors": 4,
  "reject_rate_pct": 15.2,
  "status_page_parsed": true,
  "status_page_result": "No active incident",
  "verdict": "EXCHANGE_STATUS_PAUSE",
  "quarantine_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, re-poll health immediately; treat cold start as 0 consecutive errors.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Injecting fake health endpoint responses to trigger spurious exchange-pause events
• Flooding status-page parser with malformed HTML to suppress maintenance detection

Mitigations

• Health endpoint responses validated against expected schema; unexpected payloads treated as errors
• Status-page parsing uses keyword matching with a known-safe whitelist; malformed pages treated as 'no incident'

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

ExchangeStatusMonitor incidents require checking the Polymarket status page and CLOB health endpoint. Never manually lift a pause without confirming exchange health.

On-call actions

Manual overrides

• polytraders bot force-resume exec.exchangestatusmonitor — Exchange is confirmed healthy but quarantine has not yet expired; use only with Exec pod lead approval.

Healthcheck

GET /internal/health/exchangestatusmonitor -> 200 if exchange_status=healthy, consecutive_errors=0, quarantine_active=false, polling running. Red: exchange_status in (degraded, outage), consecutive_errors >= 3, polling interval missed.

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%