Prediction Market — Orderbook WebSocket Push API（基本信息）

1. 概览

1.1 业务说明

Prediction 业务从上游做市商（Predict.fun）实时拉取行情盘口（订单簿 bid/ask）数据，并通过 Binance SApi WebSocket 通道广播给所有订阅方，用于：

• 客户端展示买卖五档 / 十档深度
• 交易终端实时计算最优执行价
• 第三方做市 / 套利策略接入
• 数据分析平台采集行情

1.2 通道特性

项	说明
协议	WebSocket (WSS)
网关	Binance SApi WSS
路由模式	按 topic 广播（任何订阅了该 topic 的连接都会收到，不按 userId 路由）
投递语义	at-most-once
顺序性	同一 marketId 不保证严格顺序；用 updateTimestampMs 字段排序
离线消息	不缓存，重连后请通过 REST API 拉取最新快照
时延	上游事件触发后 < 200 ms 投递（不含网络）
单条大小	< 4 KB（典型市场约 0.5–2 KB）

1.3 业务限制

限制	说明
仅活跃市场	仅订单簿持续更新的活跃市场会推送，已结算 / 已关闭市场不推送
上游依赖	行情来源为 Predict.fun，上游断连时本通道也会暂停推送（不会推空数据）
价格 / 数量精度	price 范围 [0, 1]（2~6 位小数），size 通常为整数，最多 6 位小数

---

2. WebSocket 连接

基础连接规范完全遵循 Binance CMS General Info。本节仅列示行情订阅相关示例。

2.1 连接 URL 示例

订阅单个市场的 orderbook（动态 topic）：

wss://api.binance.com/sapi/wss?random={random}&topic=web3_prediction_orderbook_8859231&recvWindow=30000&timestamp={timestamp}&signature={signature}

订阅聚合 topic（一条流接收所有市场更新）：

wss://api.binance.com/sapi/wss?random={random}&topic=web3_prediction_orderbook_data&recvWindow=30000&timestamp={timestamp}&signature={signature}

订阅多个市场（管道符 | 分隔）：

?topic=web3_prediction_orderbook_8859231|web3_prediction_orderbook_8859232

2.2 鉴权与签名

完全等同于用户事件推送（参考 Binance CMS General Info 的鉴权章节）：

• Header: X-MBX-APIKEY: <api_key>
• 签名：HMAC SHA256(query string, secret_key)
• query string 按参数名字母升序拼接

2.3 订阅、心跳、限流

完全遵循 CMS 规范，本文不重复列举：

• 客户端每 30 秒发送 PING
• 单连接 5 条/秒消息上限
• 单连接 24h 后需重连

---

3. 推送消息结构

3.1 信封

每条 orderbook 推送由 SApi 网关投递，业务 payload 即 data 字段中的 JSON 字符串：

{
  "type": "TOPIC",
  "topic": "web3_prediction_orderbook_8859231",
  "data": "{\"msgType\":\"orderbook\",\"marketId\":8859231,\"updateTimestampMs\":1717420800123,\"asks\":[[\"0.32\",\"500\"],[\"0.33\",\"1200\"]],\"bids\":[[\"0.31\",\"800\"],[\"0.30\",\"2000\"]]}"
}

⚠️ data 字段为字符串化的 JSON，需要二次 JSON.parse。

3.2 业务 Payload 完整结构

{
  "msgType": "orderbook",
  "marketId": 8859231,
  "updateTimestampMs": 1717420800123,
  "asks": [
    ["0.32", "500"],
    ["0.33", "1200"],
    ["0.34", "300"]
  ],
  "bids": [
    ["0.31", "800"],
    ["0.30", "2000"],
    ["0.28", "1500"]
  ]
}

3.3 字段定义

