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.

.. code:: python

    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

.. code:: python

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


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

.. code:: python

    {
        '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.

.. code:: python

    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 `_.

.. code:: python

    # 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 `_.

.. code:: python

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


`Aggregated Trade Socket `_
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. code:: python

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


`Trade Socket `_
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. code:: python

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

`Symbol Ticker Socket `_
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. code:: python

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

`Ticker Socket `_
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. code:: python

    conn_key = bm.start_ticker_socket(process_message)

`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.

.. code:: python

    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.

.. code:: python

    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.

.. code:: python

    bm.close()

.. image:: https://analytics-pixel.appspot.com/UA-111417213-1/github/python-binance/docs/websockets?pixel


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.

.. code:: python

    from twisted.internet import reactor

    # program code here

    # when you need to exit
    reactor.stop()