Wallet Events WebSocket API

1. Overview

1.1 Business Description

Binance Web3 Prediction pushes 14 types of business events to individual users in real time via the Binance SApi WebSocket channel, covering 4 major categories: trading (market / limit), reward claim, fund transfer, and market resolution.

1.2 Channel Characteristics

Item	Description
Protocol	WebSocket (WSS)
Gateway	Binance SApi WSS (shares the same connection infrastructure with Spot / USD-M SApi)
Routing	Exact (topic, userId) match — only the matching user receives the push
Delivery semantics	at-most-once (no retransmission guarantee)
Ordering	No strict ordering is guaranteed for the same user/topic; use pushId for idempotency
Offline messages	Not cached — please pull the latest state via REST API after reconnect
Latency	Delivered within < 500 ms after the business event triggers (excluding network)
Per-message size	< 2 KB

1.3 Target Audience

• Wallet clients integrating Prediction business
• Third-party agent trading parties
• Data analytics / risk-control systems

---

2. WebSocket Connection

The basic connection specification fully follows Binance CMS General Info. This section excerpts the key points and adds Prediction-specific examples.

2.1 Connection URL

Base URL:

wss://api.binance.com/sapi/wss

Full connection URL format:

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

Example (subscribing to the prediction buy success topic):

wss://api.binance.com/sapi/wss?random=56724ac693184379ae23ffe5e910063c&topic=web3_prediction_pm_market_buy_success&recvWindow=30000&timestamp=1753244327210&signature=341098eff29e3ef395ed4ea85035bd7fe9e9356d2b0d4f1f97655c74516a2d65

2.2 URL Parameters

Param	Required	Description
random	✅	Random string or number, ≤ 32 chars recommended; ensures signature uniqueness
topic	✅	Topics to subscribe; multiple topics joined by |
recvWindow	✅	Time window (ms), max 60000
timestamp	✅	Millisecond UTC timestamp at request time
signature	✅	HMAC SHA256 signature (see below)

2.3 Authentication

Header

X-MBX-APIKEY: <your_api_key>

Signature Steps

1. Collect all URL parameters (excluding signature itself)
2. Sort parameters by name in alphabetical order and join into a query string
3. Apply HMAC SHA256 with the Secret Key on this string

Payload example:

random=56724ac693184379ae23ffe5e910063c&recvWindow=30000&timestamp=1753244327210&topic=web3_prediction_pm_market_buy_success

Bash verification:

echo -n "random=56724ac693184379ae23ffe5e910063c&recvWindow=30000&timestamp=1753244327210&topic=web3_prediction_pm_market_buy_success" \
  | openssl dgst -sha256 -hmac "<YOUR_SECRET_KEY>"

2.4 Time Window

The server validates: server_time <= timestamp + recvWindow. Requests outside this window are rejected. Clients are advised to periodically sync local time with Binance Server Time.

2.5 Connection Lifecycle

Item	Rule
Max single connection lifetime	24 hours
After timeout	Client must reconnect, regenerating timestamp + signature
Server heartbeat timeout	Disconnects if no PING received for 1 minute

2.6 Subscribe / Unsubscribe / Heartbeat / Rate Limits

Fully follows Binance CMS General Specification. Not duplicated here.

Quick reference:

• Subscribe at connect time via URL parameter topic=topic1|topic2
• After connection, dynamically subscribe / unsubscribe via JSON command {"command":"SUBSCRIBE","value":"..."}
• Client must send a PING (empty payload) every 30 seconds
• Per-connection rate limit: 5 messages/second; exceeding causes disconnection, repeated violations cause IP ban

For detailed fields, response structures, error codes, and reconnection guidance, refer to the CMS document.

---

3. Common Push Message Structure

3.1 Envelope

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

{
  "type": "TOPIC",
  "topic": "web3_prediction_pm_market_buy_success",
  "data": "{\"pushId\":\"pm_PM2026052812345_pm_market_buy_success_a1b2c3d4\",\"amount\":\"12.34\",\"topic\":\"BTC will hi..\"}"
}

Note: the data field is a stringified JSON — requires a second JSON.parse.

3.2 Common Business Payload Fields

{
  "pushId": "pm_<refId>_<scenarioCode>_<8hex>",
  "<businessField1>": "...",
  "<businessField2>": "..."
}

Field	Type	Required	Description
pushId	string	✅	Unique push ID, present in every topic
Other business fields	string	per-topic	See Section 4; all values are stringified

3.3 pushId Format

pm_<refId>_<scenarioCode>_<8hex>

Example: pm_PM2026052812345_pm_market_buy_success_a1b2c3d4

