4.5 SportsFeed-Adapter

1. Bot Identity

2. Purpose

SportsFeed-Adapter ingests structured sports data from league APIs (NBA, NFL, EPL, ATP/WTA, MLB) and odds-feed providers, normalises it into a canonical SportsFeedEvent schema, and emits an ObservationReport for each qualifying update (lineup changes, injury reports, score updates, and pre-game odds shifts). It supplements primary API feeds with ws_sports for low-latency in-play state and falls back to web extraction for sports without direct API coverage. Output feeds sports-model strategies with the event data they need to price Polymarket sports markets. SportsFeed-Adapter is strictly read-only — it never submits or signs orders.

3. Why This Bot Matters

• Injury report not ingested before market open

  Sports-model strategy prices a market without a key player absence; takes a position at a probability that is stale by a significant amount and gets adversely selected.

• Score update delayed by > refresh_interval_s

  In-play market probability estimate diverges from ground truth; strategy holds a stale position through a goal or score change, realising avoidable losses.

• Primary league API unavailable and fallback_to_web disabled

  No sports data flows to the model; strategy falls back to last-known odds and risks trading on stale information for the duration of the outage.

• Odds from wrong provider used due to preferred_provider misconfiguration

  Systematically biased odds feed primes the model with incorrect pre-game probability estimates, degrading pricing accuracy across all sports markets in the affected sport.

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

{ "refresh_interval_s": 30 }

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

{ "stale_feed_threshold_s": 120 }

if (feed_age_s > p.hard) emit_stale_and_halt(sport);

{ "min_odds_shift_bps": 50 }

if (abs(odds_shift_bps) < p.hard) return; // noise floor

8. Default Configuration

{
  "bot_id": "intel.sportsfeed-adapter",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "enabled_sports": [
      "NBA",
      "NFL",
      "EPL",
      "ATP",
      "WTA",
      "MLB"
    ],
    "preferred_provider": "primary_league_api",
    "refresh_interval_s": 30,
    "stale_feed_threshold_s": 120,
    "min_odds_shift_bps": 50,
    "fallback_to_web": true
  },
  "locked": {
    "refresh_interval_s": {
      "min": 5
    },
    "stale_feed_threshold_s": {
      "max": 300
    },
    "min_odds_shift_bps": {
      "min": 5
    }
  }
}

9. Implementation Flow

1. On startup, subscribe to ws_sports for real-time in-play state updates for all enabled_sports.
2. On each refresh cycle (refresh_interval_s), poll preferred_provider league API for each tracked event: lineups, injuries, odds, score, game_clock.
3. If preferred_provider unavailable and fallback_to_web=true, attempt web extraction for affected sport/event.
4. Normalise raw feed payload into canonical SportsFeedEvent schema: {event_id, sport, home_team, away_team, condition_id, event_type, payload, source_provider, feed_age_s}.
5. Check feed_age_s: if > stale_feed_threshold_s hard (300 s), emit STALE_DATA WARN and halt ObservationReports for that sport.
6. For odds-update events, compute odds_shift_bps vs last emitted odds. If abs(odds_shift_bps) < min_odds_shift_bps hard (5 bps), discard as noise.
7. Check KillSwitch. If active, continue ingesting and normalising but suppress ObservationReport emissions.
8. For qualifying events, emit ObservationReport with: report_id, trace_id, condition_id, event_type, sport, event_id, normalised_payload, source_provider, feed_age_s, odds_shift_bps (if applicable), warnings.
9. Apply sampling: emit-every for LINEUP_CHANGE, INJURY_UPDATE, GAME_START, GAME_END; sample-1/5 for routine score-tick updates.
10. Log per-cycle summary: events_polled, events_emitted, events_discarded_noise, stale_sports, fallback_used.

10. Reference Implementation

Polls league APIs and ws_sports for sports events, normalises to canonical SportsFeedEvent schema, applies staleness and noise-floor filters, applies sampling for routine score ticks, and emits ObservationReports to the sports-model strategy layer.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output.

