0.4 OpportunityQueue

1. Bot Identity

2. Purpose

Maintain a ranked queue of the best candidate markets per registered strategy type by combining MarketQualityRanker scores, EventCalendarMapper proximity signals, and per-strategy fit-scores into a single ordered list that strategies consume without re-running discovery.

3. Why This Bot Matters

• Strategies independently re-rank markets

  Each strategy duplicates discovery logic, wasting compute and producing inconsistent rankings across the system.

• Existing positions not suppressed

  A strategy may generate a new intent on a market where the user already has an open position, causing unintended double-up exposure.

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

{ "queue_depth": 20 }

if (d < params.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "refresh_interval_s": 60 }

if (s < params.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

8. Default Configuration

{
  "bot_id": "disc.opportunity_queue",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "queue_depth": 20,
    "refresh_interval_s": 60,
    "strategy_filters": [],
    "suppress_existing_position": true
  }
}

9. Implementation Flow

1. On each refresh cycle, ingest latest MarketQualityRanker ObservationReports.
2. Check KillSwitch; if active, freeze queue and suppress emissions.
3. Optionally ingest EventCalendarMapper reports; apply hours_to_event proximity boost.
4. If suppress_existing_position=true, fetch open positions from exec.position_tracker and exclude those markets.
5. For each registered strategy type, compute per-strategy fit_score using strategy_filters (e.g. time-to-res, vol range, spread tolerance).
6. Final rank = quality_score * fit_score * proximity_boost.
7. Retain top queue_depth entries per strategy type; evict stale entries older than 2× refresh_interval_s.
8. Emit ObservationReport with ranked queue snapshot per strategy type.
9. Log cycle summary with queue depth, evictions, and top entry per strategy.

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 queueRefreshCycle():
  ks = FETCH internal.killswitch.status
  IF ks.active: EMIT STALE_QUEUE; RETURN

  quality_reports = FETCH disc.marketqualityranker.latest_reports()
  IF quality_reports IS NULL OR age(quality_reports) > 2 * params.refresh_interval_s:
    EMIT ObservationReport(kind='STALE_QUEUE'); RETURN

  calendar_boosts = FETCH disc.eventcalendarmapper.latest_reports() OR {}
  open_positions = FETCH exec.position_tracker.open() OR {}

  FOR strategy_type IN registered_strategies:
    candidates = []
    FOR report IN quality_reports:
      IF params.suppress_existing_position AND report.market_id IN open_positions:
        CONTINUE
      fit = computeFitScore(strategy_type, report)
      boost = calendarBoost(report.market_id, calendar_boosts)
      final_score = report.quality_score * fit * boost
      candidates.append({ market_id, quality_score, fit, boost, final_score })

    candidates.sort(key=final_score, desc=True)
    queue = candidates[:params.queue_depth]

    IF len(queue) < params.queue_depth.warning:
      LOG WARN 'QUEUE_TOO_SHALLOW'

    EMIT ObservationReport(strategy_type, queue, refreshed_at)

  LOG cycle summary

SDK calls used

• fetchClobPublic('/book?market=<condition_id>&depth=1')
• ws_market.current_spread('<condition_id>')

Complexity: O(M × S) where M=candidate markets, S=registered strategy types

11. Wire Examples

Input — what arrives on the wire

MarketQualityRanker ObservationReport consumed by queue — disc.marketqualityranker

{
  "market_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "quality_score": 0.71,
  "sub_scores": {
    "liquidity": 0.82,
    "rule_clarity": 0.65,
    "resolution_horizon": 0.6
  }
}

Output — what the bot emits

ObservationReport — ranked queue for mean-reversion strategy

{
  "report_id": "0xeeff33445566778899001122334455eeff33445566778899001122334455eeff",
  "bot_id": "disc.opportunity_queue",
  "strategy_type": "mean-reversion",
  "queue": [
    {
      "rank": 1,
      "market_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
      "quality_score": 0.71,
      "fit_score": 0.88,
      "proximity_boost": 1.0,
      "final_rank_score": 0.625
    }
  ],
  "queue_depth": 1,
  "refreshed_at_ms": 1746789000000
}

Reproduce locally

curl 'https://clob.polymarket.com/book?market=0x7f8a9b...&depth=1'

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "0xeeff33445566778899001122334455eeff33445566778899001122334455eeff",
  "bot_id": "disc.opportunity_queue",
  "strategy_type": "mean-reversion",
  "queue": [
    {
      "rank": 1,
      "market_id": "0x7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
      "quality_score": 0.71,
      "fit_score": 0.88,
      "proximity_boost": 1.0,
      "final_rank_score": 0.625
    }
  ],
  "queue_depth": 1,
  "refreshed_at_ms": 1746789000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Discovery / OpportunityQueue depth and evictions

Log levels

16. Developer Reporting

{
  "bot_id": "disc.opportunity_queue",
  "cycle": 88,
  "strategy_types_served": 3,
  "total_queue_entries": 45,
  "evictions": 3,
  "suppressed_existing": 2,
  "killswitch_active": false,
  "refreshed_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, queue is empty; first refresh cycle populates it.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Injection of crafted quality scores via compromised MarketQualityRanker to manipulate queue ranking

Mitigations

• Queue entries clamped to [0,1] score range regardless of upstream values
• All outputs are ObservationReports; execution layer independently validates before acting

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

OpportunityQueue incidents are typically upstream data staleness or KillSwitch activation. Bot is read-only; incidents delay strategy opportunity discovery but do not affect active positions.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/opportunityqueue → green if Queue depth > 0 for at least one strategy type; last refresh within 2× refresh_interval_s.; red if Queue depth = 0 for all strategy types or no refresh in 2× interval.

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%