1.5 RateLimitGovernor

1. Bot Identity

Operational profile

2. Purpose

RateLimitGovernor prevents the system from exceeding Polymarket's CLOB order send-rate limits at both the per-market and per-account levels. It reads live rate-limit headers from CLOB responses (X-RateLimit-Remaining, X-RateLimit-Reset), maintains sliding-window counters, and either delays (reshapes) or rejects OrderIntents when the remaining budget falls below configured thresholds. Cancel and risk-flatten requests always receive priority allocation over new open orders. The bot is fail-closed: if rate-limit state cannot be determined, new order intents are rejected until state is re-established.

3. Why This Bot Matters

• Order send-rate exceeds CLOB limit

  Polymarket's CLOB enforces rate limits via Cloudflare. Exceeding the limit produces HTTP 429 responses, which cause order rejections, increased latency, and potential temporary IP/key bans that block all trading — including urgent risk-flatten operations.

• No priority for cancel/risk-flatten requests

  If rate budget is exhausted by new open orders, urgent cancellation or position-flatten requests may be queued or dropped, leaving dangerous open exposure during fast market moves.

• Rate budget not read from live CLOB headers

  Hard-coded rate limits may diverge from Polymarket's actual published limits. Reading live headers ensures the system adapts to any policy changes without a code deploy.

• Per-market throttle not separated from per-account throttle

  A high-frequency strategy on one market can exhaust the account's global rate budget, silently starving other markets of order capacity.

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

{ "public_req_per_min": 200 }

if (windowCount.public >= p.hard) return reject('RATE_LIMIT_GOVERNOR_BUDGET_EXHAUSTED'); else if (windowCount.public >= p.warning) return warn('RATE_LIMIT_GOVERNOR_BUDGET_WARN');

{ "trading_req_per_min": 100 }

if (windowCount.trading >= p.hard) return reject('RATE_LIMIT_GOVERNOR_BUDGET_EXHAUSTED'); else if (windowCount.trading >= p.warning) return reshape({defer_ms: msUntilWindowReset()});

{ "priority_cancel_over_open": true }

if (params.priority_cancel_over_open && intent.type == 'CANCEL') return approve_from_reserved_budget();

{ "priority_risk_flatten": true }

if (params.priority_risk_flatten && intent.type == 'RISK_FLATTEN') return approve_unconditionally();

8. Default Configuration

{
  "bot_id": "risk.rate_limit_governor",
  "version": "2.0.0",
  "mode": "hard_guard",
  "defaults": {
    "public_req_per_min": 200,
    "trading_req_per_min": 100,
    "priority_cancel_over_open": true,
    "priority_risk_flatten": true
  },
  "locked": {
    "priority_risk_flatten": {
      "min": true
    },
    "trading_req_per_min": {
      "max": 100
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent from Strategy layer with intent type (open / cancel / risk-flatten).
2. Check KillSwitch active flag; if active, reject all open-order intents immediately. Cancel and risk-flatten intents still proceed via their priority paths.
3. If intent type is RISK_FLATTEN and priority_risk_flatten=true, approve unconditionally and bypass all rate counters.
4. If intent type is CANCEL and priority_cancel_over_open=true, approve from the reserved cancel budget and bypass the standard trading counter.
5. Read the current sliding-window counter for the target market (per-market bucket) and for the account (global trading bucket).
6. Check account-level trading counter against trading_req_per_min. If at or above the hard limit, return HARD_REJECT with RATE_LIMIT_GOVERNOR_BUDGET_EXHAUSTED.
7. Check per-market counter against the per-market sub-limit (trading_req_per_min / active_market_count). If at or above the per-market hard limit, return HARD_REJECT with RATE_LIMIT_GOVERNOR_MARKET_THROTTLED.
8. If either counter is in the warning zone (80–100% of limit), return RESHAPE with constraints.defer_ms set to the milliseconds until the current window resets (from X-RateLimit-Reset header).
9. Approve the intent; increment both the per-market and per-account counters; update counters from the next CLOB response headers.
10. On each CLOB response, sync internal counters with X-RateLimit-Remaining to detect drift between internal estimates and Polymarket-reported values.

10. Reference Implementation

Maintains per-market and per-account sliding-window counters. On each intent, checks the KillSwitch and priority paths first, then evaluates both counters before approving, reshaping, or rejecting. Syncs counters from live X-RateLimit headers on every CLOB response.

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

FUNCTION evaluateRateLimit(intent):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active AND intent.type == 'OPEN':
    EMIT RiskVote(decision=HARD_REJECT, reason=KILL_SWITCH_ACTIVE)
    RETURN

  // --- 1. Priority paths ---
  IF intent.type == 'RISK_FLATTEN' AND params.priority_risk_flatten:
    EMIT RiskVote(decision=APPROVE, reason=RATE_LIMIT_GOVERNOR_PRIORITY_FLATTEN)
    RETURN
  IF intent.type == 'CANCEL' AND params.priority_cancel_over_open:
    reserved = FETCH internal.counter.reserved_cancel_budget
    IF reserved.remaining > 0:
      reserved.remaining -= 1
      EMIT RiskVote(decision=APPROVE, reason=RATE_LIMIT_GOVERNOR_PRIORITY_CANCEL)
    ELSE:
      EMIT RiskVote(decision=HARD_REJECT, reason=RATE_LIMIT_GOVERNOR_CANCEL_BUDGET_EXHAUSTED)
    RETURN

  // --- 2. Read counters ---
  tradingWindow = FETCH internal.counter.trading_window
  marketWindow  = FETCH internal.counter.market_window(intent.market_id)
  IF tradingWindow IS NULL OR marketWindow IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=RATE_LIMIT_GOVERNOR_STATE_UNKNOWN)
    RETURN

  // --- 3. Hard limit checks ---
  IF tradingWindow.count >= params.trading_req_per_min.hard:
    EMIT RiskVote(decision=HARD_REJECT, reason=RATE_LIMIT_GOVERNOR_BUDGET_EXHAUSTED)
    RETURN
  perMarketHard = params.trading_req_per_min.hard / activeMarketCount()
  IF marketWindow.count >= perMarketHard:
    EMIT RiskVote(decision=HARD_REJECT, reason=RATE_LIMIT_GOVERNOR_MARKET_THROTTLED)
    RETURN

  // --- 4. Warning zone → reshape with defer ---
  IF tradingWindow.count >= params.trading_req_per_min.warning OR
     marketWindow.count >= perMarketHard * 0.8:
    resetMs = tradingWindow.reset_at_ms - now_ms()
    EMIT RiskVote(decision=RESHAPE_REQUIRED,
                  reason=RATE_LIMIT_GOVERNOR_BUDGET_WARN,
                  constraints={defer_ms: max(resetMs, 0)})
    RETURN

  // --- 5. Approve and increment counters ---
  tradingWindow.count += 1
  marketWindow.count  += 1
  EMIT RiskVote(decision=APPROVE,
                reason=RATE_LIMIT_GOVERNOR_PASS,
                checked_at=now_iso())

// Called on every CLOB API response to sync internal counters
FUNCTION syncFromClobHeaders(response):
  remaining = response.headers.get('X-RateLimit-Remaining')
  reset_at  = response.headers.get('X-RateLimit-Reset')
  IF remaining IS NOT NULL:
    tradingWindow.count = params.trading_req_per_min.hard - int(remaining)
    tradingWindow.reset_at_ms = int(reset_at) * 1000

SDK calls used

• clob_auth.GET('/orders') — reads X-RateLimit-Remaining header from response
• clob_auth.POST('/order') — reads X-RateLimit-Remaining header from response
• internal.counter.trading_window.get()
• internal.counter.market_window.get(market_id)
• internal.killswitch.status()

Complexity: O(1) — constant-time counter lookup and increment per intent

11. Wire Examples

Input — what arrives on the wire

OrderIntent — open order when rate is in warning zone — internal

{
  "intent_id": "int_e5f6a7b8c9d0e1f2",
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "side": "BUY",
  "outcome": "YES",
  "size_usd": 200,
  "price": 0.48,
  "intent_type": "OPEN",
  "generated_at_ms": 1746787260000
}

Internal rate counter state — internal

{
  "trading_window_count": 87,
  "trading_hard_limit": 100,
  "market_window_count": 22,
  "market_hard_limit": 25,
  "window_reset_at_ms": 1746787320000,
  "last_header_remaining": 13
}

Output — what the bot emits

RiskVote — RESHAPE (defer until window reset)

{
  "guard_id": "risk.rate_limit_governor",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "RATE_LIMIT_GOVERNOR_BUDGET_WARN",
  "message": "Trading rate 87/100 req/min (87%). Defer by 4200ms until window resets at 2026-05-09T12:02:00Z.",
  "constraints": {
    "defer_ms": 4200,
    "passive_only": false,
    "close_only": false
  },
  "inputs_used": [
    "clob_auth.ratelimit_headers",
    "internal.sliding_window.trading",
    "internal.sliding_window.market"
  ],
  "checked_at": "2026-05-09T12:01:15Z"
}

RiskVote — HARD_REJECT (budget exhausted)

{
  "guard_id": "risk.rate_limit_governor",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "RATE_LIMIT_GOVERNOR_BUDGET_EXHAUSTED",
  "message": "Trading rate 100/100 req/min. Rate budget exhausted for this window. Intent dropped.",
  "constraints": {},
  "inputs_used": [
    "clob_auth.ratelimit_headers",
    "internal.sliding_window.trading"
  ],
  "checked_at": "2026-05-09T12:01:30Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.rate_limit_governor",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "RATE_LIMIT_GOVERNOR_BUDGET_WARN",
  "message": "Trading rate at 87/100 req/min (87%). Deferring intent by 4200ms until window resets.",
  "constraints": {
    "defer_ms": 4200,
    "passive_only": false,
    "close_only": false
  },
  "inputs_used": [
    "clob_auth.ratelimit_headers",
    "internal.sliding_window.trading",
    "internal.killswitch.status"
  ],
  "checked_at": "2026-05-09T12:01:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Risk overview / RateLimitGovernor
• Grafana — API health / CLOB rate-limit utilisation and 429 history

16. Developer Reporting

{
  "bot_id": "risk.rate_limit_governor",
  "decision": "RESHAPE_REQUIRED",
  "reason_code": "RATE_LIMIT_GOVERNOR_BUDGET_WARN",
  "inputs_used": [
    "clob_auth.ratelimit_headers",
    "internal.sliding_window.trading"
  ],
  "metrics": {
    "trading_counter": 87,
    "trading_hard_limit": 100,
    "market_counter": 22,
    "market_hard_limit": 25,
    "window_reset_in_ms": 4200,
    "last_ratelimit_remaining_from_header": 13
  },
  "checked_at": "2026-05-09T12:01:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, all counters initialise to 0. The first CLOB response syncs them to the live X-RateLimit-Remaining value. Until the first sync, intents are allowed up to 50% of the hard limit as a conservative bootstrap budget.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Strategy flooding small-sized intents to consume the rate budget of other strategies
• Race condition: two concurrent strategies both checking the counter before either increments, causing double-approval near the hard limit

Mitigations

• Global mutex on counter increment prevents concurrent double-counting
• Per-market sub-limits prevent a single market from consuming the full account budget
• Cancel and risk-flatten budgets are reserved and cannot be consumed by open-order intents

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

RateLimitGovernor incidents are typically a 429 from Polymarket (counter miscalibrated or burst overrun) or a stale header sync. A 429 in production is a P1 incident because it may block all order operations including risk-flattening.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/ratelimitgovernor → 200 if trading window utilisation < 80%, last X-RateLimit-Remaining header read < 60s ago, and zero 429 responses in the last 5 minutes; red if utilisation >= 100%, any 429 observed, or header sync stale > 60s.

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%