0.2 MarketQualityRanker

1. Bot Identity

2. Purpose

Score every market across volume, spread, depth, dispute history, rule clarity, implied volatility, and time-to-resolution into a single quality rank. Sits before every strategy and replaces ad-hoc per-strategy quality checks with a shared, consistent score.

3. Why This Bot Matters

• No shared quality score

  Each strategy re-derives its own quality filter, producing inconsistent rankings and wasted per-strategy compute.

• High-dispute markets not penalised

  Markets with frequent UMA disputes carry elevated resolution risk; without a dispute-penalty weight they appear equivalent to clean markets.

• Short-horizon markets ignored

  Markets resolving in <24h may have inflated spreads or thin books that are artefacts of the final trading window, not genuine signals.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "min_quality_score": 0.4 }

if (score < params.hard) emit(HARD_REJECT, 'LOW_QUALITY_SCORE');

{ "weight_liquidity": 0.4 }

if (w < 0) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "weight_rule_clarity": 0.35 }

if (w < 0) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

8. Default Configuration

{
  "bot_id": "disc.market_quality_ranker",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "min_quality_score": 0.4,
    "weight_liquidity": 0.4,
    "weight_rule_clarity": 0.35,
    "weight_resolution_horizon": 0.25
  }
}

9. Implementation Flow

1. On each scoring cycle, receive the current MarketScanner candidate list.
2. Check KillSwitch; if active, halt emissions.
3. For each candidate, fetch rule text from Gamma API and compute rule_clarity_score via heuristics (ambiguity keywords, missing resolution date, etc.).
4. Fetch 30-day dispute history from Data API; compute dispute_penalty = disputes_30d / 10, capped at 0.3.
5. Compute liquidity_score = normalise(volume_24h, book_depth_usd) against rolling 30-day distribution.
6. Compute resolution_horizon_score = 1 / (1 + exp(-time_to_res_days)); short horizons score lower.
7. Composite score = weight_liquidity * liquidity_score + weight_rule_clarity * (rule_clarity_score - dispute_penalty) + weight_resolution_horizon * resolution_horizon_score.
8. Emit ObservationReport for each market with composite score, sub-scores, and any WARN/HARD_REJECT codes.
9. Log cycle summary with top-ranked and bottom-ranked markets.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION scoringCycle():
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN  // halt emissions

  candidates = FETCH disc.marketscanner.latest_candidates()
  IF candidates IS NULL:
    LOG ERROR 'MarketScanner candidates unavailable'
    RETURN

  FOR market IN candidates:
    rules_text = FETCH gamma.GET('/market/' + market.condition_id + '/rules')
    IF rules_text IS NULL: CONTINUE  // skip; STALE_MARKET_DATA

    rule_clarity = scoreRuleClarity(rules_text)
    disputes = FETCH data_api.GET('/disputes?market=' + market.condition_id + '&window=30d')
    dispute_penalty = MIN(0.3, (disputes.count OR 0) / 10)

    liq_score = normalise(market.volume_24h_usd, market.book_depth_usd)
    horizon_score = horizonScore(market.resolution_date)

    score = (params.weight_liquidity * liq_score
           + params.weight_rule_clarity * (rule_clarity - dispute_penalty)
           + params.weight_resolution_horizon * horizon_score)
    score = CLAMP(score, 0.0, 1.0)

    IF score < params.min_quality_score.hard:
      LOG reason=LOW_QUALITY_SCORE; CONTINUE

    warnings = []
    IF score < params.min_quality_score.default:
      warnings.append('LOW_QUALITY_SCORE')

    EMIT ObservationReport(market_id, score, liq_score, rule_clarity, horizon_score,
                           dispute_penalty, warnings)

  LOG cycle summary

SDK calls used

• gamma.GET('/market/<condition_id>/rules')
• data_api.GET('/disputes?market=<condition_id>&window=30d')
• data_api.GET('/volume?market=<condition_id>&window=24h')

Complexity: O(M) where M = number of MarketScanner candidates per cycle

11. Wire Examples

Input — what arrives on the wire

MarketScanner candidate passed to ranker — disc.marketscanner

{
  "market_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "volume_24h_usd": 8540,
  "book_depth_usd": 3200,
  "spread_bps": 210,
  "neg_risk": false,
  "resolution_date": "2026-06-01T00:00:00Z"
}

Output — what the bot emits

ObservationReport — high-quality market

{
  "report_id": "0xaabb1122334455667788990011223344aabb1122334455667788990011223344",
  "bot_id": "disc.market_quality_ranker",
  "market_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "quality_score": 0.71,
  "sub_scores": {
    "liquidity": 0.82,
    "rule_clarity": 0.65,
    "resolution_horizon": 0.6
  },
  "dispute_penalty": 0.0,
  "warnings": [],
  "ranked_at_ms": 1746789000000
}

Reproduce locally

curl 'https://gamma-api.polymarket.com/market/0x7f8a9b.../rules'

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "0xaabb1122334455667788990011223344aabb1122334455667788990011223344",
  "bot_id": "disc.market_quality_ranker",
  "market_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "quality_score": 0.71,
  "sub_scores": {
    "liquidity": 0.82,
    "rule_clarity": 0.65,
    "resolution_horizon": 0.6
  },
  "dispute_penalty": 0.0,
  "warnings": [],
  "ranked_at_ms": 1746789000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Discovery / MarketQualityRanker score distribution

Log levels

16. Developer Reporting

{
  "bot_id": "disc.market_quality_ranker",
  "cycle": 42,
  "markets_scored": 47,
  "markets_forwarded": 38,
  "markets_dropped_low_quality": 9,
  "top_market": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "top_score": 0.71,
  "killswitch_active": false,
  "scored_at": "2026-05-09T11:30:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, normalisation uses the first cycle's values as a warm-up baseline.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

0.4

External services

23. Security Surfaces

Abuse vectors considered

• Gamma API returning crafted resolution text to manipulate rule_clarity scores
• Data API returning artificially low dispute counts to inflate quality scores

Mitigations

• Rule clarity scoring uses local heuristics, not API-provided scores
• All ObservationReports are recommendations only; downstream bots independently validate

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

MarketQualityRanker incidents are usually upstream data issues or threshold drift. Bot is read-only; incidents do not affect active positions.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/marketqualityranker → green if Last cycle completed within 2× scoring interval and at least one report emitted.; red if No cycle completed in 2× interval or zero reports for 10 minutes.

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%