0.1 MarketScanner

1. Bot Identity

2. Purpose

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.

3. Why This Bot Matters

• 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.

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

{ "scan_interval_s": 30 }

if (p.scan_interval_s < p.hard) throw new ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "min_volume_24h_usd": 1000 }

if (market.volume24h < p.hard) return exclude('INSUFFICIENT_VISIBLE_DEPTH');

{ "min_book_depth_usd": 500 }

if (market.bookDepthUsd < p.hard) return exclude('INSUFFICIENT_VISIBLE_DEPTH');

{ "max_spread_bps": 400 }

if (market.spreadBps > p.hard) return exclude('SPREAD_TOO_WIDE');

8. Default Configuration

{
  "bot_id": "intel.market_scanner",
  "version": "1.0.0",
  "mode": "general_live",
  "defaults": {
    "scan_interval_s": 30,
    "min_volume_24h_usd": 1000,
    "min_book_depth_usd": 500,
    "max_spread_bps": 400
  },
  "locked": {
    "scan_interval_s": {
      "min": 5
    },
    "min_volume_24h_usd": {
      "min": 100
    },
    "min_book_depth_usd": {
      "min": 100
    }
  }
}

9. Implementation Flow

1. On each scan cycle (every scan_interval_s seconds), fetch the full list of live markets from Gamma API.
2. Check KillSwitch active flag; if active, complete the scan and update market scores but suppress all OrderIntent candidate emissions.
3. For each market in the list, fetch top-50 CLOB book depth and compute total visible_depth_usd.
4. For each market, fetch the current bid-ask spread from WebSocket and compute spread_bps.
5. For each market, fetch 24-hour trading volume from Data API.
6. Apply filters in order: (a) exclude if volume_24h < min_volume_24h_usd hard floor; (b) exclude if book_depth < min_book_depth_usd hard floor; (c) exclude if spread_bps > max_spread_bps hard ceiling.
7. For markets that pass all filters, attach resolution metadata (resolution rules text, neg-risk flag) from Gamma API.
8. Score each passing market on a composite tradability score based on depth, spread, and volume relative to thresholds.
9. Emit an OrderIntent candidate for each passing market to the Strategy layer, including: market_id, tradability score, depth, spread, volume, neg-risk flag, and scan timestamp.
10. Log the full scan results (pass/fail counts, filtered-out reason codes, and top-scoring markets) to the developer log.

10. Reference Implementation

On each scan cycle, fetches the full live market list from Gamma API, applies four tradability filters (volume, depth, spread, freshness), attaches neg-risk and resolution metadata, scores each passing market, and emits OrderIntent candidates to the Strategy layer.

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

FUNCTION scanCycle():
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  killswitchActive = ks.active

  // --- 1. Fetch live market list ---
  markets = FETCH gamma_api.GET('/markets?active=true&closed=false')
  IF markets IS NULL:
    LOG ERROR 'Gamma API unavailable — halting emission for this cycle'
    RETURN

  passed = []
  FOR market IN markets:
    // --- 2. Fetch per-market data ---
    vol24h = FETCH data_api.GET('/volume?market=' + market.condition_id)
    book   = fetchClobPublic('/book?market=' + market.condition_id)
    spread = ws_market.current_spread(market.condition_id)

    IF vol24h IS NULL OR book IS NULL OR spread IS NULL:
      CONTINUE  // skip — missing data; do not emit stale candidate

    // --- 3. Apply hard-floor filters ---
    depthUsd = SUM(level.size * level.price FOR level IN book.asks[:50] + book.bids[:50])
    spreadBps = spread.current_bps

    IF vol24h.usd < params.min_volume_24h_usd.hard:
      CONTINUE; reason=INSUFFICIENT_VISIBLE_DEPTH
    IF depthUsd < params.min_book_depth_usd.hard:
      CONTINUE; reason=INSUFFICIENT_VISIBLE_DEPTH
    IF spreadBps > params.max_spread_bps.hard:
      CONTINUE; reason=SPREAD_TOO_WIDE

    // --- 4. Compute warnings ---
    warnings = []
    IF vol24h.usd < params.min_volume_24h_usd.default:
      warnings.append('MARKET_SCANNER_LOW_VOLUME')
    IF depthUsd < params.min_book_depth_usd.default:
      warnings.append('MARKET_SCANNER_THIN_BOOK')
    IF spreadBps > params.max_spread_bps.warning:
      warnings.append('SPREAD_TOO_WIDE')

    // --- 5. Neg-risk qualification ---
    negRisk = market.neg_risk OR market.enable_neg_risk
    IF negRisk:
      // NegRisk markets: standard or augmented (open set)
      // Apply stricter depth check: require 2× min_book_depth_usd
      IF depthUsd < params.min_book_depth_usd.default * 2:
        warnings.append('MARKET_SCANNER_NEGRISK_THIN_BOOK')

    // --- 6. Resolution metadata ---
    resMeta = FETCH gamma_api.GET('/market/' + market.condition_id)
    resSource = resMeta.resolution_source  // e.g. 'UMA'

    // --- 7. Tradability score ---
    score = 0.4 * min(vol24h.usd / 10000, 1.0)
           + 0.4 * min(depthUsd / 5000, 1.0)
           + 0.2 * max(0, 1 - spreadBps / params.max_spread_bps.default)

    passed.append({
      market_id: market.condition_id,
      tradability_score: score,
      volume_24h_usd: vol24h.usd,
      book_depth_usd: depthUsd,
      spread_bps: spreadBps,
      neg_risk: negRisk,
      resolution_source: resSource,
      warnings: warnings,
      scanned_at: now_iso()
    })

  // --- 8. Emit candidates (suppressed if KillSwitch active) ---
  IF NOT killswitchActive:
    FOR candidate IN passed:
      EMIT OrderIntentCandidate(candidate)

  // --- 9. Log cycle stats ---
  LOG INFO { markets_scanned: len(markets), passed: len(passed),
             excluded: len(markets)-len(passed), killswitch: killswitchActive }

