WebSocket Streams — General Info
Option order updates are pushed over the stock user data stream. Option orders are pushed on
<listenKey>@orderReportV2, not on <listenKey>@orderReport.
Base URL
| Environment | Base URL |
|---|---|
| Production | wss://nbstream.binance.com/equity |
Listen Key
Obtain a listenKey via
Create / Renew Listen Key.
- Valid for 1 hour. Calling the endpoint again renews it and returns the same key; renewing every 30 minutes is recommended. After expiry a new key is issued and you must resubscribe with it.
- Options and stocks share one key.
/sapi/v1/equity/option/listenKeyand/sapi/v1/equity/listenKeyreturn the same key.
Connecting
| Mode | URL |
|---|---|
| Single stream | wss://nbstream.binance.com/equity/ws/<listenKey>@orderReportV2 |
| Combined stream | wss://nbstream.binance.com/equity/stream?streams=<listenKey>@orderReportV2 |
You can also connect to wss://nbstream.binance.com/equity/stream and then subscribe:
Request
Code
Response
Code
On a single stream, each message is the event itself. On a combined stream, the event is wrapped as
{"stream": "<listenKey>@orderReportV2", "data": {...}}.
Choosing a Stream
| Stream | Content |
|---|---|
<listenKey>@orderReportV2 | US stocks and US stock options, told apart by ac |
<listenKey>@orderReport | US stocks only, no options, and no ac field |
To process option orders only, subscribe to orderReportV2 and handle events where ac =
us_option.
ac | Asset class |
|---|---|
us_option | US stock options |
us_equity | US stocks |
When Events Are Pushed
x | When | Possible s |
|---|---|---|
ORDER_UPDATE | The order is open (new, accepted by the broker, partially filled, cancel pending, etc.) | new / pending_new / accepted / partially_filled / pending_cancel / pending_replace |
ORDER_TERMINAL | The order reached a terminal state; it will not be pushed again | filled / canceled / expired / rejected / replaced |
- Pushes are best-effort and not guaranteed: a failed push is not retried; the terminal state of
an order is pushed only once; events during a period when the
listenKeyis invalid are not replayed; an order never pushed in an open state (e.g. rejected immediately) may not get a terminal push. After reconnecting, call Current Open Option Orders for a full snapshot, then apply pushes as increments. - Nothing is pushed when nothing changes (e.g. for queries).
- Fill-level details (price of each fill) are not pushed; use Option Order Detail or Option Trade History.
Example (ac = us_option)
A buy-to-open limit order accepted by the broker:
Code
When the same order is canceled, x = ORDER_TERMINAL and s = canceled; other fields keep the
same meaning. See
Order Report V2 Stream
for every field.
Differences from REST
The stream is shared with the Binance App, and its format takes precedence:
- Keys are abbreviated. The field reference maps each key to its REST field.
- Enum values are lowercase (
buy,limit,accepted,buy_to_open); REST uses uppercase. Compare case-insensitively. - Numbers are JSON numbers, not strings, with a variable number of decimals (trailing zeros possible). Parse them with a decimal type; do not compare them as floating point.
- Empty fields are kept as
null, not omitted. Stock and option events have the same set of keys; fields that do not apply are pushed asnull. - Expiration-day auto-liquidation orders by the broker (
o=market) may havenullinp,b,q,tc,u,ct,spanded; get the contract details by calling Option Exchange Info withos.
Connection Lifecycle
If the listenKey expires, the stream stops pushing. Renew it before its 1-hour validity ends, and
after reconnecting, call Current Open Option Orders for a full snapshot before applying pushes.