// --- Initialisation ---
ws_sports.subscribe(handler=onInPlayEvent)
last_odds   = {}   // event_id -> odds_value
last_feed_ts = {}  // sport -> timestamp_ms
score_tick_counter = {}  // event_id -> int

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

  FOR sport IN params.enabled_sports:
    // --- 1. Poll primary provider ---
    feed = FETCH league_api[sport].getEvents(active=true)

    IF feed IS NULL AND params.fallback_to_web:
      feed = FETCH web_extractor[sport].getEvents()
      provider = 'web_fallback'
    ELSE:
      provider = params.preferred_provider

    IF feed IS NULL:
      feed_age_s = (now_ms() - last_feed_ts.get(sport, 0)) / 1000
      IF feed_age_s > params.stale_feed_threshold_s.hard:
        LOG WARN 'STALE_DATA — ' + sport + ' feed hard stale'
        stale_sports.add(sport)
      CONTINUE

    last_feed_ts[sport] = now_ms()
    stale_sports.discard(sport)

    FOR event IN feed.events:
      condition_id = gamma_api.GET('/sports-event/' + event.event_id + '/condition')
      IF condition_id IS NULL:
        CONTINUE

      // --- 2. Classify event type ---
      FOR update IN event.updates:
        event_type = classifyUpdate(update)  // INJURY_UPDATE | LINEUP_CHANGE | ODDS_UPDATE | SCORE_TICK | GAME_START | GAME_END

        // --- 3. Noise filter for odds updates ---
        IF event_type == 'ODDS_UPDATE':
          shift_bps = abs(update.new_odds - last_odds.get(event.event_id, update.new_odds)) * 10000
          IF shift_bps < params.min_odds_shift_bps.hard:
            events_discarded_noise_counter += 1
            CONTINUE
          last_odds[event.event_id] = update.new_odds

        // --- 4. Staleness check ---
        feed_age_s = (now_ms() - update.provider_ts_ms) / 1000
        warnings = []
        IF feed_age_s > params.stale_feed_threshold_s.default:
          warnings.append('STALE_DATA')
          IF feed_age_s > params.stale_feed_threshold_s.hard:
            CONTINUE  // halt emission

        // --- 5. Sampling for routine ticks ---
        sampling_applied = False
        IF event_type == 'SCORE_TICK':
          score_tick_counter[event.event_id] = score_tick_counter.get(event.event_id, 0) + 1
          IF score_tick_counter[event.event_id] % 5 != 0:
            CONTINUE  // sample-1/5
          sampling_applied = True

        // --- 6. KillSwitch suppress ---
        IF ks.active:
          LOG INFO 'KILL_SWITCH_ACTIVE — suppressing ObservationReport'
          CONTINUE

        // --- 7. Emit ---
        EMIT ObservationReport {
          report_id:         'rep_sfa_' + sport + '_' + condition_id[:6] + '_' + now_ms(),
          trace_id:          new_trace_id(),
          bot_id:            'intel.sportsfeed-adapter',
          kind:              'ObservationReport',
          condition_id:      condition_id,
          event_type:        event_type,
          sport:             sport,
          event_id:          event.event_id,
          normalised_payload: normalise(update),
          source_provider:   provider,
          feed_age_s:        feed_age_s,
          odds_shift_bps:    shift_bps IF event_type == 'ODDS_UPDATE' ELSE None,
          sampling_applied:  sampling_applied,
          warnings:          warnings,
          emitted_at_ms:     now_ms()
        }

FUNCTION onInPlayEvent(ws_event):
  // ws_sports supplement — same normalise + emit pipeline, source_provider='ws_sports'
  condition_id = gamma_api.GET('/sports-event/' + ws_event.event_id + '/condition')
  IF condition_id IS NULL: RETURN
  // ... same emit logic with event_type from ws_sports message type

SDK calls used

• league_api[sport].getEvents(active=true)
• ws_sports.subscribe(handler=onInPlayEvent)
• gamma_api.GET('/sports-event/<event_id>/condition')
• web_extractor[sport].getEvents()