字段	类型	必填	说明
msgType	string	✅	固定为 "orderbook"，用于客户端区分消息类型
marketId	number (long)	✅	Binance 内部 market ID（已从上游 vendor ID 映射），与 REST API 一致
updateTimestampMs	number (long)	✅	行情更新的毫秒级 UTC 时间戳，用于乱序判定
asks	array	✅	卖单档位列表，按 price 升序排列；空数组表示无卖单
bids	array	✅	买单档位列表，按 price 降序排列；空数组表示无买单

3.4 档位（asks / bids）数据结构

每个档位是一个长度为 2 的数组，元素均为字符串数字：

[<price>, <size>]

位置	字段	类型	说明
[0]	price	string	价格，范围 (0, 1)，单位为 outcome share/USDT 比率，例如 "0.32" 表示 0.32 USDT/share
[1]	size	string	数量（outcome shares），可能含小数，例如 "500" / "500.5"

注意点

• 数值用字符串传输：避免 JS 浮点精度损失。客户端使用前需用 BigDecimal / BigNumber 解析
• size = 0 不会出现：上游会过滤空档位，size 始终 > 0
• 档位深度：通常返回前 N 档（具体值随上游策略调整，一般 ≤ 50 档）

---

4. Topic 列表

Prediction 行情推送提供两个独立的 topic 模式，按用途选择即可（也可同时订阅）。

4.1 动态 topic（按市场订阅）

web3_prediction_orderbook_{marketId}

项	说明
命名规则	前缀 web3_prediction_orderbook_ + 市场 internal ID
示例	web3_prediction_orderbook_8859231
适用	仅关心特定市场（如订单簿组件、单 market 套利策略）
优点	流量最小，每个市场独立订阅
缺点	监听很多市场时需要订阅很多 topic（注意 5 msg/s 限流）

4.2 聚合 topic（一条流全市场）

web3_prediction_orderbook_data

项	说明
命名规则	固定字符串
适用	数据采集 / 行情聚合 / 全平台分析
优点	只需订阅一个 topic 即可接收所有市场行情
缺点	流量大，需客户端按 marketId 字段二次过滤

4.3 选型建议

场景	推荐 topic
App / Web 仅查看单个市场详情页	动态 topic（按市场进入/离开页面切换订阅）
交易终端，关注 ≤ 10 个市场	动态 topic（订阅时一次拼接 ≤ 10 个 topic）
数据采集 / 全市场策略 / 行情仓库	聚合 topic
混合（首屏聚合 + 详情页深度）	同时订阅，聚合 topic 用于首屏，动态 topic 用于深度页

4.4 同时订阅注意事项

若客户端同时订阅了动态 topic 和聚合 topic，同一笔行情会被推送两次（每个 topic 各一次）。 客户端需用 marketId + updateTimestampMs 做幂等，避免重复刷新 UI。

---

5. 推送频率与建议

5.1 推送频率

项	数值
单市场更新峰值	~10 条/秒（活跃市场上游全量推送时）
单市场更新均值	~1-3 条/秒
全平台聚合峰值	数百条/秒（高峰时段全部市场叠加）

5.2 客户端处理建议

项	建议
节流 / 防抖	UI 渲染建议 100ms 防抖，避免高频更新拖累渲染线程
乱序判定	必须用 updateTimestampMs 比对，丢弃比当前快照旧的消息
重连补偿	重连后先调 REST API 拉一次盘口快照，再以 WSS 增量更新（CMS 不缓存离线消息）
价格 / 数量解析	用 BigDecimal / BigNumber.js 解析，避免精度损失
异常市场过滤	asks 和 bids 都为空数组时表示无挂单（停摆 / 即将结算市场），客户端自行决定是否展示

5.3 限流防护

若 N 个动态 topic 一次性订阅，建议：
  - 用单条 SUBSCRIBE 命令拼接所有 topic（用 | 分隔），避免连发多条命令触发 5 msg/s 限流
  - 大量 topic 切换时使用 UNSUBSCRIBE 释放无关市场，控制带宽
  - 同一连接全部 prediction 业务（用户事件 + orderbook）只用一个 WSS 连接，不要每类 topic 独立连

---