# Matching Markets (https://docs.predictorsdk.com/concepts/matching-markets)

How PredictorSDK finds the same game and the same bet on different venues, and the IDs it gives them.

The same game is listed on many venues, each in its own format. Kalshi calls
Thunder at Spurs `KXNBAGAME-26OCT20OKCSAS`, SX Bet calls it fixture
`L19766755`, and Polymarket gives it its own slug and IDs. PredictorSDK matches
these listings into one **event**, and the bets inside it into
**submarkets**, so you can put the same bet side by side across venues.

## What gets matched [#what-gets-matched]

1. **The game.** Listings are grouped by league, teams and date into one event,
   such as `nba-okc-sas-2026-10-20`.
2. **The bet.** Within a game, markets are grouped by kind (winner, spread,
   total, team total, player prop), period (full game, a half, a quarter) and
   line.
3. **The sides.** Each venue's sides (yes and no, team names, over and under)
   map to shared outcomes, such as `winner:sas`.

An event or submarket appears only when at least two venues list it. Venues
sometimes settle the same bet differently, for example a tied NFL game or
overtime in a second half. The response says so: see
[Game-line rules](https://docs.predictorsdk.com/guides/game-line-rules) and
[Player-prop matching](https://docs.predictorsdk.com/guides/player-prop-matching).

## IDs that don't change [#ids-that-dont-change]

Every matched game, bet and side has a canonical ID, the same on every call:

| ID | Example | What it names |
|---|---|---|
| Event ID | `nba-okc-sas-2026-10-20` | The game: league, away team, home team and date (US Eastern) |
| Submarket key | `moneyline\|full\|winner`, `spread\|full\|spread:okc\|8.5` | One bet within the game |
| Outcome key | `winner:sas`, `cover:okc`, `over` | One side of that bet |

## What a matched game looks like [#what-a-matched-game-looks-like]

Each event in `data` lists its submarkets, and each submarket lists the venue
markets matched to it in `source_markets[]`. A venue market has the same fields
whichever venue it comes from: `provider`, the venue's own `event_id` and
`market_id`, `market_name`, and `outcomes`, which map each of the venue's
sides to a canonical outcome. [Events and markets](https://docs.predictorsdk.com/concepts/events-and-markets)
walks through a full example and says which ID goes to which endpoint.

A venue's `event_id` goes to `GET /v1/events/{event_id}`, with one catch: SX
Bet lists a fixture's markets only while the fixture is trading, so once a game
has been played its SX Bet `event_id` answers `404` there. Its `market_id`
still works on market detail.

A page of the list covers games whose full-game winner is matched, and each
game carries only that submarket, so pages stay small. Add
`include_submarkets=true` for every matched submarket, which also brings in
games matched only on spreads, totals or props.

The list is sorted by scheduled start, soonest first. A game stays in it
through the day after its date (US Eastern), so the first games may already be
over; [Filtering](https://docs.predictorsdk.com/guides/filtering#include-settled-events) shows how to reach
older ones.

## Finding games [#finding-games]

- **Browse** with `GET /v1/matching-markets/sports`, narrowed by `league`,
  `scheduled_date` or `participant`. See [Filtering](https://docs.predictorsdk.com/guides/filtering).
- **Look up** with `GET /v1/matching-markets/sports/lookup`. It takes canonical
  keys as `event_id`, and any ID a venue market publishes as
  `source_id={provider}:{id}`, such as `kalshi:KXNBAGAME-26OCT20OKCSAS`. On
  Polymarket, Predict, AlphaArcade and Hyperliquid an outcome token works too,
  and on Polymarket a condition ID. Send up to 100 IDs in one request; matching
  ignores case. Each game found comes back once, with every submarket, and
  `lookups` reports what each ID found.

## Identity, not prices [#identity-not-prices]

Matching answers one question: which markets are the same bet. It returns no
prices, volumes or statuses. To price a market, send its `market_id` to
[`GET /v1/markets/{market_id}`](https://docs.predictorsdk.com/api-reference/getMarket), which reads the
venue when you ask.

**Upgrading from an older SDK?**   SDK 0.23 moved lookups to their own route, renamed the `platform` parameter
  to `provider`, and made paginated calls return pages you can iterate. SDKs
  0.21 and 0.19 reshaped the response. Retired parameters answer `400` naming
  their replacement, and the [breaking changes](https://docs.predictorsdk.com/changelog?tag=breaking) in the
  changelog map each old field to its new home.