python-binance Documentation

For asyncio based applications, use DepthCacheManager (or OptionsDepthCacheManager for vanilla options).

Usage Pattern:

• Pass an existing AsyncClient and a symbol to the constructor.
• Use the async with context manager pattern to handle the lifecycle.
• Retrieve updates using await dcm_socket.recv().

Configuration:

• refresh_interval: Controls how often the order book is fetched via REST to stay synced. Default is 30 minutes. Set to 0 or None to disable refreshing.

import asyncio
from binance import AsyncClient, DepthCacheManager

async def main():
    client = await AsyncClient.create()
    dcm = DepthCacheManager(client, 'BNBBTC')

    async with dcm as dcm_socket:
        while True:
            depth_cache = await dcm_socket.recv()
            print("symbol {}".format(depth_cache.symbol))
            print("top 5 bids")
            print(depth_cache.get_bids()[:5])
            print("top 5 asks")
            print(depth_cache.get_asks()[:5])
            print("last update time {}".format(depth_cache.update_time))

if __name__ == "__main__":
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())

The BinanceSocketManager is designed for asyncio environments.

Usage Pattern:

1. Create an AsyncClient.
2. Pass the client to BinanceSocketManager(client).
3. Create a socket (e.g., bm.trade_socket('SYMBOL')).
4. Use an async with context manager to receive messages via await tscm.recv().

Options:

• Timeout: You can set a custom timeout for connections using the user_timeout parameter: BinanceSocketManager(client, user_timeout=60).
• Manual Context: You can manually enter/exit the context using await ts.__aenter__() and await ts.__aexit__(None, None, None).

import asyncio
from binance import AsyncClient, BinanceSocketManager


async def main():
    client = await AsyncClient.create()
    bm = BinanceSocketManager(client)
    # start any sockets here, i.e a trade socket
    ts = bm.trade_socket('BNBBTC')
    # then start receiving messages
    async with ts as tscm:
        while True:
            res = await tscm.recv()
            print(res)

    await client.close_connection()

if __name__ == "__main__":
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())

Verbose mode provides detailed logging of all HTTP requests and responses (method, URL, headers, body, and status codes). This is recommended for quick debugging but should be disabled in production to minimize overhead.

Using the verbose parameter (Quick Debugging)

Pass verbose=True when initializing the Client or AsyncClient.

Using the Logging Module (Recommended for Production)

For fine-grained control in production, use the standard logging module to set the level for binance.base_client specifically.

# Method 1: Using the verbose parameter (Quick Debugging)
from binance.client import Client
import logging

logging.basicConfig(level=logging.DEBUG)
client = Client(api_key, api_secret, verbose=True)
server_time = client.get_server_time()

# For AsyncClient
import asyncio
from binance.async_client import AsyncClient

async def main():
    client = await AsyncClient.create(api_key, api_secret, verbose=True)
    server_time = await client.get_server_time()
    await client.close_connection()

if __name__ == "__main__":
    asyncio.run(main())

# Method 2: Using Python's Logging Module (Recommended for Production)
import logging
from binance.client import Client

logging.basicConfig(
    level=logging.INFO, 
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
# Enable debug logging for binance specifically
logging.getLogger('binance.base_client').setLevel(logging.DEBUG)

client = Client(api_key, api_secret)

The ThreadedWebsocketManager is used for streaming data without requiring asyncio programming.

Key Requirements:

• Initialization: You must call .start() to initialize the internal loop before starting any sockets.
• Callbacks: Every socket start method (e.g., start_ticker_socket) requires a callback function to handle incoming messages.
• Authentication: For authenticated streams, provide api_key and api_secret during instantiation.
• Persistence: Use .join() to keep the manager running in the main thread.
• Termination: Use .stop_socket(stream_name) to stop a specific stream or .stop() to stop all streams.

Socket Types:

• Individual sockets: start_kline_socket, start_depth_socket, etc.
• Multiplex sockets: start_multiplex_socket(callback=..., streams=['stream1', 'stream2']).

import time
from binance import ThreadedWebsocketManager

api_key = '<api_key>'
api_secret = '<api_secret>'

def main():
    symbol = 'BNBBTC'

    twm = ThreadedWebsocketManager(api_key=api_key, api_secret=api_secret)
    # start is required to initialise its internal loop
    twm.start()

    def handle_socket_message(msg):
        print(f"message type: {msg['e']}")
        print(msg)

    twm.start_kline_socket(callback=handle_socket_message, symbol=symbol)

    # multiple sockets can be started
    twm.start_depth_socket(callback=handle_socket_message, symbol=symbol)

    # or a multiplex socket can be started like this
    # see Binance docs for stream names
    streams = ['bnbbtc@miniTicker', 'bnbbtc@bookTicker']
    twm.start_multiplex_socket(callback=handle_socket_message, streams=streams)

    twm.join()

if __name__ == "__main__":
   main()

WebSocket connections support verbose mode to log raw received messages, connection state changes, reconnection attempts, and subscription events.

Using the verbose parameter

Pass verbose=True when creating the BinanceSocketManager.

Using the Logging Module

Set the log level for binance.ws or specific sub-components.

Sub-components for granular logging:

• binance.ws.websocket_api: Log only WebSocket API messages
• binance.ws.reconnecting_websocket: Log reconnection events
• binance.ws.streams: Log stream events

import logging
import asyncio
from binance import AsyncClient, BinanceSocketManager

# Method 1: Using the verbose parameter
logging.basicConfig(level=logging.DEBUG)

async def main():
    client = await AsyncClient.create()
    # Enable verbose mode for WebSocket connections
    bm = BinanceSocketManager(client, verbose=True)

    ts = bm.trade_socket('BTCUSDT')
    async with ts as tscm:
        msg = await tscm.recv()
        print(msg)

    await client.close_connection()

# Method 2: Using Python's Logging Module
logging.basicConfig(level=logging.DEBUG)
# Enable debug logging for all WebSocket connections
logging.getLogger('binance.ws').setLevel(logging.DEBUG)

# Specific component logging examples:
# logging.getLogger('binance.ws.websocket_api').setLevel(logging.DEBUG)
# logging.getLogger('binance.ws.reconnecting_websocket').setLevel(logging.DEBUG)
# logging.getLogger('binance.ws.streams').setLevel(logging.DEBUG)