/prediction-markets/canonical-events

Description

Get the full details for one or more canonical events. A canonical event groups the same real-world event across prediction market platforms (Kalshi, Polymarket) under a single canonical_id, and each underlying outcome is mapped to a shared canonical_market_id. The response includes the event title, description, category, and — per platform — a confidence score for the match and the platform's native source_event_id / source_market_id values for order routing.

Best Practice: Match on Canonical IDs

Pair markets on canonical_market_id, not on title.

Kalshi and Polymarket describe the same outcome with different titles, IDs, and market breakdowns. The canonical_market_id is the reliable join key: the same value under two platforms means the two source markets settle on the same thing.

What to do instead

Build a lookup keyed on canonical_market_id, then act only on outcomes that appear on both platforms. Use each platform's native source_market_id when routing orders, and gate on confidence (for example, only act on matches >= 0.95) for real-money strategies.

Why this matters

An event may be matched on zero, one, or multiple platforms. Relying on titles — or assuming every event exists on both platforms — leads to mispaired markets and unintended exposure.

Specific Parameter Information

For a full list of parameters, scroll to the bottom of this page.

You must pass at least one canonical_id. Authenticate with the X-Api-Key header.

canonical_id

(Required.) A canonical event ID, obtained from /prediction-markets/canonical-events/ids.

Note: multiple IDs must be passed as repeated query parameters (e.g. canonical_id=X&canonical_id=Y), not comma-delimited values.

Example Responses

Canonical Event

URL: https://api.opticodds.com/api/v3/prediction-markets/canonical-events?canonical_id=548068796ec55f2fb280b49a526d9dbe

{
  "data": [
    {
      "canonical_id": "548068796ec55f2fb280b49a526d9dbe",
      "title": "FL-20 Democratic Primary Winner",
      "description": "This market will resolve according to the candidate who wins the nomination for the Democratic Party to contest the FL-20 congressional district seat in the U.S. House of Representatives in the 2026 midterm elections. The Democratic primary will take place on August 18, 2026.\n\nIf no nominee is announced by November 3, 2026, 11:59 PM ET, this market will resolve to \"Other\".",
      "category": "politics",
      "events": [
        {
          "platform": "kalshi",
          "source_event_id": "KXFLPRIMARY-20D26",
          "confidence": 0.95,
          "markets": [
            { "canonical_market_id": "7106f753fbc75c2a89e6c716e5341359", "source_market_id": "KXFLPRIMARY-20D26-DHOL" },
            { "canonical_market_id": "3b5bf665f0f35a05b1d14552edab5e78", "source_market_id": "KXFLPRIMARY-20D26-DSCH" },
            { "canonical_market_id": "fbd757ffbc565d6693f70b76c43c4cc8", "source_market_id": "KXFLPRIMARY-20D26-EMAN" },
            { "canonical_market_id": "d319db493de3572d948feb9f2fd01643", "source_market_id": "KXFLPRIMARY-20D26-LCAM" },
            { "canonical_market_id": "7ddee06b78055330b8adba24cba69997", "source_market_id": "KXFLPRIMARY-20D26-MDOU" },
            { "canonical_market_id": "dd7dfdf9b5975f6ba25a23b8e1fee213", "source_market_id": "KXFLPRIMARY-20D26-RMOI" },
            { "canonical_market_id": "ed93c3ed5cf2548ea3652845390c3a83", "source_market_id": "KXFLPRIMARY-20D26-SMCC" }
          ]
        },
        {
          "platform": "polymarket",
          "source_event_id": "403518",
          "confidence": 1.0,
          "markets": [
            { "canonical_market_id": "ed93c3ed5cf2548ea3652845390c3a83", "source_market_id": "2044829" },
            { "canonical_market_id": "d319db493de3572d948feb9f2fd01643", "source_market_id": "2044830" },
            { "canonical_market_id": "7ddee06b78055330b8adba24cba69997", "source_market_id": "2044831" },
            { "canonical_market_id": "7106f753fbc75c2a89e6c716e5341359", "source_market_id": "2044832" },
            { "canonical_market_id": "fbd757ffbc565d6693f70b76c43c4cc8", "source_market_id": "2044833" },
            { "canonical_market_id": "dd7dfdf9b5975f6ba25a23b8e1fee213", "source_market_id": "2044835" },
            { "canonical_market_id": "3b5bf665f0f35a05b1d14552edab5e78", "source_market_id": "2044836" }
          ]
        }
      ]
    }
  ]
}