> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oddspapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Odds Channel - Realtime Betting Odds Stream

> High-throughput realtime betting odds via WebSocket. Stream live odds aggregated from 200+ bookmakers. Decimal, fractional, American formats with orderbook depth.

## 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

* This channel is **high throughput**
* Updates are **latest-state only**
* The gateway may coalesce or drop intermediate updates under load
* Do **not** assume tick-by-tick completeness

Treat every message as a **state update**, not a ledger.

> Need every price move or the closing line? The stream is for trading on latest state; for full movement use [Historical Odds](/api-reference/concepts#historical-odds-and-clv) and for opening/closing prices use [CLV](/api-reference/concepts#historical-odds-and-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 (if provided)                          |                                     |
| `betslip`            | `string \| null`  | Optional bookmaker betslip or deeplink token                  |                                     |
| `meta`               | `object \| null`  | Bookmaker-specific metadata (orderbooks, ladders, etc.)       |                                     |
| `changedAt`          | `number`          | Gateway change timestamp (epoch ms, UTC)                      |                                     |

***

## Notes on timestamps

* `changedAt` is **always present** and represents when the gateway accepted the update
* `bookmakerChangedAt` (when present) reflects the bookmaker’s own timestamp
* These values may differ — do not assume equality

***

## Advanced metadata (`meta`)

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

Example:

```json theme={null}
{
  "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

The schema of `meta` is **bookmaker-specific** and may evolve.

***

## Example: traditional bookmaker odds

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

***