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

# WebSocket API概述 - 实时体育数据流

> 连接OddsPapi WebSocket网关以获取低延迟实时体育博彩数据。使用JSON或MessagePack编码流式传输实时赔率、比分、赛事和事件。

## 端点

生产网关：

```
wss://v5.oddspapi.io/ws
```

您的账户可能使用不同的区域或主机名。请使用仪表板中显示的端点。

***

## 推荐的集成流程（生产环境）

使用REST获取快照，使用WebSocket获取实时更新：

1. 通过REST获取初始快照（例如`/fixtures`、`/fixtures/odds`）
2. 连接到WebSocket并发送带有过滤器的`login`
3. 收到`login_ok`后开始处理更新
4. 持久化`serverEpoch`和每个频道的`lastSeenId`（来自`entryId`）
5. 重新连接时，发送`serverEpoch` + `lastSeenId`以恢复
6. 如果收到`snapshot_required`，通过REST重新获取快照

***

## 登录模式

WebSocket支持**仅登录订阅**。要更改过滤器或频道，请使用新的`login`重新连接。

***

## 消息信封

所有更新共享一个公共信封：

```json theme={null}
{
  "channel": "scores",
  "type": "UPDATE",
  "payload": { "...": "..." },
  "ts": 1765497902846,
  "entryId": "1765497902846-3221"
}
```

* `channel` – 流名称（例如`odds`、`fixtures`）
* `type` – 消息类型（目前始终为`UPDATE`）
* `payload` – 频道特定数据
* `ts` – UTC时间戳（毫秒）
* `entryId` – 用于重放/恢复的游标

> `entryId`不保证是连续的。有关完整说明，请参阅[恢复和重放](/zh/websocket/resume-replay)。

***

## 编码：JSON vs 二进制

在登录时使用`receiveType`控制。

* `"json"`（默认）— 所有消息作为UTF-8 JSON到达
* `"binary"` — 数据帧使用MessagePack；控制帧保持JSON

**客户端提示：**

```js theme={null}
import msgpack from "@msgpack/msgpack";

const obj = typeof raw === "string"
  ? JSON.parse(raw)
  : msgpack.decode(new Uint8Array(raw));
```

> 控制消息如`login_ok`、`snapshot_required`和`resume_complete`始终是JSON，即使在二进制模式下也是如此。

***

## 频道类型

* **赛事范围**：`fixtures`、`scores`、`odds`、`bookmakers`。— 有效载荷包含`fixtureId`
* **期货范围**：`futures`、`bookmakersFutures`、`oddsFutures` — 包含`futureId`
* **全局**：`currencies` — 无ID

> 有关每个频道的模式，请参阅`/websocket/channels/*`。

***

## 吞吐量指南

* 对于高容量频道如`odds`，首选`receiveType: "binary"`
* 使用过滤器（`sportIds`、`bookmakers`）减少噪音
* `odds`应被视为**最新状态**，而不是交易记录账本

> 需要完整的价格变动或收盘价？请使用 REST [历史赔率与 CLV](/zh/api-reference/concepts) 端点。

***

## WebSocket限制

| 限制类型 | 描述                                                       |
| ---- | -------------------------------------------------------- |
| 并发连接 | 按`apiKey`组强制执行（最大：5）。参见错误`4003`。                         |
| 背压   | 如果您的客户端无法跟上，连接将被关闭（`4002`）。                              |
| 重放窗口 | 参见[恢复和重放](/zh/websocket/resume-replay)中的`resumeWindowMs` |
| 消息速率 | 没有明确限制，但建议使用过滤器以提高性能                                     |

***

## 询问AI助手

想使用您喜欢的AI探索或提问关于此页面的问题？

点击下面的链接——每个链接都会在选定的工具中打开此页面并预填提示：

* [询问ChatGPT](https://chatgpt.com/?prompt=Read+from+https%3A%2F%2Fdocs.oddspapi.io%2Fllms-full.txt+and+help+me+with+this+API.)
* [询问Claude](https://claude.ai/?prompt=Please+read+https%3A%2F%2Fdocs.oddspapi.io%2Fllms-full.txt+and+help+me+use+this+API.)
* [询问Perplexity](https://www.perplexity.ai/search?q=Read+from+https%3A%2F%2Fdocs.oddspapi.io%2Fllms-full.txt)
* [询问Gemini](https://gemini.google.com/app?query=Read+from+https%3A%2F%2Fdocs.oddspapi.io%2Fllms-full.txt+and+help+me+use+this+API.)