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

​

端点

wss://v5.oddspapi.io/ws

​

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

1. 连接到 WebSocket 并发送带有过滤器的 login
2. 收到 login_ok 后，开始将更新按行键（如 oddsId）应用到您的存储中
3. 通过 REST 获取快照（例如 /fixtures、/fixtures/odds）并合并：按键比较，保留 changedAt 较新的一侧
4. 持久化 serverEpoch 和每个频道的 lastSeenId（来自 entryId）
5. 重新连接时，发送 serverEpoch + lastSeenId 以恢复
6. 如果收到 snapshot_required，通过 REST 重新获取快照 —— 合并规则相同

​

登录模式

​

消息信封

{
  "channel": "scores",
  "type": "UPDATE",
  "payload": { "...": "..." },
  "ts": 1765497902846,
  "entryId": "1765497902846-3221"
}

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

entryId不保证是连续的。有关完整说明，请参阅恢复和重放。

​

编码：JSON vs 二进制

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

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 端点。

​

WebSocket限制

​

询问AI助手

• 询问ChatGPT
• 询问Claude
• 询问Perplexity
• 询问Gemini