MarketScanner
MarketScanner continuously scans every live Polymarket market on each scan cycle and scores each one for tradability based on volume, book depth, spre
What it does
MarketScanner continuously scans every live Polymarket market on each scan cycle and scores each one for tradability based on volume, book depth, spread, and resolution metadata. Markets that pass all filters emit an OrderIntent candidate to the Strategy layer for further evaluation. MarketScanner is strictly read-only — it never submits, signs, or modifies orders. All output is a recommendation that Strategy may accept or ignore.
Pipeline placement
Applies to: All live Polymarket markets on every scan cycle
Why it matters
| If this fails | Consequence |
|---|---|
| Strategy allowed to consider illiquid markets | Without a tradability filter, strategies may generate intents on markets too thin to fill without severe price impact, wasting compute and risking poor execution. |
| Stale market list used | A market that has resolved or been paused may still appear in a static list. Acting on it wastes budget and risks failed submissions. |
| Wide-spread markets not filtered | Markets with unusually wide spreads have high transaction costs. Without a spread filter, strategies may target them without accounting for the extra cost. |
| No volume floor applied | A market with near-zero 24-hour volume is unlikely to fill at a reasonable price. Surfacing it to Strategy without a volume check leads to wasted resources. |
Inputs
Polymarket inputs
| Input | Source | Required | Use |
|---|---|---|---|
| Full list of live markets with condition IDs and metadata | Gamma API | required | Enumerate every currently active market to scan on each cycle. |
| CLOB order book depth and last-trade timestamp per market | CLOB | required | Compute visible depth and detect markets with no recent trading activity. |
| Bid-ask spread per market | WebSocket | required | Filter out markets whose current spread exceeds max_spread_bps. |
| 24-hour trading volume per market | Data API | required | Apply the min_volume_24h_usd filter to exclude low-activity markets. |
| Market resolution rules text and neg-risk flag | Gamma API | optional | Pass resolution metadata to Strategy so it can assess resolution risk without re-fetching. |
Internal inputs
| Input | Source | Required | Use |
|---|---|---|---|
| KillSwitch active flag | KillSwitch | required | Suppress all OrderIntent candidate emissions when KillSwitch is active; continue scanning passively. |
| Strategy interest list | StrategyRegistry | optional | Prioritise markets that registered strategies have expressed interest in on each scan cycle. |
Authority
What this bot is permitted to do
State
Readiness
General live
Status
live
Class
Signal Service
Default mode
general_live
Developer owner
Polytraders core — Intelligence pod
Capital impact
Indirect
Reason codes emitted
| Code | Severity | Meaning | Action |
|---|---|---|---|
| INSUFFICIENT_VISIBLE_DEPTH | EXPLAIN | Market excluded because 24h volume or book depth is below the hard floor. | Exclude market from candidate list; log exclusion_breakdown. |
| SPREAD_TOO_WIDE | EXPLAIN | Market excluded because bid-ask spread exceeds the hard ceiling. | Exclude market from candidate list; log exclusion reason. |
| KILL_SWITCH_ACTIVE | HARD_REJECT | KillSwitch is active; candidate emissions are suppressed. | Complete the scan and score all markets but do not emit any OrderIntent candidates. |
| STALE_MARKET_DATA | HARD_REJECT | Gamma API or Data API unavailable; this scan cycle is halted. | Do not emit any candidates for this cycle; log the error. |
| PARAMETER_CHANGE_REQUIRES_APPROVAL | HARD_REJECT | scan_interval_s is below the locked hard minimum of 5s. | Reject the config change; do not apply. |
| MARKET_SCANNER_LOW_VOLUME | WARN | Market volume is between the warning and hard floor thresholds. | Include candidate with LOW_VOLUME warning flag; Strategy decides whether to proceed. |
| MARKET_SCANNER_THIN_BOOK | WARN | Market book depth is between the warning and hard floor thresholds. | Include candidate with THIN_BOOK warning flag. |
| MARKET_SCANNER_NEGRISK_THIN_BOOK | WARN | NegRisk market depth is below 2× min_book_depth_usd, indicating elevated definition-shift risk. | Include candidate with NEGRISK_THIN_BOOK warning flag. |
| NEGRISK_CONVERT_AVAILABLE | EXPLAIN | NegRisk market has enable_neg_risk=true; convert-arb may be available via NegRiskAdapter. | Annotate candidate with negrisk_convert_available=true. |
Related bots in Market Discovery
Used by
Reverse index — strategies that currently reference disc.marketscanner. 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 28m ago |
| US Elect — book-builder | demo-wired | last triggered 35m ago |
Showing 2 of 2 · demo-wired ≠ production-live
Why this matters
Market Discovery bots does NOT propose or execute trades; only scores and ranks. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →