Web Socket Streams for Binance (2023-12-04)
General WSS information
- The base endpoint is: wss://stream.binance.com:9443 or wss://stream.binance.com:443
- Streams can be accessed either in a single raw stream or in a combined stream
- Raw streams are accessed at /ws/\<streamName>
- Combined streams are accessed at /stream?streams=\<streamName1>/\<streamName2>/\<streamName3>
- Combined stream events are wrapped as follows: {"stream":"\<streamName>","data":\<rawPayload>}
- All symbols for streams are lowercase
- A single connection to stream.binance.com is only valid for 24 hours; expect to be disconnected at the 24 hour mark
- Websocket server will send a
ping frame
every 3 minutes.- If the websocket server does not receive a
pong frame
back from the connection within a 10 minute period, the connection will be disconnected. - When you receive a ping, you must send a pong with a copy of ping's payload as soon as possible.
- Unsolicited
pong frames
are allowed, but will not prevent disconnection. It is recommended that the payload for these pong frames are empty.
- If the websocket server does not receive a
- The base endpoint wss://data-stream.binance.vision can be subscribed to receive only market data messages.
User data stream is NOT available from this URL.
#
Websocket Limits- WebSocket connections have a limit of 5 incoming messages per second. A message is considered:
- A PING frame
- A PONG frame
- A JSON controlled message (e.g. subscribe, unsubscribe)
- A connection that goes beyond the limit will be disconnected; IPs that are repeatedly disconnected may be banned.
- A single connection can listen to a maximum of 1024 streams.
- There is a limit of 300 connections per attempt every 5 minutes per IP.
#
Live Subscribing/Unsubscribing to streams- The following data can be sent through the websocket instance in order to subscribe/unsubscribe from streams. Examples can be seen below.
- The
id
is used as an identifier to uniquely identify the messages going back and forth. The following formats are accepted:- 64-bit signed integer
- alphanumeric strings; max length 36
null
- In the response, if the
result
received isnull
this means the request sent was a success for non-query requests (e.g. Subscribing/Unsubscribing).
#
Subscribe to a streamRequest
Response
#
Unsubscribe to a streamRequest
Response
#
Listing SubscriptionsRequest
Response
#
Setting PropertiesCurrently, the only property that can be set is whether combined
stream payloads are enabled or not.
The combined property is set to false
when connecting using /ws/
("raw streams") and true
when connecting using /stream/
.
Request
Response
#
Retrieving PropertiesRequest
Response
#
Error MessagesError Message | Description |
---|---|
{"code": 0, "msg": "Unknown property","id": %s} | Parameter used in the SET_PROPERTY or GET_PROPERTY was invalid |
{"code": 1, "msg": "Invalid value type: expected Boolean"} | Value should only be true or false |
{"code": 2, "msg": "Invalid request: property name must be a string"} | Property name provided was invalid |
{"code": 2, "msg": "Invalid request: request ID must be an unsigned integer"} | Parameter id had to be provided or the value provided in the id parameter is an unsupported type |
{"code": 2, "msg": "Invalid request: unknown variant %s, expected one of SUBSCRIBE , UNSUBSCRIBE , LIST_SUBSCRIPTIONS , SET_PROPERTY , GET_PROPERTY at line 1 column 28"} | Possible typo in the provided method or provided method was neither of the expected values |
{"code": 2, "msg": "Invalid request: too many parameters"} | Unnecessary parameters provided in the data |
{"code": 2, "msg": "Invalid request: property name must be a string"} | Property name was not provided |
{"code": 2, "msg": "Invalid request: missing field method at line 1 column 73"} | method was not provided in the data |
{"code":3,"msg":"Invalid JSON: expected value at line %s column %s"} | JSON data sent has incorrect syntax. |
Detailed Stream information
#
Aggregate Trade StreamsThe Aggregate Trade Streams push trade information that is aggregated for a single taker order.
Stream Name: \<symbol>@aggTrade
Update Speed: Real-time
Payload:
#
Trade StreamsThe Trade Streams push raw trade information; each trade has a unique buyer and seller.
Stream Name: \<symbol>@trade
Update Speed: Real-time
Payload:
#
Kline/Candlestick StreamsThe Kline/Candlestick Stream push updates to the current klines/candlestick every second.
Kline/Candlestick chart intervals:
s-> seconds; m -> minutes; h -> hours; d -> days; w -> weeks; M -> months
- 1s
- 1m
- 3m
- 5m
- 15m
- 30m
- 1h
- 2h
- 4h
- 6h
- 8h
- 12h
- 1d
- 3d
- 1w
- 1M
Stream Name: \<symbol>@kline_\<interval>
Update Speed: 1000ms for 1s
, 2000ms for the other intervals
Payload:
#
Individual Symbol Mini Ticker Stream24hr rolling window mini-ticker statistics. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs.
Stream Name: \<symbol>@miniTicker
Update Speed: 1000ms
Payload:
#
All Market Mini Tickers Stream24hr rolling window mini-ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.
Stream Name: !miniTicker@arr
Update Speed: 1000ms
Payload:
#
Individual Symbol Ticker Streams24hr rolling window ticker statistics for a single symbol. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs.
Stream Name: \<symbol>@ticker
Update Speed: 1000ms
Payload:
#
All Market Tickers Stream24hr rolling window ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.
Stream Name: !ticker@arr
Update Speed: 1000ms
Payload:
#
Individual Symbol Rolling Window Statistics StreamsRolling window ticker statistics for a single symbol, computed over multiple windows.
Stream Name: \<symbol>@ticker_\<window_size>
Window Sizes: 1h,4h,1d
Update Speed: 1000ms
Note: This stream is different from the \<symbol>@ticker stream.
The open time "O"
always starts on a minute, while the closing time "C"
is the current time of the update.
As such, the effective window might be up to 59999ms wider that \<window_size>.
Payload:
#
All Market Rolling Window Statistics StreamsRolling window ticker statistics for all market symbols, computed over multiple windows. Note that only tickers that have changed will be present in the array.
Stream Name: !ticker_\<window-size>@arr
Window Size: 1h,4h,1d
Update Speed: 1000ms
Payload:
#
Individual Symbol Book Ticker StreamsPushes any update to the best bid or ask's price or quantity in real-time for a specified symbol.
Multiple <symbol>@bookTicker
streams can be subscribed to over one connection.
Stream Name: \<symbol>@bookTicker
Update Speed: Real-time
Payload:
#
Average PriceAverage price streams push changes in the average price over a fixed time interval.
Stream Name: \<symbol>@avgPrice
Update Speed: 1000ms
Payload:
#
Partial Book Depth StreamsTop \<levels> bids and asks, pushed every second. Valid \<levels> are 5, 10, or 20.
Stream Names: \<symbol>@depth\<levels> OR \<symbol>@depth\<levels>@100ms
Update Speed: 1000ms or 100ms
Payload:
#
Diff. Depth StreamOrder book price and quantity depth updates used to locally manage an order book.
Stream Name: \<symbol>@depth OR \<symbol>@depth@100ms
Update Speed: 1000ms or 100ms
Payload:
#
How to manage a local order book correctly- Open a stream to wss://stream.binance.com:9443/ws/bnbbtc@depth.
- Buffer the events you receive from the stream.
- Get a depth snapshot from https://api.binance.com/api/v3/depth?symbol=BNBBTC&limit=1000 .
- Drop any event where
u
is <=lastUpdateId
in the snapshot. - The first processed event should have
U
<=lastUpdateId
+1 ANDu
>=lastUpdateId
+1. - While listening to the stream, each new event's
U
should be equal to the previous event'su
+1. - The data in each event is the absolute quantity for a price level.
- If the quantity is 0, remove the price level.
- Receiving an event that removes a price level that is not in your local order book can happen and is normal.
Note: Due to depth snapshots having a limit on the number of price levels, a price level outside of the initial snapshot that doesn't have a quantity change won't have an update in the Diff. Depth Stream. Consequently, those price levels will not be visible in the local order book even when applying all updates from the Diff. Depth Stream correctly and cause the local order book to have some slight differences with the real order book. However, for most use cases the depth limit of 5000 is enough to understand the market and trade effectively.