Helpers used

SDK calls used

• fetchClobPublic('/book?market=0xabc123...&depth=50')
• gamma_api.GET('/markets?active=true&closed=false')
• gamma_api.GET('/market/0xabc123...')
• data_api.GET('/volume?market=0xabc123...&window=24h')
• ws_market.current_spread('0xabc123...')

Complexity: O(M) where M = number of live markets per scan cycle

11. Wire Examples

Input — what arrives on the wire

Gamma API market list entry — gamma_api

{
  "condition_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "question": "Will event X happen before 2026-06-01?",
  "active": true,
  "closed": false,
  "neg_risk": false,
  "enable_neg_risk": false,
  "resolution_source": "UMA Optimistic Oracle",
  "minimum_tick_size": 0.01,
  "volume_24h": "8540.00",
  "spread_bps": 210
}

Output — what the bot emits

OrderIntent candidate — market passing all filters

{
  "scanner_id": "disc.market_scanner",
  "market_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "condition_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "tradability_score": 0.78,
  "volume_24h_usd": 8540,
  "book_depth_usd": 3200,
  "spread_bps": 210,
  "neg_risk": false,
  "resolution_source": "UMA Optimistic Oracle",
  "warnings": [],
  "scanned_at": "2026-05-09T11:30:00Z",
  "type": "CANDIDATE"
}

OrderIntent candidate — neg-risk market with thin-book warning

{
  "scanner_id": "disc.market_scanner",
  "market_id": "0x8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b",
  "condition_id": "0x8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b",
  "tradability_score": 0.42,
  "volume_24h_usd": 2100,
  "book_depth_usd": 620,
  "spread_bps": 340,
  "neg_risk": true,
  "resolution_source": "UMA Optimistic Oracle",
  "warnings": [
    "MARKET_SCANNER_NEGRISK_THIN_BOOK",
    "SPREAD_TOO_WIDE"
  ],
  "scanned_at": "2026-05-09T11:30:00Z",
  "type": "CANDIDATE"
}

Reproduce locally

curl 'https://gamma-api.polymarket.com/markets?active=true&closed=false&limit=100'

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "scanner_id": "intel.market_scanner",
  "market_id": "CLOB:0xabc123",
  "condition_id": "0xabc123",
  "tradability_score": 0.78,
  "volume_24h_usd": 8500,
  "book_depth_usd": 3200,
  "spread_bps": 210,
  "neg_risk": false,
  "resolution_source": "UMA Optimistic Oracle",
  "warnings": [],
  "scanned_at": "2026-05-09T11:30:00Z",
  "type": "CANDIDATE"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Discovery / MarketScanner cycle health
• Grafana — Market quality / tradability score distribution

Log levels

16. Developer Reporting

{
  "scanner_id": "intel.market_scanner",
  "scan_cycle": 1428,
  "markets_scanned": 312,
  "markets_passed": 47,
  "markets_excluded": 265,
  "exclusion_breakdown": {
    "INSUFFICIENT_VISIBLE_DEPTH": 189,
    "SPREAD_TOO_WIDE": 76
  },
  "top_market": "CLOB:0xabc123",
  "top_tradability_score": 0.78,
  "killswitch_active": false,
  "scanned_at": "2026-05-09T11:30:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Stateless between scan cycles except for a short-lived in-memory market score cache.

State stores

Cold-start recovery

On cold start, the cache is empty. The first scan cycle populates it.

On restart

All scores are re-computed on the first scan cycle after restart. No durable state is loaded.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

0.2 0.5 0.6

External services

23. Security Surfaces

MarketScanner is strictly read-only. It never signs, submits, or modifies orders.

Signing surface

This bot does NOT sign anything.

Abuse vectors considered

• Gamma API returning malicious market metadata to inject a fraudulent condition_id into the candidate list

Mitigations

• condition_id format validated against known 32-byte hex pattern before inclusion
• All candidates are recommendations only — downstream guardrails independently re-validate every market

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

MarketScanner incidents are usually Gamma API or Data API outages. The bot is read-only so incidents do not affect active positions — only new opportunity discovery.

On-call actions

Manual overrides

• polytraders bot pause disc.market_scanner — Stops scan cycles; no new candidates are emitted. Active positions and guardrails are unaffected.
• polytraders bot set-param disc.market_scanner --scan-interval 60 — Temporarily increases scan interval to reduce API load during a degraded period.

Healthcheck

GET /health → 200 if last scan cycle completed within 2× scan_interval_s and at least one candidate was emitted.

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%