QueueWarden
QueueWarden polices the rate at which orders and cancel-replace operations are sent to the Polymarket CLOB V2 and manages the maker queue position of
What it does
QueueWarden polices the rate at which orders and cancel-replace operations are sent to the Polymarket CLOB V2 and manages the maker queue position of resting orders. It enforces a cap on cancel-replace operations per minute to avoid CLOB rate-limit rejections, monitors drift between the resting quote price and the best bid/ask, and cancels stale resting orders that have not been filled within the stale_ttl_s window. QueueWarden also injects builderCode (bytes32) into cancel-replace messages to maintain builder attribution continuity across order lifecycle events.
Pipeline placement
Applies to: All resting maker orders on Polymarket CLOB V2 that are subject to quote drift or TTL management
Why it matters
| If this fails | Consequence |
|---|---|
| Excessive cancel-replace rate | Polymarket CLOB V2 enforces per-API-key rate limits. Exceeding them causes 429 rejections, breaking the order submission pipeline and potentially leaving the strategy with unintended open positions. |
| Quote drift not corrected | A resting order priced more than drift_ticks_threshold ticks away from the current best bid/ask is no longer competitive; it accumulates adverse-selection risk without filling. |
| Stale resting order not cancelled | An order sitting in the book beyond stale_ttl_s may fill at a price that no longer reflects the strategy's current view, creating unintended exposure. |
| builderCode absent from cancel-replace message | Builder attribution is broken for the replacement order; maker rebates may not be correctly attributed. |
Inputs
Internal inputs
| Input | Source | Required | Use |
|---|---|---|---|
| Active resting order registry | internal order state store | required | Track all resting orders with their price, side, placed_at_ms, and queue position. |
| CLOB V2 order book snapshot (best bid/ask) | clob_auth (authenticated book endpoint) | required | Compute drift between resting order price and current best bid/ask in ticks. |
| Cancel-replace rate counter | internal sliding-window counter (Redis) | required | Enforce cancel_replace_per_min_cap by tracking ops in the last 60s. |
| ExecutionPlan for replacement order | exec.smart_router | required | Receive the updated quote parameters when a cancel-replace is triggered. |
Authority
What this bot is permitted to do
State
Readiness
General live
Status
live
Class
Execution Utility
Default mode
general_live
Developer owner
Polytraders core
Capital impact
Direct
Reason codes emitted
| Code | Severity | Meaning | Action |
|---|---|---|---|
| QUEUE_WARDEN_HOLD | INFO | Resting order is within drift tolerance, below stale TTL, and queue position is acceptable. | No action. Emit QueueDecision.HOLD. |
| QUEUE_WARDEN_DRIFT_EXCEEDED | RESHAPE | Order price has drifted more than drift_ticks_threshold ticks from the current best bid/ask. | Cancel and replace order at current best price with refreshed builderCode. |
| QUEUE_WARDEN_STALE_ORDER | RESHAPE | Resting order has exceeded stale_ttl_s without being filled. | Cancel order without replacement. Emit QueueDecision.CANCEL_STALE. |
| QUEUE_WARDEN_QUEUE_DEGRADED | RESHAPE | Maker queue position has worsened beyond min_queue_position threshold. | Cancel and replace to re-enter at the front of the queue. |
| QUEUE_WARDEN_RATE_CAP_HIT | WARN | cancel_replace_per_min_cap has been reached; excess operations are queued for the next rate window. | Enqueue op in rate-deferred queue. Emit WARN. Do not block non-cancel-replace ops. |
| QUEUE_WARDEN_BOOK_UNAVAILABLE | HARD_REJECT | CLOB V2 book endpoint is unreachable; drift cannot be computed for this order. | Cancel order as safe fallback. Emit QueueDecision.CANCEL_STALE. |
| QUEUE_WARDEN_STATE_UNAVAILABLE | HARD_REJECT | Internal order registry is unreachable; evaluation cannot proceed. | Pause all evaluation. Emit WARN. Resume when state store reconnects. |
| KILL_SWITCH_ACTIVE | HARD_REJECT | Global kill switch is active; all resting orders are cancelled immediately. | Cancel all resting orders. Emit no replacement orders. |
Related bots in Execution
Used by
Reverse index — strategies that currently reference exec.queuewarden. If you change this bot's authority or reason codes, these strategies must re-pass shadow.
| Strategy | State | Activity |
|---|---|---|
| Crypto Q2 — basket rebalance | frozen | last triggered 16m ago |
| US Elect — book-builder | demo-wired | last triggered 23m ago |
| NBA H2H — moneyline market-make | demo-wired | last triggered 30m ago |
Showing 3 of 3 · demo-wired ≠ production-live
Why this matters
Execution bots does NOT propose new positions; only routes and shapes approved intents. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →