UNICORN Binance WebSocket API

A python API to use the Binance Websocket API in a easy, fast, flexible, robust and fully-featured way.

The python module UNICORN Binance WebSocket API provides an API to the Binance Websocket API, which supports the streaming of public streams like trade, kline, ticker and depth, but also the private userData stream which need to be used with a valid api_key and api_secret from the Binance Exchange.

The module requires python 3.5.3 or above, as it depends on pythons latest asyncio features for asynchronous/concurrent processing. The current dependencies are listed here.

Be aware that the Binance websocket API just offers to receive data. If you would like to set orders, withdraws and so on, you have to use the Binance Rest API in combination.

Why to use the UNICORN Binance WebSocket API?

  • 100% auto-reconnect.
  • Streams are processing asynchronous/concurrent (python asyncio) and each stream is started in a separate thread.
  • No use of the twisted module, so you can use this lib in a daemonized application (compatible with python-daemon).
  • If you can not store your data on an offline local database, you can kick back the data to the stream_buffer which stores the receives in the RAM till you are able to process the data in the normal way again.
  • Helpful management features like get_binance_api_status(), get_stream_info(), get_stream_list(), get_stream_statistic(), is_websocket_uri_length_valid(), replace_stream(), wait_till_stream_has_started() and many more.

Read the Howto: UNICORN Binance WebSocket API for installation instructions and a guide on how to use it.

UNICORN Binance WebSocket API is available on PyPI: https://pypi.org/project/unicorn-binance-websocket-api/

So you can make the package available on your system with `pip install unicorn-binance-websocket-api`!

 

UNICORN Binance WebSocket API documentation

class unicorn_binance_websocket_api_manager.BinanceWebSocketApiManager(process_stream_data=False)

A python API to handle the Binance websocket API

Binance websocket API documentation:
https://github.com/binance-exchange/binance-official-api-docs/blob/master/web-socket-streams.md
https://github.com/binance-exchange/binance-official-api-docs/blob/master/user-data-stream.md

Parameters

