websockets.rst

Websockets

Sockets are handled through a Socket Manager BinanceSocketManager.

Multiple socket connections can be made through the manager.

Only one instance of each socket type will be created, i.e. only one BNBBTC Depth socket can be created and there can be both a BNBBTC Depth and a BNBBTC Trade socket open at once.

When creating socket connections a callback function is passed which receives the messages.

Messages are received as dictionary objects relating to the message formats defined in the Binance WebSocket API documentation.

Websockets are setup to reconnect with a maximum of 5 retries.

Websocket Usage

Create the manager like so, passing the API client.

from binance.websockets import BinanceSocketManager
bm = BinanceSocketManager(client)
# start any sockets here, i.e a trade socket
conn_key = bm.start_trade_socket('BNBBTC', process_message)
# then start the socket manager
bm.start()

A callback to process messages would take the format

def process_message(msg):
    print("message type: {}".format(msg['e']))
    print(msg)
    # do something

Set a custom timeout for the websocket connection

# set a timeout of 60 seconds
bm = BinanceSocketManager(client, user_timeout=60)

Websocket Errors

If the websocket is disconnected and is unable to reconnect a message is sent to the callback to indicate this. The format is

{
    'e': 'error',
    'm': 'Max reconnect retries reached'
}

# check for it like so
def process_message(msg):
    if msg['e'] == 'error':
        # close and restart the socket
    else:
        # process message normally

Multiplex Socket

Create a socket combining multiple streams.

These streams can include the depth, kline, ticker and trade streams but not the user stream which requires extra authentication.

Symbols in socket name must be lowercase i.e bnbbtc@aggTrade, neobtc@ticker

See the Binance Websocket Streams API documentation for details on socket names.

def process_m_message(msg):
    print("stream: {} data: {}".format(msg['stream'], msg['data']))

# pass a list of stream names
conn_key = bm.start_multiplex_socket(['bnbbtc@aggTrade', 'neobtc@ticker'], process_m_message)

Depth Socket

Depth sockets have an optional depth parameter to receive partial book rather than a diff response. By default this the diff response is returned. Valid depth values are 5, 10 and 20 and defined as enums.

# depth diff response
diff_key = bm.start_depth_socket('BNBBTC', process_message)

# partial book response
partial_key = bm.start_depth_socket('BNBBTC', process_message, depth=BinanceSocketManager.WEBSOCKET_DEPTH_5)

Kline Socket

Kline sockets have an optional interval parameter. By default this is set to 1 minute. Valid interval values are defined as enums.

from binance.enums import *
conn_key = bm.start_kline_socket('BNBBTC', process_message, interval=KLINE_INTERVAL_30MINUTE)

Aggregated Trade Socket

conn_key = bm.start_aggtrade_socket('BNBBTC', process_message)

Trade Socket

conn_key = bm.start_trade_socket('BNBBTC', process_message)

Symbol Ticker Socket

conn_key = bm.start_symbol_ticker_socket('BNBBTC', process_message)

Ticker Socket

conn_key = bm.start_ticker_socket(process_message)

Mini Ticker Socket

# by default updates every second
conn_key = bm.start_miniticker_socket(process_message)

# this socket can take an update interval parameter
# set as 5000 to receive updates every 5 seconds
conn_key = bm.start_miniticker_socket(process_message, 5000)

User Socket

This watches for 3 different user events

• Account Update Event
• Order Update Event
• Trade Update Event

The Manager handles keeping the socket alive.

bm.start_user_socket(process_message)

Close a Socket

To close an individual socket call the stop_socket function. This takes a conn_key parameter which is returned when starting the socket.

bm.stop_socket(conn_key)

To stop all sockets and end the manager call close after doing this a start call would be required to connect any new sockets.

bm.close()

Close and exit program

Websockets utilise a reactor loop from the Twisted library. Using the close method above will close the websocket connections but it won't stop the reactor loop so your code may not exit when you expect.

If you do want to exit then use the stop method from reactor like below.

from twisted.internet import reactor

# program code here

# when you need to exit
reactor.stop()