Odds Channel - Realtime Betting Odds Stream

What it streams

Realtime odds updates for outcomes within markets, scoped to a specific fixtureId. Odds are grouped by bookmaker and keyed by a unique oddsId per outcome. Each entry represents a single oddsId (one price for one outcome).

Routing

Entity key: payload.fixtureId
Filters: sportIds, tournamentIds, fixtureIds, bookmakers
Access: determined by your apiKey
Bookmaker-gated: ✅ Yes

Delivery semantics

The odds channel delivers conflated state on a fixed ~10 ms batching window: if multiple updates for the same oddsId occur within one window, only the newest is sent.

No state is lost — the final value of every price move is always delivered
Bounded staleness — a delivered price is never more than one batching window behind our observation of the bookmaker
The window is a fixed performance parameter, not a load-shedding mechanism

What is not delivered: intermediate ticks superseded within the same window. Treat every message as a state update, not a ledger.

Need every price move or the closing line? For full tick-level movement use Historical Odds and for opening/closing prices use CLV.

Payload structure

oddsId:

<fixtureId>:<bookmaker>:<outcomeId>:<playerId>

outcome object (full schema)

Each odds entry is an outcome, with the following fields:

Field	Type	Description
`bookmaker`	`string`	Bookmaker slug (e.g. `"stake"`, `"pinnacle"`, `"polymarket"`)
`outcomeId`	`integer`	Outcome identifier
`playerId`	`integer`	Player ID (`0` for non-player markets)
`price`	`number`	Decimal odds
`active`	`boolean`	Whether this outcome is currently available
`marketActive`	`boolean \| null`	Whether the entire market is active
`mainLine`	`boolean \| null`	Whether this is the bookmaker’s main line
`marketId`	`integer`	Market identifier
`bookmakerMarketId`	`string \| null`	Native bookmaker market ID
`bookmakerOutcomeId`	`string \| null`	Native bookmaker outcome ID
`bookmakerChangedAt`	`number \| null`	Bookmaker-provided change timestamp (epoch ms)
`priceFractional`	`string	`	Fractional odds (e.g. `"5/2"`)
`priceAmerican`	`integer	`	American odds (e.g. `-110`, `+250`)
`limit`	`number \| null`	Maximum accepted stake at this price — carried for close to every sharp book
`betslip`	`string \| null`	Optional bookmaker betslip or deeplink token
`meta`	`object \| null`	Bookmaker-specific metadata (orderbooks, ladders, etc.)
`changedAt`	`number`	When OddsPapi observed this change at the bookmaker (epoch ms, UTC) — always present

Notes on timestamps

Each update carries the full delivery chain:

Stamp	Field	Meaning
t0	`bookmakerChangedAt`	The bookmaker’s own change timestamp (when provided)
t1	`changedAt`	When OddsPapi observed the change — always present
t2	`ts` (message envelope)	When the gateway sent the message
t3	—	Client receipt — measure it on your side

changedAt − bookmakerChangedAt is the observation delay for that update. Per-bookmaker freshness bounds are published on GET /bookmakers — see Latency and freshness.

Limits

limit is the maximum accepted stake at the current price — for a trading system, size-at-price matters as much as the price itself. OddsPapi normalizes limits across books and carries them for close to every sharp book (see "limit": 19354 on Pinnacle below). Limit changes are delivered as regular odds updates.

Advanced metadata (`meta`)

Some bookmakers (e.g. prediction markets / exchanges) provide rich metadata. Example:

{
  "meta": {
    "lay": [
      { "price": 2.00, "size": 100.0 },
      { "price": 2.10, "size": 80.0 }
    ],
    "back": [
      { "price": 1.95, "size": 50.0 }
    ]
  }
}

Typical meta contents may include:

Orderbook ladders (back / lay)
Liquidity hints
Internal sizing or tick metadata