process_stream_data (function) – Provide a function/method to process the received webstream data. The function will be called with one variable like `process_stream_data(data)` where data` cointains the raw_stream_data. If not provided, the raw_stream_data will get stored in the stream_buffer.

add_to_stream_buffer(stream_data)

Kick back data to the stream_buffer

If it is not possible to process received stream data (for example, the database is restarting, so its not possible to save the data), you can return the data back into the stream_buffer. After a few seconds you stopped writing data back to the stream_buffer, the BinanceWebSocketApiManager starts flushing back the data to normal processing.

Parameters

stream_data (raw stream_data or unicorn_fied stream data) – the data you want to write back to the buffer

create_stream(channels, markets)

Create a websocket stream

Parameters
  • channels (str or tuple) – provide the channels you wish to stream

  • markets (str or tuple) – provide the markets you wish to stream

channel "trade" with `markets = {'bnbbtc', 'ethbtc', 'btcusdt'}`
channel "aggTrade" with `markets = {'bnbbtc', 'ethbtc', 'btcusdt'}`
channel "kline_<interval>" (1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M)
with `markets = {'bnbbtc', 'ethbtc', 'btcusdt'}`
channel "miniTicker" with `markets = {'bnbbtc', 'ethbtc', 'btcusdt'}`
channel "ticker" with `markets = {'bnbbtc', 'ethbtc', 'btcusdt'}`
channel "depth<level>" (5, 10, 20) with `markets = {'bnbbtc', 'ethbtc', 'btcusdt'}`
channel "depth" with `markets = {'bnbbtc', 'ethbtc', 'btcusdt'}`
channel "arr" with `"!ticker"`or "!miniTicker" or "!userData"
Returns

stream_id

create_websocket_uri(channels, markets, stream_id, api_key, api_secret)

Create a websocket URI

Parameters
  • channels (str or tuple) – provide the channels to create the URI

  • markets (str or tuple) – provide the channels to create the URI

  • stream_id (uuid) – provide a stream_id (only needed for userData Streams (acquiring a listenKey)

  • api_key (str) – provide a valid Binance API key

  • api_secret (str) – provide a valid Binance API secret

Returns

str

delete_listen_key_by_stream_id(stream_id)

Delete a binance listen_key from a specific !userData stream

Parameters

stream_id (uuid) – id of a !userData stream

delete_stream_from_stream_list(stream_id)

Delete a stream from the stream_list

Even if a stream crashes or gets stopped, its data remains in the BinanceWebSocketApiManager till you stop the BinanceWebSocketApiManager itself. If you want to tidy up the stream_list you can use this method.

Parameters

stream_id (uuid) – id of a stream

Returns

bool

get_active_stream_list()

Get a list of all active streams

Returns

set

get_all_receives_last_second()

Get the number of all receives of the last second

Returns

int

get_binance_api_status()

Get used_weight, last status_code and the timestamp of the last status update

Returns

dict

get_keep_max_received_last_second_entries()

Get the number of received_last_second entries are stored till they get deleted

Returns

int

get_latest_version()

Get the version of the latest available release

Returns

str or False

get_listen_key_from_restclient(stream_id, api_key, api_secret)

Get a new or cached (<30m) listen_key

Parameters
  • stream_id (uuid) – provide a stream_id

  • api_key (str) – provide a valid Binance API key

  • api_secret (str) – provide a valid Binance API secret

Returns

str or False

get_most_receives_per_second()

Get the highest total receives per second value

Returns

int

get_number_of_streams_in_stream_list()

Get the number of streams that are stored in the stream_list

Returns

int

get_reconnects()

Get the number of total reconnects

Returns

int

get_start_time()

Get the start_time of the BinanceWebSocketApiManager instance

Returns

timestamp

get_stream_buffer_byte_size()

Get the current byte size of the stream_buffer

Returns

int

get_stream_info(stream_id)

Get infos about a specific stream

Parameters

stream_id (uuid) – id of a stream

Returns

set

get_stream_list()

Get a list of all streams

Returns

set

get_stream_receives_last_second(stream_id)

Get the number of receives of specific stream from the last seconds

Parameters

stream_id (uuid) – id of a stream

Returns

int

get_stream_statistic(stream_id)

Get the statistic of a specific stream

Parameters

stream_id (uuid) – id of a stream

Returns

set

get_total_received_bytes()

Get number of total received bytes

Returns

int

get_total_receives()

Get the number of total receives

Returns

int

get_version()

Get the package/module version

Returns

str

get_websocket_uri_length(channels, markets)

Get the length of the generated websocket URI

  • channels (str or tuple) – provide the channels to create the URI

  • markets (str or tuple) – provide the channels to create the URI

Returns

int

is_stop_request(stream_id)

Has a specific stream a stop_request?

Parameters

stream_id (uuid) – id of a stream

Returns

bool

is_update_availabe()

Is a new release of this package available?

Returns

bool

is_websocket_uri_length_valid()

Is the websocket URI length valid?

Returns

bool

pop_stream_data_from_stream_buffer()

Get oldest entry from stream_buffer and remove from stack (FIFO stack)

Returns

raw_stream_data (set) or False

print_stream_info(stream_id)

Print all infos about a specific stream, helps debugging :)

Parameters

stream_id (uuid) – id of a stream

Returns

print_summary()

Print an overview of all streams

Returns

replace_stream(stream_id, new_channels, new_markets)

Replace a stream

If you want to start a stream with a new config, it is recommended to first start a new stream with the new settings and close the old stream not before the new stream received its first data. So your data will stay consistent.

Parameters
  • stream_id (uuid) – id of the old stream

  • new_channels (str or tuple) – the new channel list for the stream

  • new_markets (str or tuple) – the new markets list for the stream

Returns

new stream_id

restart_stream(stream_id)

Restart a specific stream

Parameters

stream_id (uuid) – id of a stream

Returns

stream_id

set_private_api_config(binance_api_key, binance_api_secret)

Set binance_api_key and binance_api_secret

This settings are needed to acquire a listenKey from Binance to establish a userData stream

Parameters
  • binance_api_key (str) – The Binance API key

  • binance_api_secret (str) – The Binance API secret

stop_manager_with_all_streams()

Stop the BinanceWebSocketApiManager with all streams and management threads

stop_stream(stream_id)

Stop a specific stream

Parameters

stream_id (uuid) – id of a stream

Returns

bool

wait_till_stream_has_started(stream_id)

Returns True as soon a specific stream has started

Parameters

stream_id (uuid) – id of a stream

Returns

True

wait_till_stream_has_stopped(stream_id)

Returns True as soon a specific stream has stopped itself

Parameters

stream_id (uuid) – id of a stream

Returns

True