Complexity: O(S × E) per refresh cycle where S = enabled sports count, E = average events per sport

11. Wire Examples

Input — what arrives on the wire

{
  "label": "League API injury update payload",
  "source": "primary_league_api",
  "payload": {
    "sport": "NBA",
    "event_id": "NBA_2026_PO_G3_TOR_MIA",
    "updates": [
      {
        "type": "injury",
        "player": "Player A",
        "team": "TOR",
        "status": "OUT",
        "reason": "ankle sprain",
        "provider_ts_ms": 1746704000000
      }
    ]
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — INJURY_UPDATE for NBA market",
  "payload": {
    "report_id": "rep_sfa_NBA_0xcc99_1746704000000",
    "trace_id": "trc_0xdead0102030405060708",
    "bot_id": "intel.sportsfeed-adapter",
    "kind": "ObservationReport",
    "condition_id": "0xcc990000000000000000000000000000000000000000000000000000000000000000",
    "event_type": "INJURY_UPDATE",
    "sport": "NBA",
    "event_id": "NBA_2026_PO_G3_TOR_MIA",
    "normalised_payload": {
      "player": "Player A",
      "team": "TOR",
      "status": "OUT",
      "reason": "ankle sprain",
      "updated_at_ms": 1746704000000
    },
    "source_provider": "primary_league_api",
    "feed_age_s": 8,
    "odds_shift_bps": null,
    "sampling_applied": false,
    "warnings": [],
    "emitted_at_ms": 1746704000095
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "rep_sfa_NBA_0xcc99_1746704000000",
  "trace_id": "trc_0xdead0102030405060708",
  "bot_id": "intel.sportsfeed-adapter",
  "kind": "ObservationReport",
  "condition_id": "0xcc990000000000000000000000000000000000000000000000000000000000000000",
  "event_type": "INJURY_UPDATE",
  "sport": "NBA",
  "event_id": "NBA_2026_PO_G3_TOR_MIA",
  "normalised_payload": {
    "player": "Player A",
    "team": "TOR",
    "status": "OUT",
    "reason": "ankle sprain",
    "updated_at_ms": 1746704000000
  },
  "source_provider": "primary_league_api",
  "feed_age_s": 8,
  "odds_shift_bps": null,
  "sampling_applied": false,
  "warnings": [],
  "emitted_at_ms": 1746704000095
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / SportsFeed-Adapter feed age per sport
• Grafana — Intelligence / event type distribution and emissions rate

16. Developer Reporting

{
  "bot_id": "intel.sportsfeed-adapter",
  "refresh_cycle": 2847,
  "events_polled": 42,
  "events_emitted": 6,
  "events_discarded_noise": 11,
  "stale_sports": [],
  "fallback_used": false,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, Redis state reloaded. First refresh cycle repopulates any missing keys. score_tick_counter resets to 0 for all events.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Compromised league API provider injecting false injury or lineup data to manipulate sports-model strategy pricing
• Web fallback scraping page with adversarially crafted content to produce incorrect normalised_payload values

Mitigations

• Only preferred league API sources are used by default; web fallback requires explicit fallback_to_web=true config
• normalised_payload schema is strictly validated; unexpected fields are stripped before emission
• All ObservationReports are informational only — downstream strategies and risk bots independently validate market state 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

SportsFeed-Adapter incidents are usually league API outages or hard-stale feeds. Since sports markets can move rapidly around game events, stale feeds during live games should be paged immediately. The fallback_to_web mechanism provides a safety net during primary API outages.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/sportsfeed-adapter -> 200 if All enabled_sports have feed_age_s < stale_feed_threshold_s AND ws_sports connected AND observations_emitted_total rate > 0 in last 5 min. RED if Any sport in stale_sports (hard stale) OR ws_sports disconnected > 60 s AND primary API also down OR observations_emitted_total rate == 0 for > 15 min.

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%