6.17 APIDegradationMonitor

1. Bot Identity

Operational profile

2. Purpose

Watches every external API surface Polytraders depends on (CLOB v2 REST, CLOB WebSocket, Polymarket metadata REST, Ethereum RPC, builder fee oracle) and publishes a per-surface health envelope (latency p50/p99, error rate, last_success_ts_ms). Risk and Strategy bots consume this envelope to decide whether to operate normally, degrade, or pause.

3. Why This Bot Matters

• Cascading failures from a single dead dependency

  Without an explicit health signal, every bot infers liveness from its own latest call — producing inconsistent retreat behaviour across the system.

• Silent degradations

  An API can stay up but slow to 30-second responses; bots without an explicit threshold keep blocking on it instead of failing fast.

• Postmortem confusion

  Without a health timeline, postmortems cannot answer 'what was the actual external latency at 14:23?'.

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

{ "probe_interval_ms": 5000 }

schedule.every(p.probe_interval_ms).do(probe);

{ "warn_p99_ms": 750 }

if (p99 > p.warn_p99_ms) status = 'DEGRADED';

{ "fail_p99_ms": 5000 }

if (p99 > p.fail_p99_ms) status = 'DOWN';

{ "fail_error_rate_pct": 25 }

if (errRate > p.fail_error_rate_pct) status = 'DOWN';

8. Default Configuration

{
  "probe_interval_ms": 5000,
  "warn_p99_ms": 750,
  "fail_p99_ms": 5000,
  "fail_error_rate_pct": 25
}

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 surface s:
  samples = window(s, 60_000)
  p50, p99 = quantiles(samples)
  err = error_rate(samples)
  status = classify(p99, err, p)
  emit('ApiHealthReport', s, status, p50, p99, err, last_success_ts_ms[s])

11. Wire Examples

Input — what arrives on the wire

{
  "surface": "clob_v2_rest",
  "samples": [
    {
      "ts_ms": 1715260000000,
      "latency_ms": 220,
      "ok": true
    }
  ]
}

Output — what the bot emits

{
  "kind": "ApiHealthReport",
  "surface": "clob_v2_rest",
  "status": "OK",
  "p50_ms": 220,
  "p99_ms": 220,
  "error_rate_pct": 0
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "kind": "ApiHealthReport",
  "surface": "clob_v2_rest",
  "status": "DEGRADED",
  "p50_ms": 220,
  "p99_ms": 980,
  "error_rate_pct": 4.1,
  "last_success_ts_ms": 1715260000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Dashboards

• 6.17 overview dashboard

16. Developer Reporting

"Per emission: surface, status, p50, p99, error_rate, sample_count."

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Per-surface rolling sample buffer + last status. In-memory; reseeds on 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

Emits to (downstream consumers)

Required before (graph.required_before)

risk.killswitch exec.smart_router

23. Security Surfaces

Probe credentials are read-only API keys with no order-placement scope.

Signing surface

None — bot does not sign or submit.

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

If a surface is stuck DEGRADED with no obvious cause, increase probe_interval_ms temporarily and inspect upstream provider's status page.

On-call actions

Manual overrides

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

Healthcheck

GET /healthz/api_degradation_monitor → 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%