Key Takeaways
The Binance Spot WebSocket Stream allows users to access real-time market data for programmatic spot trading.
Users can subscribe to multiple streams and combine them for a more comprehensive data feed.
User-specific data streams are not available through WebSocket Streams.
Introduction
Binance provides different types of information across various markets, such as Spot, Futures, Margin, and Options. To access these, users can choose from different API types, including REST APIs, WebSocket APIs, and WebSocket Streams. For users who are not yet ready to trade but want to monitor and learn from market data, WebSocket Streams offer real-time information.
While Websocket Streams are convenient, setting them up can be burdensome as they require technical knowledge and attention to important details.
This article will guide you through the process of using a Binance Spot WebSocket Stream, including setup instructions, the types of responses received, and an example. Most of the information in this article is based on the official Binance API documentation.
How to Configure a Binance Spot WebSocket Stream?
Unlike REST APIs, a WebSocket stream enables two-way communication between the client and server. The client must first establish a connection with the server, a process known as the handshake. The connection is made by sending a request to a specific base endpoint.
Base endpoints
Similar to REST API’s base URL, a base endpoint in WebSocket streams serves as the main point for accessing resources on a web server or API. However, unlike REST APIs, the WebSocket base endpoint begins with ’ws’ or ’wss’ to distinguish WebSocket connections from regular HTTP connections, with ’wss’ being used for secure WebSocket connections.
Binance WebSocket stream offers the following base endpoints:
wss://stream.binance.com:9443: The general base URL for all available functionalities of the Spot WebSocket stream.
wss://stream.binance.com:443: An alternative base URL that can be used if users encounter issues with the first one.
wss://data-stream.binance.vision: A base URL used to receive only market data messages.
Streams
Once the base endpoint is selected, the client must choose which streams to follow. Streams can be accessed in two ways:
Raw Streams: A client can connect to a single raw stream by adding the stream name after the endpoint ‘ws’ (e.g.: /ws/<streamName>).
Combined Streams: Multiple streams can be combined in a single request. The endpoint ‘/stream’ should be followed by the list of stream names, formatted as streams=<streamName1>/<streamName2>/<streamName3>.
Note that stream names should be written in lowercase. Depending on the stream, additional parameters may be required. Documentation will indicate where to place these parameters in the stream endpoint. Moreover, Binance provides only market data streams, with no user-specific data streams available.
Once the client has chosen the base endpoint and streams, they can send a request to initiate the handshake with the server. If the connection is successful, it will remain active until the client decides to close it or 24 hours have passed. The connection may also be closed if the client fails to send a message every 3 minutes to keep it alive.
Managing subscriptions
After establishing a connection, the client can subscribe to streams by sending a request to the server with the following keys:
Id: A unique identifier for messages between the client and server. The Id can be a string of alphanumeric characters (up to 36 characters) or a 64-bit signed integer. The client can also send a null value for the Id.
Params: Specifies which streams the client wants to subscribe to or whether to set the stream property to "combined".
Method: Tells the server whether the client wants to subscribe, unsubscribe, set the "combined" property, check the status of the property, or retrieve the list of subscribed streams.
Interpreting The WebSocket Stream Response
Once the client sends a request, the server responds with the following information:
Id: The server returns the same Id that the client sent.
Result: The result can either be a null value (indicating a successful request for non-query requests, e.g., subscribing/unsubscribing) or a value corresponding to the requested type (e.g., a boolean for setting the "combined" property or a list of subscribed streams).
Example response for a request to list subscribed streams:
{
"result": [
"btcusdt@aggTrade"
],
"id": 3
}Practical WebSocket Stream Example
Various tools are available for clients to interact with the Binance WebSocket stream. One such tool is the connector provided by Binance.
The client must first initiate a connection request with the server before subscribing to a stream.
Connection to a stream server
Python Snippet:
Import logging
import time
from binance.websocket.spot.websocket_stream import SpotWebsocketStreamClient
def message_handler(_, message):
logging.info(message)
my_client = SpotWebsocketStreamClient(on_message=message_handler, is_combined=True)In this example, the client sets up a connection with the server by requesting the combined parameter to be true.
Once the connection is established, the user can request their desired stream for subscription.
Subscribe to an Aggregate trade Stream on BNBUSDT
Python Snippet:
# Subscribe to a single symbol stream
my_client.agg_trade(symbol="bnbusdt")This request subscribes to the aggTrade stream, which returns the aggregate trades for a specific symbol. In this case, the symbol is BNBUSDT. The request will look as follows:
{
Method: “SUBSCRIBE”,
Params: [“bnbusdt@aggTrade”],
Id: 1
}The server will first send a confirmation response:
{
"result": null,
"id": 1
}Afterward, the server will continuously return aggregate trade data in real time:
{
"e": "aggTrade", // Event type
"E": 1672515782136, // Event time
"s": "BNBUSDT", // Symbol
"a": 12345, // Aggregate trade ID
"p": "0.001", // Price
"q": "100", // Quantity
"f": 100, // First trade ID
"l": 105, // Last trade ID
"T": 1672515782136, // Trade time
"m": true, // Is the buyer the market maker?
"M": true // Ignore
}Closing the connection
When the user is done, they can close the connection with the command shown below.
Python Snippet:
my_client.stop()Closing Thoughts
The Binance WebSocket Stream is a powerful tool for retrieving market data in real time. Understanding how to properly construct WebSocket Stream requests and interpret the resulting JSON responses is essential for efficient use and secure interactions with the platform. Although the initial setup might seem complex, following a structured approach can simplify the process, allowing users to fully leverage Binance's Spot Trading capabilities.
Further Reading
Disclaimer: This content is presented to you on an “as is” basis for general information and educational purposes only, without representation or warranty of any kind. It should not be construed as financial, legal or other professional advice, nor is it intended to recommend the purchase of any specific product or service. You should seek your own advice from appropriate professional advisors. Where the article is contributed by a third party contributor, please note that those views expressed belong to the third party contributor, and do not necessarily reflect those of Binance Academy. Please read our full disclaimer here for further details. Digital asset prices can be volatile. The value of your investment may go down or up and you may not get back the amount invested. You are solely responsible for your investment decisions and Binance Academy is not liable for any losses you may incur. This material should not be construed as financial, legal or other professional advice. For more information, see our Terms of Use and Risk Warning.