Segment	Description
pm_	Fixed prefix
<refId>	Business reference ID (orderId / claimBatchId / transferId / marketId, see Section 4)
<scenarioCode>	Scenario code, identical to the topic suffix
<8hex>	8 random hex chars to ensure uniqueness

---

4. Topic List & Detailed Payloads

All 14 topics are prefixed with web3_prediction_. Subscribe as needed.

4.0 Topic Summary

#	scenarioCode	Topic	Trigger
1	pm_market_buy_success	web3_prediction_pm_market_buy_success	Market buy order fully filled
2	pm_market_buy_fail	web3_prediction_pm_market_buy_fail	Market buy order failed / expired
3	pm_market_sell_success	web3_prediction_pm_market_sell_success	Market sell order fully filled
4	pm_market_sell_fail	web3_prediction_pm_market_sell_fail	Market sell order failed / expired
5	pm_limit_submit_success	web3_prediction_pm_limit_submit_success	Limit order submitted successfully
6	pm_limit_submit_fail	web3_prediction_pm_limit_submit_fail	Limit order submission failed
7	pm_limit_order_filled	web3_prediction_pm_limit_order_filled	Limit order fully filled
8	pm_limit_order_partial_fill	web3_prediction_pm_limit_order_partial_fill	Limit order partially filled
9	pm_claim_success	web3_prediction_pm_claim_success	Reward claim succeeded
10	pm_claim_fail	web3_prediction_pm_claim_fail	Reward claim failed
11	pm_claim_partial_success	web3_prediction_pm_claim_partial_success	Batch claim partially succeeded
12	pm_transfer_success	web3_prediction_pm_transfer_success	Fund transfer succeeded
13	pm_transfer_fail	web3_prediction_pm_transfer_fail	Fund transfer failed
14	pm_market_close	web3_prediction_pm_market_close	Market resolution notification

---

4.1 web3_prediction_pm_market_buy_success

Trigger

User's market buy order is fully filled (OrderStatus = FILLED).

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812345_pm_market_buy_success_a1b2c3d4",
  "amount": "12.34",
  "topic": "BTC will hi.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated	Unique ID
amount	string	✅	OrderHistory.amountIn	USDT amount the user paid, truncated to 2 decimals
topic	string	✅	MarketTopic.title truncated to 12 chars	Market title

Copy Template

Bought ${amount} USDT in ${topic}

---

4.2 web3_prediction_pm_market_buy_fail

Trigger

Market buy order transitions to FAILED or EXPIRED.

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812345_pm_market_buy_fail_b2c3d4e5",
  "amount": "12.34",
  "topic": "BTC will hi.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	OrderHistory.amountIn	Original order USDT amount (not actually deducted)
topic	string	✅	Truncated market title

---

4.3 web3_prediction_pm_market_sell_success

Trigger

User's market sell order is fully filled (FILLED).

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812346_pm_market_sell_success_c3d4e5f6",
  "amount": "10.50",
  "topic": "ETH price.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	amountOut − totalFee	USDT actually received (fees deducted)
topic	string	✅	Truncated market title

---

4.4 web3_prediction_pm_market_sell_fail

Trigger

Market sell order transitions to FAILED or EXPIRED.

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812346_pm_market_sell_fail_d4e5f6a7",
  "amount": "10.50",
  "topic": "ETH price.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	amountOut − totalFee	Expected receivable amount before failure (not credited)
topic	string	✅	Truncated market title

---

4.5 web3_prediction_pm_limit_submit_success

Trigger

User's limit order is successfully placed on the order book.

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812347_pm_limit_submit_success_e5f6a7b8",
  "amount": "100.00",
  "topic": "BTC will hi.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	BUY: amountIn / SELL: amountOut	Total limit order amount
topic	string	✅	Truncated market title

---

4.6 web3_prediction_pm_limit_submit_fail

Trigger

Limit order submission rejected at submission time.

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812347_pm_limit_submit_fail_f6a7b8c9",
  "topic": "BTC will hi.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
topic	string	✅	Truncated market title

⚠️ Note: this scenario does not carry the amount field.

Copy Template

Failed to submit your limit order for ${topic}. Please try again.

---

4.7 web3_prediction_pm_limit_order_filled

Trigger

A previously placed limit order is fully filled.

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812347_pm_limit_order_filled_a7b8c9d0",
  "amount": "100.00",
  "topic": "BTC will hi.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	BUY: amountIn / SELL: amountOut − totalFee	USDT amount of the full fill
topic	string	✅	Truncated market title

---

4.8 web3_prediction_pm_limit_order_partial_fill

Trigger

Limit order partially filled (PARTIALLY_FILLED). Each new partial fill triggers a push.

refId

