0.3 EventCalendarMapper

1. Bot Identity

2. Purpose

Map every Polymarket market to a known real-world calendar event (elections, sports fixtures, court dates, FOMC releases, earnings, debates) and emit a time-tagged ObservationReport so strategies can act on pre-event positioning logic.

3. Why This Bot Matters

• Markets not linked to calendar events

  Strategies cannot distinguish between a stagnant market and one where a price-moving event is imminent, missing pre-event edge opportunities.

• Stale calendar data

  Rescheduled or cancelled events leave strategies positioned on a timeline that no longer exists.

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

{ "event_lookahead_h": 72 }

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

{ "min_event_relevance": 0.6 }

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

8. Default Configuration

{
  "bot_id": "disc.event_calendar_mapper",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "event_lookahead_h": 72,
    "enabled_calendars": [
      "elections",
      "sports",
      "macro",
      "earnings"
    ],
    "timezone_default": "UTC",
    "min_event_relevance": 0.6
  }
}

9. Implementation Flow

1. On each mapping cycle, fetch all active markets from Gamma API.
2. For each market, extract resolution date and normalise to UTC.
3. Filter to markets with resolution date within event_lookahead_h.
4. For each candidate, run NLP title-match against each enabled calendar feed to find the best-matching event.
5. Accept mappings where match_score >= min_event_relevance; reject below hard floor with CALENDAR_MISMATCH.
6. Emit ObservationReport with market_id, event_id, calendar_source, match_score, event_time_utc, hours_to_event.
7. Log cycle summary with total markets mapped, unmatched count, and top mapping by relevance.

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

  markets = FETCH gamma.GET('/markets?active=true&closed=false')
  IF markets IS NULL:
    LOG ERROR 'Gamma API unavailable — halting mapping cycle'
    RETURN

  now_utc = current_time_utc()
  horizon_cutoff = now_utc + params.event_lookahead_h * 3600

  FOR market IN markets:
    res_time = parse_utc(market.resolution_date)
    IF res_time > horizon_cutoff: CONTINUE  // outside lookahead

    best_match = NULL; best_score = 0.0
    FOR calendar IN params.enabled_calendars:
      events = calendarFeed(calendar, res_time)
      FOR event IN events:
        score = nlpMatch(market.question, event.description)
        IF score > best_score:
          best_match = event; best_score = score

    IF best_score < params.min_event_relevance.hard:
      LOG reason=CALENDAR_MISMATCH; CONTINUE

    warnings = []
    IF best_score < params.min_event_relevance.default:
      warnings.append('LOW_RELEVANCE')

    hours_to_event = (parse_utc(best_match.time) - now_utc) / 3600
    EMIT ObservationReport(market_id, best_match.id, best_match.calendar,
                           best_score, hours_to_event, warnings)

  LOG cycle summary

SDK calls used

• gamma.GET('/markets?active=true&closed=false')
• calendarFeed('elections', resolution_date)
• nlpMatch(market.question, event.description)

Complexity: O(M × C × E) where M=markets, C=calendars, E=events per calendar window

11. Wire Examples

Input — what arrives on the wire

Gamma market with election resolution date — gamma_api

{
  "condition_id": "0x8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b",
  "question": "Will Candidate A win the 2026 midterm election?",
  "active": true,
  "resolution_date": "2026-11-04T00:00:00Z",
  "neg_risk": false
}

Output — what the bot emits

ObservationReport — election market mapped

{
  "report_id": "0xccdd2233445566778899001122334455ccdd2233445566778899001122334455",
  "bot_id": "disc.event_calendar_mapper",
  "market_id": "0x8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b",
  "event_id": "us-election-2026-nov-03",
  "calendar_source": "elections",
  "match_score": 0.87,
  "event_time_utc": "2026-11-03T23:00:00Z",
  "hours_to_event": 48.5,
  "warnings": [],
  "mapped_at_ms": 1746789000000
}

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 ObservationReport object. See ObservationReport schema.

{
  "report_id": "0xccdd2233445566778899001122334455ccdd2233445566778899001122334455",
  "bot_id": "disc.event_calendar_mapper",
  "market_id": "0x8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b",
  "event_id": "us-election-2026-nov-03",
  "calendar_source": "elections",
  "match_score": 0.87,
  "event_time_utc": "2026-11-03T23:00:00Z",
  "hours_to_event": 48.5,
  "warnings": [],
  "mapped_at_ms": 1746789000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Discovery / EventCalendarMapper mapping coverage

Log levels

16. Developer Reporting

{
  "bot_id": "disc.event_calendar_mapper",
  "cycle": 11,
  "markets_evaluated": 312,
  "markets_mapped": 24,
  "markets_unmatched": 288,
  "top_mapping": "0x8a9b... \u2192 us-election-2026-nov-03 (score 0.87)",
  "killswitch_active": false,
  "mapped_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, calendar feeds are re-fetched on first cycle.

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

• External calendar feed returning crafted event data to create false market mappings

Mitigations

• NLP match score threshold prevents low-confidence mappings from propagating
• All outputs are ObservationReports (read-only recommendations); 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

EventCalendarMapper incidents are typically calendar feed outages or NLP threshold misconfiguration. Bot is read-only; incidents do not affect active positions.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/eventcalendarmapper → green if Last cycle completed within 2× mapping interval; at least one event mapped in last 24h.; red if No cycle completed in 2× interval or zero mappings in 24h during active markets.

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%