Howto: UNICORN Binance WebSocket API

by Oliver Zehentleitner

Documentation: API reference


You can install the library with `pip install unicorn-binance-websocket-api` from PyPI or you download the latest release or the current branch via the green "clone or download" button. The easiest way to test the examples is to clone the repository from git with `git clone` to your local system.

How to use the class?

Import the `BinanceWebSocketApiManager` class:

from unicorn_binance_websocket_api.unicorn_binance_websocket_api_manager import BinanceWebSocketApiManager

Additionally we need more imports for this example:

import logging
import time
import os

Configure logging, to get a very verbose mode use DEBUG instead of INFO:

logging.basicConfig(filename=os.path.basename(__file__) + '.log')

Create an instance of the `BinanceWebSocketApiManager`:

binance_websocket_api_manager = BinanceWebSocketApiManager()

Now define the channels and markets you wish to stream. In this example we define a multiplex stream with 3 channels and 5 markets, resulting in 15 different streams (in one multistream - only one connection) Unfortunately you can not receive !miniTicker, !ticker or !userData with the other streams combined. All of this 3 (!miniTicker, !ticker and !userData) must be created as a single websocket stream. If you want all stream types you have to create minimum 4 streams at least. Be also aware, that Binance doesnt allow infinity long URIs, so you can not create one stream with kline_5m, kline_15m, kline_30m, kline_1h, kline_12h and trades for 150 markets in one stream. Binance blocks this and the stream could not establish a connection.

channels = {'trade', 'kline_5m', 'depth5'}
markets = {'bnbbtc', 'ethbtc', 'btcusdt', 'bchabcusdt', 'eosusdt'}

Then create and start the multiplex stream:

multi_stream_id = binance_websocket_api_manager.create_stream(channels, markets)

And create a `!userData` stream:

binance_websocket_api_manager.set_private_api_config(binance_api_key, binance_api_secret)
user_data_stream_id = binance_websocket_api_manager.create_stream('arr', '!userData')

And a `!ticker` and `!miniTicker` stream:

ticker_stream_id = binance_websocket_api_manager.create_stream(["arr"], ["!miniTicker"])
miniticker_stream_id = binance_websocket_api_manager.create_stream(["arr"], ["!ticker"])

To watch what your streams are doing use:

while True:

Now your streams should be running, and everything happening with the received data is, its stored in the stream_buffer. To get and remove the oldest entry from the stream_buffer stack do:

oldest_stream_data_from_stream_buffer = binance_websocket_api_manager.pop_stream_data_from_stream_buffer()

Then you can do with it what every you want. If your database is down for a restart or anything else, you can kick the data back to the stream_buffer with:


An other way to process the received data is, to provide an own process_streams class (use this template to start) when creating the manager instance, so instead of writing the raw_stream_data to the stream_buffer, each receive will directly trigger the function/method you provided:

from unicorn_binance_websocket_api_process_streams import BinanceWebSocketApiProcessStreams
binance_websocket_api_manager = BinanceWebSocketApiManager(BinanceWebSocketApiProcessStreams.process_stream_data)

The process_streams template is only printing the data, so you have to extend the file `` and replace "print" with your business logic.

If you would like to unify the received data with UnicornFy, please follow this guide.

Here are some working example files (just clone the repository and run them):

UNICORN Binance WebSocket API Demo

Go back

Add a comment

Please add 3 and 7.