<refId> = OrderHistory.orderId

Payload

{
  "pushId": "pm_PM2026052812347_pm_limit_order_partial_fill_b8c9d0e1",
  "amount": "30.00",
  "topic": "BTC will hi.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	BUY: amountIn / SELL: amountOut − totalFee	Cumulative filled amount after this partial fill, NOT the increment
topic	string	✅	Truncated market title

⚠️ A single limit order may trigger multiple pushes; clients must use pushId for deduplication.

---

4.9 web3_prediction_pm_claim_success

Trigger

A claim fully succeeds (single success or batch all succeed).

refId

<refId> = batchId (claim batch ID)

Payload

{
  "pushId": "pm_CLAIM_BATCH_20260528001_pm_claim_success_c9d0e1f2",
  "amount": "50.00"
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	SUM(dataItems[].amount)	Total claimed USDT

⚠️ This scenario does not include topic / outcome fields (even single-claim shows only the total).

Copy Template

Successfully claimed ${amount} USDT.

---

4.10 web3_prediction_pm_claim_fail

Trigger

Claim entirely fails (single fail or batch all fail).

refId

<refId> = batchId

Payload

{
  "pushId": "pm_CLAIM_BATCH_20260528002_pm_claim_fail_d0e1f2a3",
  "amount": "10.00",
  "outcome": "Yes"
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	dataItems[0].amount	Amount of the first failed claim
outcome	string	✅	dataItems[0].outcome.name	Outcome name (e.g. Yes/No) of the first failed claim; may be ""

⚠️ Even if multiple claims fail in a batch, only the first one's amount/outcome is included.

Copy Template

Failed to claim ${amount} from ${outcome}. Please try again.

---

4.11 web3_prediction_pm_claim_partial_success

Trigger

A batch claim is partially successful (some succeed, some fail).

refId

<refId> = batchId

Payload

{
  "pushId": "pm_CLAIM_BATCH_20260528003_pm_claim_partial_success_e1f2a3b4"
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated

⚠️ This scenario contains only pushId — no business fields. Query REST API for details.

Copy Template

Partially claimed. Please try again to collect the remaining.

---

4.12 web3_prediction_pm_transfer_success

Trigger

Fund transfer succeeds (deposit into prediction wallet / withdraw out).

refId

<refId> = FundTransferOrder.transferId

Payload

{
  "pushId": "pm_TRANSFER_20260528001_pm_transfer_success_f2a3b4c5",
  "amount": "100.00"
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	FundTransferOrder.fromTokenAmount	Token amount transferred

⚠️ Direction (deposit/withdraw) is not distinguished, and token type is not carried (currently USDT only).

---

4.13 web3_prediction_pm_transfer_fail

Trigger

Fund transfer fails.

refId

<refId> = transferId

Payload

{
  "pushId": "pm_TRANSFER_20260528002_pm_transfer_fail_a3b4c5d6",
  "amount": "100.00"
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
amount	string	✅	FundTransferOrder.fromTokenAmount	Original transfer amount

---

4.14 web3_prediction_pm_market_close

Trigger

After a market is resolved (Market.status = RESOLVED), pushed to every user holding any outcome in that market (regardless of win or loss).

refId

<refId> = marketId (note: NOT outcomeId)

Payload

{
  "pushId": "pm_8859231_pm_market_close_b4c5d6e7",
  "topic": "BTC will hi.."
}

Field	Type	Required	Source	Description
pushId	string	✅	System-generated
topic	string	✅	Truncated market title

⚠️ This scenario does not include amount / outcome / isWinner. To display user PnL, query REST API after receiving the push.

Copy Template

Market ${topic} has been resolved. Please claim your winnings.

---

4.15 Field Matrix Quick Reference

Scenario	pushId	amount	topic	outcome	refId Type
pm_market_buy_success	✅	✅	✅	—	orderId
pm_market_buy_fail	✅	✅	✅	—	orderId
pm_market_sell_success	✅	✅	✅	—	orderId
pm_market_sell_fail	✅	✅	✅	—	orderId
pm_limit_submit_success	✅	✅	✅	—	orderId
pm_limit_submit_fail	✅	❌	✅	—	orderId
pm_limit_order_filled	✅	✅	✅	—	orderId
pm_limit_order_partial_fill	✅	✅	✅	—	orderId
pm_claim_success	✅	✅	❌	❌	batchId
pm_claim_fail	✅	✅	❌	✅	batchId
pm_claim_partial_success	✅	❌	❌	❌	batchId
pm_transfer_success	✅	✅	❌	❌	transferId
pm_transfer_fail	✅	✅	❌	❌	transferId
pm_market_close	✅	❌	✅	❌	marketId

---