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

# 行情数据与标识符 - 通过 Apexium 提供的 OddsPapi v5

> Apexium API 所提供的 OddsPapi v5 行情数据如何组织：运动、联赛、赛事、盘口、选项和赔率标识符，以及它们如何变成订单。

Apexium API 的行情数据就是 **OddsPapi v5**：路径、参数、响应和标识符完全相同，位于 `/v1/{lang}` 下（参见[语言](https://docs.apexiumbet.com/zh/api-reference/overview.md#语言)）。您在赔率中读取到的 `fixtureId`、`outcomeId` 和 `playerId`，就是您下单所用的标识符：数据与执行之间没有映射。

> [!NOTE]
>
> OddsPapi 在其自己的文档 [docs.oddspapi.io](https://docs.oddspapi.io) 中说明了这些数据的每个字段。要迁移已在使用 OddsPapi 的客户端？参见[从 OddsPapi 迁移](https://docs.apexiumbet.com/zh/guides/coming-from-oddspapi.md)。

## 运动、联赛、赛季

* **`sportId`。** 整数。它的两位数字是其他多个标识符的开头。通过 [`GET /v1/{lang}/sports`](https://docs.apexiumbet.com/zh/coverage) 列出。
* **`tournamentId`。** 整数。属于一项运动。通过 `GET /v1/{lang}/tournaments` 列出。
* **`seasonId`。** 整数。属于一个联赛。通过 `GET /v1/{lang}/seasons` 列出。

## 实体层级

所有内容都挂在同一棵树上：

```
Sport
  └── Tournament (recurring competition)
        └── Season (time-bound instance)
              └── Fixture (single match)
                    ├── Participants (teams / competitors)
                    ├── Scores (per period)
                    └── Players (squad members)
```

**联赛**是周期性举办的竞赛（“Premier League”）；**赛季**是它在某一时期的一届（“Premier League 25/26”）；**赛事**是其中的一场比赛：

```
Sport:       Soccer                  (sportId=10)
Tournament:  Premier League          (tournamentId=17)
Season:      Premier League 25/26    (seasonId=130281)
Fixture:     Arsenal vs Chelsea      (fixtureId=id1000001770366972)
  ├── participant1Id → Arsenal
  ├── participant2Id → Chelsea
  ├── Scores:  result 2-1, p1 1-0, p2 1-1   (per-period rows)
  └── Players: squads per participant        (player markets)
```

* **赛事。** 它包含赛程和状态：`startTime`（epoch 秒）、`statusId`、`participant1Id` 和 `participant2Id`、`seasonId`、场馆。
* **比分。** 按时段记录，键为 `result`、`p1`、`p2` 等。`result` 行是权威的最终比分或当前比分。
* **赔率。** 它们通过[赔率标识符](#赔率标识符)挂接到赛事。

## 盘口与选项

> [!NOTE]
>
> 每个投注选项都遵循固定的层级：`marketType → period → handicap → side`，全部编码在 `outcomeId` 中。因此无论哪家博彩公司，同一项投注始终具有相同的 `marketId` 和 `outcomeId`。球员是唯一不在 `outcomeId` 中的部分：它是 `playerId`。

### 盘口如何分解

每个 `outcomeId` 都来自同一个确定性的分解：

```
marketType → period → handicap (line value) → side (outcome)   [+ optional player]
```

| 层级 | 字段 | 含义 |
| - | - | - |
| 1 | `marketType` | 盘口的类型：`1x2`、`totals`、`spreads`、`spreads-european`、`bothteamsscore`、`drawnobet`、`oddeven`、… |
| 2 | `period` | 盘口适用的时段：`fulltime`、`p1`、`p2` |
| 3 | `handicap` | 盘口线的数值，例如 `2.5` 或 `-0.25`。每个盘口线数值都是独立的 `marketId`。没有盘口线的盘口（如 `1x2`）为 `0.0` |
| 4 | `outcomeName` | 方向：`Over` / `Under`、`1` / `X` / `2`、`Yes` / `No`、… |

由于每个盘口线数值都有各自的 `marketId`，“Over 2.5”和“Over 3.5”是不同的盘口。在同一个 `marketId` 内，选项只是该盘口线的各个方向。

> [accordion] 示例：足球（sportId 10）
>
> 每个 `marketId` 等于其第一个 `outcomeId`，每个盘口线数值都是独立的盘口：
>
> | marketId | marketName | marketType | period | handicap | outcomeId | outcomeName |
> | -: | - | - | - | -: | -: | - |
> | 101 | Full Time Result | `1x2` | fulltime | 0.0 | 101 | 1 |
> | 101 | Full Time Result | `1x2` | fulltime | 0.0 | 102 | X |
> | 101 | Full Time Result | `1x2` | fulltime | 0.0 | 103 | 2 |
> | 104 | Both Teams To Score | `bothteamsscore` | fulltime | 0.0 | 104 | Yes |
> | 104 | Both Teams To Score | `bothteamsscore` | fulltime | 0.0 | 105 | No |
> | 1010 | Over Under Full Time | `totals` | fulltime | 2.5 | 1010 | Over |
> | 1010 | Over Under Full Time | `totals` | fulltime | 2.5 | 1011 | Under |
> | 1068 | Asian Handicap | `spreads` | fulltime | -0.5 | 1068 | 1 |
> | 1068 | Asian Handicap | `spreads` | fulltime | -0.5 | 1069 | 2 |
> | 10208 | First Half Result | `1x2` | p1 | 0.0 | 10208 | 1 |
> | 10208 | First Half Result | `1x2` | p1 | 0.0 | 10209 | X |
> | 10208 | First Half Result | `1x2` | p1 | 0.0 | 10210 | 2 |
>
> 第一行的含义是：`marketType=1x2`、`period=fulltime`、`handicap=0.0`、`outcomeName=1`，即全场赛果的主队一方。

某项运动的完整盘口映射来自 `GET /v1/{lang}/markets?sportId=10`。

### `marketId` 与 `outcomeId`

* **共享 `marketId`。** 一个盘口的所有选项共享其 `marketId`。
* **第一个选项。** 一个盘口的第一个 `outcomeId` 等于其 `marketId`，因此无需额外的元数据即可对选项分组。
* **`marketLength`。** 一个 `marketId` 下的选项数量：它们是共同构成完整概率空间的各个方向。`1x2` 为 3。
* **结构。** 两者都是整数，按 `{sportId (2 digits)}{incrementing number}` 构建：`11xxxx` 是篮球，`14xxxx` 是美式橄榄球。

同一个 `marketId` 的所有选项涵盖了每一种结果。计算利润率、超额概率（overround）和套利时，请按 `marketId` 对赔率分组。

## 参赛方与球员

* **`participantId`。** 整数，一支球队或一名参赛者。通过 `GET /v1/{lang}/participants` 列出。
* **`playerId`。** 整数，用于球员盘口。`0` 表示与球员无关的盘口。通过 `GET /v1/{lang}/players` 列出。

## 赛事 ID

`fixtureId` 是一个字符串，编码了多项信息：

```
id1100013262926199
```

* `id`：命名空间前缀；请将其视为不透明值
* `11`：`sportId`（2 位）
* `000132`：`tournamentId`（6 位）
* `62926199`：原生赛事 ID

仅凭 `fixtureId` 就能读出运动和联赛。

## 赔率标识符

价格由其 `oddsId` 标识：

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

例如 `id1400003160574217:sharpbet:141:0`。请将其用作您所存储价格的主键。

去掉博彩公司，就得到**投注选项**，即 `{fixtureId}:{outcomeId}:{playerId}`：它在每家博彩公司都是同一项投注，在任何地方的输赢结果也相同。

## 从赔率到订单

订单使用相同的三个标识符来指定一个投注选项。要买入（back）上面的价格：

```json theme={null}
{
  "mode": "preview",
  "clientOrderId": "my-order-0003",
  "fixtureId": "id1400003160574217",
  "outcomeId": 141,
  "playerId": 0,
  "side": "back",
  "bookmakers": ["sharpbet"],
  "stake": { "amount": "100.00", "currency": "USD" },
  "minPrice": "1.90",
  "acceptBetterOdds": true,
  "acceptPartialStake": true
}
```

* **价格下限。** `minPrice` 是您接受的最低价格：您读到的价格，或略低一点，以留出价格变动的空间。
* **博彩公司。** 省略 `bookmakers`，即可让 Apexium 将投注额拆分到您账户的每一家博彩公司。
* **投注单价格。** [`GET /v1/betslip`](https://docs.apexiumbet.com/zh/api-reference/overview#投注单) 给出应用您账户规则之后的价格，它可能与市场价格不同。参见[行情赔率与投注单](https://docs.apexiumbet.com/zh/guides/feed-odds-and-betslip.md)。

参见[预览与下单](https://docs.apexiumbet.com/zh/guides/preview-and-place.md)。

## 时间戳

行情数据使用 OddsPapi 的两种单位：

* **Epoch 秒**用于赛程：`startTime`、`startTimeFrom`、`startTimeTo`。
* **Epoch 毫秒**用于赔率更新：`changedAt`、`bookmakerChangedAt` 以及 `since` 筛选参数。

账户及其订单的 `/v1` 端点则使用 UTC 的 ISO 8601 字符串。

## 高效轮询

* **`since`。** 在 `fixtures/odds` 和 `fixtures/odds/main` 上，传入您最近看到的 `changedAt`，即可只获取此后发生变化的内容。
* **存储。** 以 `oddsId` 为键存储价格，这样更新会替换行，而不是新增行。
* **限额。** 行情数据计入您密钥的总体额度；参见[限额](https://docs.apexiumbet.com/zh/api-reference/limits.md)。

## 历史赔率与收盘价值（CLV）

| 用途 | 端点 |
| - | - |
| 某个选项的完整价格时间线 | `GET /v1/{lang}/fixtures/odds/historical` |
| 开盘线与收盘线（OLV / CLV） | `GET /v1/{lang}/fixtures/odds/clv` |

两者使用相同的 `oddsId`，因此您可以将自己的成交与其历史记录关联起来：

* **CLV。** 将您的成交价格与收盘线比较，以衡量您的优势。
* **成交审计。** 将您的成交价格与记录的时间线比较。
* **回测。** 用您的策略回放时间线。

## 参考文档

行情数据端点位于侧边栏的 **API → API 参考** 下，分为 **Reference data**、**Fixtures** 和 **Odds** 三组。它们的参数和响应结构来自 OddsPapi v5 参考文档，仅限于 Apexium 转发的内容。有关数据本身的背景，参见 [OddsPapi 文档](https://docs.oddspapi.io)。

## 术语表

* **sportId**：运动的数字标识符；是 `marketId`、`outcomeId` 和 `fixtureId` 的前两位数字。
* **fixtureId**：赛事的字符串键，编码了运动、联赛和原生 ID。
* **marketType**：盘口的类型（`1x2`、`totals`、`spreads`、…）。
* **period**：盘口适用的时段（`fulltime`、`p1`、`p2`）。
* **handicap**：盘口的盘口线数值；每个盘口线数值都是独立的 `marketId`。
* **marketId**：对同一盘口的选项分组的整数；等于其第一个 `outcomeId`。
* **marketLength**：一个 `marketId` 下的选项数量。
* **outcomeId**：标识一个投注选项的整数：盘口类型、时段、盘口线和方向。
* **playerId**：将选项与某名球员关联；`0` 表示与球员无关的盘口。
* **participantId**：标识一支球队或参赛者的整数。
* **oddsId**：价格键，`{fixtureId}:{bookmaker}:{outcomeId}:{playerId}`。
* **OLV / CLV**：开盘与收盘价值，即某个选项第一个和最后一个记录的价格。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.