LiquidityGuard
LiquidityGuard prevents strategies from placing orders that would consume too much of the visible order-book depth on a given market.
What it does
LiquidityGuard prevents strategies from placing orders that would consume too much of the visible order-book depth on a given market. It checks book depth, spread, and top-of-book freshness on every OrderIntent and either approves, downsizes, or rejects the order. It cannot change the market, the direction, or the strategy intent — only the size and the timing of execution.
Pipeline placement
Applies to: Every OrderIntent before it reaches the execution layer
Why it matters
| If this fails | Consequence |
|---|---|
| Thin-book consumption | An oversized order eats through the visible top-of-book and walks the price several ticks against the user before fully filling, resulting in worse-than-expected execution. |
| Stale book approved | If depth data is not refreshed, the system may believe there is enough liquidity when the book has thinned out since the last snapshot, leading to surprise price impact. |
| Excessive spread ignored | Trading into a wide spread means crossing more slippage than the strategy priced in, which can turn a positive-expected-value order into a losing one. |
| No size floor on top-of-book | An order placed on a market with near-zero resting size can move the price dramatically even for small notional amounts. |
Inputs
Polymarket inputs
| Input | Source | Required | Use |
|---|---|---|---|
| CLOB order book — top 50 levels (bid and ask) | CLOB | required | Compute total visible USD depth and the inside spread; compare against thresholds. |
| Best-bid / best-ask resting size | WebSocket | required | Determine how large the top-of-book is to enforce min_top_of_book_usd. |
| 30-day median spread for the target market | Data API | required | Calculate the spread multiple: current spread divided by 30d median, compared to max_spread_multiple. |
| Top-of-book last-update timestamp | WebSocket | required | Detect stale book data; reject if older than stale_top_seconds. |
Internal inputs
| Input | Source | Required | Use |
|---|---|---|---|
| Strategy budget remaining for this market | PortfolioGuard | required | Cap the reshape size to the budget remaining so downsized orders don't exceed the portfolio limit. |
| KillSwitch active flag | KillSwitch | required | If KillSwitch is active, reject all orders immediately without consulting book data. |
Authority
What this bot is permitted to do
State
Readiness
General live
Status
live
Class
Guardrail
Default mode
general_live
Developer owner
Polytraders core — Risk pod
Capital impact
Direct
Reason codes emitted
| Code | Severity | Meaning | Action |
|---|---|---|---|
| KILL_SWITCH_ACTIVE | HARD_REJECT | Global kill switch is active; no orders may proceed. | Immediately return HARD_REJECT without consulting book data. |
| STALE_MARKET_DATA | HARD_REJECT | Book snapshot is older than stale_top_seconds hard limit. | Return HARD_REJECT; wait for fresh book before retrying. |
| INSUFFICIENT_VISIBLE_DEPTH | HARD_REJECT | Order size exceeds the hard depth ceiling or top-of-book is below the hard floor. | Return HARD_REJECT or RESHAPE_REQUIRED depending on which threshold was breached. |
| SPREAD_TOO_WIDE | HARD_REJECT | Current spread exceeds max_spread_multiple times the 30-day median. | Return HARD_REJECT; log spread_multiple value. |
| LIQUIDITY_GUARD_RESHAPE_DEPTH | RESHAPE | Order size is above the default depth percentage but below the hard ceiling. | Return RESHAPE_REQUIRED with constraints.max_size_usd = visibleDepthUsd * default_pct. |
| LIQUIDITY_GUARD_SPREAD_WARN | WARN | Spread is between the warning and hard multiple thresholds. | Attach warning annotation to APPROVE; do not block. |
| LIQUIDITY_GUARD_NEGRISK_THIN_BOOK | WARN | NegRisk market book is thin relative to the requested size, increasing definition-shift exposure. | Attach warning annotation; Strategy may reduce size further. |
| LIQUIDITY_GUARD_TOP_BOOK_RESHAPE | RESHAPE | Top-of-book USD is between the warning and hard floor thresholds. | Return RESHAPE_REQUIRED with constraints.max_size_usd = topOfBookUsd. |
Related bots in Risk Guardrail
Used by
Reverse index — strategies that currently reference risk.liquidityguard. If you change this bot's authority or reason codes, these strategies must re-pass shadow.
| Strategy | State | Activity |
|---|---|---|
| US Elections — sentiment fade | demo-wired | last triggered 18m ago |
Showing 1 of 1 · demo-wired ≠ production-live
Why this matters
Risk Guardrail bots does NOT propose intents or sign orders; only permits or blocks. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →