Copy page

Prediction Market — Orderbook WebSocket Streams (Overview)

1. Overview

1.1 Business Description

The Prediction service pulls real-time orderbook (bid/ask) data from upstream market makers (Predict.fun) and broadcasts it via the Binance SApi WebSocket channel to all subscribers. Use cases include:

• Client display of top-N bid/ask depth
• Trading terminals computing best execution price in real time
• Third-party market making / arbitrage strategies
• Data analytics platform feeds

1.2 Channel Characteristics

Item	Description
Protocol	WebSocket (WSS)
Gateway	Binance SApi WSS
Routing mode	Broadcast by topic (any connection subscribed to the topic receives it; NOT routed by userId)
Delivery semantics	at-most-once
Ordering	No strict ordering is guaranteed for the same marketId; use the updateTimestampMs field for ordering
Offline messages	Not cached — fetch the latest snapshot via REST API after reconnect
Latency	Delivered within < 200 ms after upstream event triggers (excluding network)
Per-message size	< 4 KB (typical markets ~0.5–2 KB)

1.3 Business Constraints

Constraint	Description
Active markets only	Only continuously updating active markets are pushed; resolved / closed markets are not pushed
Upstream dependency	Quotes come from Predict.fun; if upstream disconnects, this channel pauses (no empty data is pushed)
Price / Size precision	price ∈ (0, 1) (2–6 decimals), size > 0 and may include decimals; both are JSON numbers

---

2. WebSocket Connection

The basic connection specification fully follows Binance CMS General Info. This section only lists orderbook-specific examples.

2.1 Connection URL Examples

Subscribe to a single market's orderbook:

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

Subscribe to multiple markets (separated by |):

Code
?topic=web3_prediction_orderbook_8859231|web3_prediction_orderbook_8859232

2.2 Authentication & Signature

Identical to user event push (refer to the auth section in Binance CMS General Info):

• Header: X-MBX-APIKEY: <api_key>
• Signature: HMAC SHA256(query string, secret_key)
• query string sorted alphabetically by parameter name

2.3 Subscribe / Heartbeat / Rate Limit

Fully follow CMS spec, not duplicated here:

• Client sends PING every 30 seconds
• Per-connection rate limit: 5 messages/second
• Single connection valid for 24h then must reconnect

---

3. Push Message Structure

3.1 Envelope

Each orderbook push is delivered by the SApi gateway. The business payload is a JSON string inside the data field:

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

⚠️ The data field is a stringified JSON. Requires a second JSON.parse.

3.2 Full Business Payload

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

3.3 Field Definitions

Field	Type	Required	Description
msgType	string	✅	Fixed value "orderbook", used by clients to dispatch message types
marketId	number (long)	✅	Binance internal market ID (mapped from upstream vendor ID), aligned with REST API
updateTimestampMs	number (long)	✅	Quote update millisecond UTC timestamp; use this for out-of-order detection
asks	array	✅	List of ask levels, sorted by price ascending; empty array means no asks
bids	array	✅	List of bid levels, sorted by price descending; empty array means no bids

3.4 Level Data Structure (asks / bids)

Each level is a 2-element array of JSON numbers:

Code
[<price>, <size>]

Index	Field	Type	Description
[0]	price	number	Price ∈ (0, 1), in outcome share/USDT ratio, e.g. 0.32 means 0.32 USDT/share
[1]	size	number	Quantity (outcome shares), may include decimals, e.g. 500 / 500.5

Notes

• Values may carry floating-point noise (e.g. 6865.999999999999). Round before displaying or comparing.
• size = 0 does not appear: upstream filters empty levels; size is always > 0.
• Depth: typically top N levels (the value depends on upstream policy, generally ≤ 50).

---

4. Topic

Each market has its own topic:

Code
web3_prediction_orderbook_{marketId}

Item	Description
Naming rule	Prefix web3_prediction_orderbook_ + market internal ID
Example	web3_prediction_orderbook_8859231
Use case	Orderbook components, single-market arbitrage, any client watching specific markets
Many markets	Concatenate topics with | in one subscribe (mind the 5 msg/s limit)

---

5. Push Frequency & Recommendations

5.1 Push Frequency

Item	Value
Per-market update peak	~10 messages/sec (when upstream pushes full depth on active markets)
Per-market update average	~1-3 messages/sec

5.2 Client Processing Recommendations

Item	Recommendation
Throttling / debouncing	Debounce UI rendering at 100ms to avoid blocking the rendering thread
Out-of-order detection	Must compare updateTimestampMs and discard messages older than the current snapshot
Reconnect compensation	After reconnect, first fetch a snapshot via REST API, then apply WSS deltas (CMS does not cache offline messages)
Price / size parsing	Values are JSON numbers; round them for display instead of printing them raw
Empty market filtering	Both asks and bids empty means no orders (paused / about-to-resolve markets); decide whether to render

5.3 Rate Limit Protection

Code
If subscribing to N topics at once:
  - Use a single SUBSCRIBE command concatenating all topics (separated by |) to avoid hitting 5 msg/s
  - When switching many topics, use UNSUBSCRIBE to release unrelated markets and control bandwidth
  - Use ONE WSS connection for all prediction business (user events + orderbook); do NOT open separate connections per topic

---