> For the complete documentation index, see [llms.txt](https://rock-odds.gitbook.io/rock-odds-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rock-odds.gitbook.io/rock-odds-docs/data-model.md).

# Data model

RockOdds uses the same hierarchy in REST responses and the real-time stream:

```
game
└── markets[market_id]
    └── lines[]
        └── selections[]
```

Build local state with games keyed by `game_id` and each game's markets keyed by `market_id`.

## Game

```json
{
  "game_id": "a1b2c3d4-e5f6-47a8-9012-3456789abcde",
  "sport": "NBA",
  "home_team": "Los Angeles Lakers",
  "away_team": "Boston Celtics",
  "start_time": "2026-08-28T19:30:00-04:00",
  "live": false,
  "markets": {}
}
```

| Field        | Type    | Description                                             |
| ------------ | ------- | ------------------------------------------------------- |
| `game_id`    | string  | Stable game identifier. Treat it as opaque.             |
| `sport`      | string  | Sport code.                                             |
| `home_team`  | string  | Home team display name.                                 |
| `away_team`  | string  | Away team display name.                                 |
| `start_time` | string  | Scheduled start time in ISO 8601 format with an offset. |
| `live`       | boolean | Whether the game is currently in play.                  |
| `markets`    | object  | Markets keyed by `market_id`.                           |

Do not identify a game by team names or start time. Store the supplied `game_id`.

## Market

```json
{
  "market_type": "team_total",
  "period": "game",
  "side": "home",
  "label": null,
  "limit": 500,
  "lines": []
}
```

| Field         | Type           | Description                                                           |
| ------------- | -------------- | --------------------------------------------------------------------- |
| `market_type` | string         | Machine-readable category such as `spread`, `total`, or `team_total`. |
| `period`      | string         | Period to which the market applies.                                   |
| `side`        | string or null | `home` or `away` for side-specific markets.                           |
| `label`       | string or null | Human-readable context for variable markets.                          |
| `limit`       | number or null | Maximum accepted stake when supplied.                                 |
| `lines`       | array          | The prices and outcomes currently associated with the market.         |

The property name inside the game's `markets` object is the `market_id`. Use it for updates and lookups, but do not parse it. Some IDs may look descriptive and others may look like UUIDs; clients must handle both as opaque strings.

New `market_type` values may appear over time. Ignore types your application does not yet support.

## Line

```json
{
  "selections": [
    {"name": "over", "odds": "-110", "line": "224.5"},
    {"name": "under", "odds": "-110", "line": "224.5"}
  ],
  "locked": false,
  "is_mainline": true,
  "updated_at": "2026-08-28T23:25:10+00:00"
}
```

| Field         | Type           | Description                                |
| ------------- | -------------- | ------------------------------------------ |
| `selections`  | array          | Outcomes offered on this line.             |
| `locked`      | boolean        | `true` when the line is unavailable.       |
| `is_mainline` | boolean        | `true` for the primary line in the market. |
| `updated_at`  | string or null | Last known update time in ISO 8601 format. |

A market can have alternate lines in addition to its mainline. Do not assume the first array element is the mainline; use `is_mainline`.

REST responses normally exclude locked lines. Streaming state can contain locked lines, and a `locked` event can change an existing line from open to unavailable.

## Selection

```json
{
  "name": "home",
  "odds": "-110",
  "line": "-3.5"
}
```

| Field  | Type           | Description                                                                |
| ------ | -------------- | -------------------------------------------------------------------------- |
| `name` | string         | Outcome identity, such as `home`, `away`, `over`, `under`, `yes`, or `no`. |
| `odds` | string or null | American odds when available.                                              |
| `line` | string or null | Spread or total value. Moneyline-style outcomes usually use `null`.        |

Match selections by `name`, not by array position. Soccer moneylines, for example, can contain `home`, `draw`, and `away` selections.

## Common market types

| `market_type`       | Common selection names                    | `line` value         |
| ------------------- | ----------------------------------------- | -------------------- |
| `spread`            | `home`, `away`                            | Point or goal spread |
| `total`             | `over`, `under`                           | Combined total       |
| `moneyline`         | `home`, `away`; soccer may include `draw` | Usually `null`       |
| `team_total`        | `over`, `under`                           | Team total           |
| `odd_even`          | `even`, `odd`                             | Usually `null`       |
| `score_first_10`    | `no`, `yes`                               | Usually `null`       |
| `hits_runs_errors`  | `over`, `under`                           | Combined total       |
| `total_hits`        | `over`, `under`                           | Hits total           |
| `home_run`          | `no`, `yes`                               | Usually `null`       |
| `yrfi`              | `no`, `yes`                               | Usually `null`       |
| `both_teams_score`  | `no`, `yes`                               | Usually `null`       |
| `team_exact_goals`  | Named goal-count outcomes                 | Usually `null`       |
| `match_exact_goals` | Named goal-count outcomes                 | Usually `null`       |

Not every market type is available for every sport, game, or period.
