Copy page

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）：

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

訂閱聚合 topic（一條流接收所有市場更新）：

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

訂閱多個市場（管道符 | 分隔）：

Code
?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 字串：

Code
{
  "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 完整結構

Code
{
  "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 的陣列，元素均為字串數字：

Code
[<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（按市場訂閱）

Code
web3_prediction_orderbook_{marketId}

項	說明
命名規則	字首 web3_prediction_orderbook_ + 市場 internal ID
示例	web3_prediction_orderbook_8859231
適用	僅關心特定市場（如訂單簿元件、單 market 套利策略）
優點	流量最小，每個市場獨立訂閱
缺點	監聽很多市場時需要訂閱很多 topic（注意 5 msg/s 限流）

4.2 聚合 topic（一條流全市場）

Code
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 限流防護

Code
若 N 個動態 topic 一次性訂閱，建議：
  - 用單條 SUBSCRIBE 命令拼接所有 topic（用 | 分隔），避免連發多條命令觸發 5 msg/s 限流
  - 大量 topic 切換時使用 UNSUBSCRIBE 釋放無關市場，控制頻寬
  - 同一連線全部 prediction 業務（使用者事件 + orderbook）只用一個 WSS 連線，不要每類 topic 獨立連

---