Guaranteed core. For every exchange and prediction market, meta.back and meta.lay are uniform: arrays of { price, size }, best price first, with identical semantics across venues. This shape is stable. Venue extras. Additional meta keys are venue-specific and additive — preserve unknown keys. The back / lay core will not be removed or repurposed.

One venue, betfair-ex, still uses a venue-specific meta shape. It will be migrated to the uniform back / lay core in a future release.

Example: traditional bookmaker odds

{
  "channel": "odds",
  "type": "UPDATE",
  "payload": {
    "fixtureId": "id1100013270505136",
    "odds": {
      "pinnacle": {
        "id1100013270505136:pinnacle:111:0": {
          "bookmaker": "pinnacle",
          "outcomeId": 111,
          "playerId": 0,
          "active": true,
          "price": 1.155,
          "marketActive": true,
          "mainLine": true,
          "bookmakerMarketId": "line/4/487/1628488896/3565645414/0/moneyline",
          "bookmakerOutcomeId": "home",
          "bookmakerChangedAt": 1776717657043,
          "limit": 19354,
          "priceAmerican": -645,
          "priceFractional": "11/71",
          "marketId": 111,
          "changedAt": 1776717657402
        },
        "id1100013270505136:pinnacle:112:0": {
          "bookmaker": "pinnacle",
          "outcomeId": 112,
          "playerId": 0,
          "active": true,
          "price": 5.77,
          "marketActive": true,
          "mainLine": true,
          "bookmakerMarketId": "line/4/487/1628488896/3565645414/0/moneyline",
          "bookmakerOutcomeId": "away",
          "bookmakerChangedAt": 1776717657043,
          "limit": 3000,
          "priceAmerican": 477,
          "priceFractional": "477/100",
          "marketId": 111,
          "changedAt": 1776717657402
        }
      }
    }
  },
  "ts": 1776717657500,
  "entryId": "1776717657500-84805"
}

Example: prediction market odds (extended fields)

{
  "channel": "odds",
  "type": "UPDATE",
  "payload": {
    "fixtureId": "id1100064864029581",
    "odds": {
      "polymarket": {
        "id1100064864029581:polymarket:112:0": {
          "bookmaker": "polymarket",
          "outcomeId": 112,
          "playerId": 0,
          "active": true,
          "price": 6.369,
          "priceAmerican": 537,
          "limit": 4.71,
          "bookmakerMarketId": "1011497",
          "bookmakerOutcomeId": "4937...",
          "meta": {
            "back": [{ "price": 6.369, "size": 30.0 }],
            "lay": [{ "price": 100.0, "size": 15.0 }]
          },
          "marketActive": true,
          "changedAt": 1766939876376
        }
      }
    }
  },
  "ts": 1766939876700,
  "entryId": "1766939876700-653"
}

Implementation guidance

Always key storage by

{fixtureId}:{bookmaker}:{outcomeId}:{playerId}

Group outcomes by marketId (see Concepts) for:
- arbitrage detection
- overround calculations
- probability normalization
Treat active=false or marketActive=false as hard stops
Preserve unknown fields in meta to remain forward-compatible

Getting Started

Channels

Odds Channel - Realtime Betting Odds Stream

What it streams

Routing

Delivery semantics

Payload structure

outcome object (full schema)

Notes on timestamps

Limits

Advanced metadata (`meta`)

Example: traditional bookmaker odds

Example: prediction market odds (extended fields)

Implementation guidance

​What it streams

​Routing

​Delivery semantics

​Payload structure

​outcome object (full schema)

​Notes on timestamps

​Limits

​Advanced metadata (meta)

​Example: traditional bookmaker odds

​Example: prediction market odds (extended fields)

​Implementation guidance

What it streams

Routing

Delivery semantics

Payload structure

outcome object (full schema)

Notes on timestamps

Limits

Advanced metadata (`meta`)

Example: traditional bookmaker odds

Example: prediction market odds (extended fields)

Implementation guidance