PredictorSDK Docs

Make your first call

Start here — this call takes no identifiers, so there is nothing to look up first. It returns a page of currently matched sports events, soonest scheduled start first. A game stays in the list through the day after its scheduled date (Eastern), so the first events can be games that have already been played; see Include settled events.

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.predictorsdk.com/v1/matching-markets/sports?limit=2"

data lists the events, each under its canonical event_id, with the day it is scheduled (scheduled_date, in America/New_York) and, when a venue published one, its start time (scheduled_start, in UTC; null otherwise). By default a page lists events whose full-game moneyline is matched, and each carries that moneyline and every venue market matched to it, in one shape (abridged here; the API reference shows every field):

{
  "data": [
    {
      "event_id": "nba-okc-sas-2026-10-20",
      "sport": "basketball",
      "league": "nba",
      "title": "Oklahoma City Thunder vs. San Antonio Spurs",
      "scheduled_start": "2026-10-20T23:30:00.000Z",
      "scheduled_date": "2026-10-20",
      "participants": [
        { "key": "okc", "name": "Oklahoma City Thunder", "role": "away" },
        { "key": "sas", "name": "San Antonio Spurs", "role": "home" }
      ],
      "submarkets": [
        {
          "key": "moneyline|full|winner",
          "market_type": "moneyline",
          "segment": "full",
          "display_name": "Winner",
          "outcomes": [
            { "key": "winner:okc", "label": "Oklahoma City Thunder win", "side": "win" },
            { "key": "winner:sas", "label": "San Antonio Spurs win", "side": "win" }
          ],
          "source_markets": [
            {
              "provider": "kalshi",
              "event_id": "KXNBAGAME-26OCT20OKCSAS",
              "market_id": "KXNBAGAME-26OCT20OKCSAS-OKC",
              "market_name": "Oklahoma City wins",
              "outcomes": [
                { "canonical_outcome_key": "winner:okc", "label": "Yes", "outcome_id": "yes", "side": "yes" },
                { "canonical_outcome_key": "winner:sas", "label": "No", "outcome_id": "no", "side": "no" }
              ]
            },
            {
              "provider": "kalshi",
              "event_id": "KXNBAGAME-26OCT20OKCSAS",
              "market_id": "KXNBAGAME-26OCT20OKCSAS-SAS",
              "market_name": "San Antonio wins",
              "outcomes": [
                { "canonical_outcome_key": "winner:sas", "label": "Yes", "outcome_id": "yes", "side": "yes" },
                { "canonical_outcome_key": "winner:okc", "label": "No", "outcome_id": "no", "side": "no" }
              ]
            },
            {
              "provider": "sxbet",
              "event_id": "L19766755",
              "market_id": "0xb4d047a709aae881e5ccad9d123592967644ee1df1f17078c762b388e41b81c5",
              "market_name": "San Antonio Spurs vs Oklahoma City Thunder",
              "outcomes": [
                { "canonical_outcome_key": "winner:sas", "label": "San Antonio Spurs", "outcome_id": "outcomeOne" },
                { "canonical_outcome_key": "winner:okc", "label": "Oklahoma City Thunder", "outcome_id": "outcomeTwo" }
              ]
            }
          ]
        }
      ]
    }
  ],
  "pagination": { "limit": 2, "total": 140, "has_more": true, "next_cursor": "eyJ..." },
  "snapshot": { "observed_at": "2026-10-03T23:11:41.515Z" }
}

Every venue market carries the same references, whichever venue it is:

provider names the venue.
event_id is the venue's parent event, for GET /v1/events/{event_id}.
market_id is the market itself, for GET /v1/markets/{market_id}.
Each outcome_id is the venue's handle for one side, mapped to a canonical outcome such as winner:okc. Market detail returns the same IDs, so read sides by ID. The labels match too, except on AlphaArcade, where market detail names a game line's two sides Yes and No.

Kalshi lists a game winner as one binary market per team, so it appears once per team, each with its own Yes / No outcomes. Send provider along with either ID, as the composite kalshi:KXNBAGAME-26OCT20OKCSAS-OKC or as ?provider=, because some venues' IDs are not unique across venues.

Identifiers in these examples are samples, not fixtures

Game tickers, event slugs, and canonical event keys are delisted once an event settles, so the specific values shown throughout these docs will stop resolving. Take live ones from the call above — that is the whole reason this page starts with a call that needs no identifier.

Look up one of those events

Instead of walking list pages to find an event again, look it up with GET /v1/matching-markets/sports/lookup: pass a canonical key as event_id, or a venue market's market_id, market_slug or event_id as source_id={provider}:{id}. Here, a Kalshi event ticker and an ID no venue lists:

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.predictorsdk.com/v1/matching-markets/sports/lookup?source_id=kalshi:KXNBAGAME-26OCT20OKCSAS&source_id=kalshi:KXNBA-27-SAS"

A lookup returns each event it found once in data, in full, with no pagination block. lookups reports every identifier you sent, as you sent it, with the events it found, so one that found nothing is listed with none:

{
  "data": [
    {
      "event_id": "nba-okc-sas-2026-10-20",
      "title": "Oklahoma City Thunder vs. San Antonio Spurs",
      "submarkets": [ … ]
    }
  ],
  "lookups": {
    "kalshi:KXNBAGAME-26OCT20OKCSAS": { "event_ids": ["nba-okc-sas-2026-10-20"] },
    "kalshi:KXNBA-27-SAS": { "event_ids": [] }
  },
  "snapshot": { "observed_at": "2026-10-03T23:11:41.515Z" }
}

KXNBA-27-SAS is a real market, a season future, but no other venue lists it, so it matches no game.

You can mix several venues and canonical keys in one request, up to 100 identifiers. Coverage is NBA, WNBA, NHL, MLB, and NFL. The league is the first segment of the canonical event ID, and the list takes it as a filter along with a date and a participant: ?league=nfl&scheduled_date=2026-10-25. See Filtering.

See every submarket

A list page carries only each game's moneyline, so it stays small. Pass include_submarkets=true to see every matched submarket (spreads, totals, period lines and player props), each with the same fields as the moneyline above. This returns the first game in the list, with all of its submarkets:

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.predictorsdk.com/v1/matching-markets/sports?include_submarkets=true&limit=1"

A lookup returns every submarket by default: a source_id for a spread finds its game, spread included. Send include_submarkets=false to get only the moneyline.

The response carries identity and exact native references only; prices and executable depth stay on market and venue surfaces. Join each source_markets[].market_id to GET /v1/markets/{market_id} for quotes, and each outcomes[].outcome_id to that response's outcomes[].outcome_id to line up the selections. Every provider joins on both. Polymarket, Predict and AlphaArcade publish a per-outcome token that is unique on that venue, which source_id also accepts (AlphaArcade's game lines reuse the token of the Polymarket market they mirror, so key a cross-venue map by provider and token); SX Bet, Kalshi, ProphetX and Pred have none, so their references are market-scoped and read together with market_id: outcomeOne / outcomeTwo on SX Bet, yes / no on Kalshi and Pred, and small integers on ProphetX.

Next steps

Authentication -- add your API key
Filtering -- filter the list by league, date or participant, and look up canonical event IDs or provider identifiers
Plans & Limits -- read the public plan catalog with GET /v1/plans
Pagination -- walk large result sets with cursors
API Reference -- explore all endpoints

Quickstart

Make your first call

Look up one of those events

See every submarket

Next steps

On this page