Binance REST API Python Client

Warnings

• breaking With the v1.0.0 release, all 'wapi' calls were migrated to 'sapi' endpoints, and websocket streams (including DepthCacheManager) were converted to use asynchronous context managers. Code using older 'wapi' endpoints or synchronous websocket implementations will break.
  Fix: Update API calls to use the new 'sapi' endpoints (if directly calling internal methods) and refactor websocket stream handling to use `async with` for `BinanceSocketManager` or `DepthCacheManager`. Refer to the official documentation for updated examples.
• gotcha Binance API keys should be stored securely and never hardcoded in your application. Treat your secret key like a password; anyone with access to it can trade on your account.
  Fix: Store API keys as environment variables, use a secrets management service, or load them from a secure configuration file. The quickstart example demonstrates using `os.environ.get()`.
• gotcha Binance enforces strict rate limits on API requests (e.g., 20 requests per second). Exceeding these limits will result in API errors (e.g., HTTP 429 Too Many Requests) and potentially IP bans. While the library handles timestamps, developers must manage their request frequency.
  Fix: Implement proper rate-limiting strategies in your application, such as delays between requests or using a token bucket algorithm. Check Binance's official API documentation for specific rate limits on different endpoints. The `X-MBX-USED-WEIGHT` headers can help monitor usage.
• gotcha Order placement can fail with 'Precision is over the maximum defined for this asset' if the quantity or price has too many decimal places. Each trading pair on Binance has specific precision requirements for quantity, price, and other parameters.
  Fix: Before placing orders, retrieve exchange information using `client.get_exchange_info()` to determine the correct `stepSize` (for quantity) and `tickSize` (for price) for the specific symbol. Format your order parameters to adhere to these precision rules, typically by rounding down.
• gotcha Websocket connections to Binance are subject to a 24-hour limit, after which they will be disconnected. Additionally, user data streams require 'listen keys' to be kept alive (renewed) at least once every hour.
  Fix: Implement robust reconnection logic for all websocket streams. For user data streams, ensure a 'keep-alive' mechanism is in place to periodically send a ping or renew the listen key before it expires.
• gotcha When calculating annualized yields for perpetual futures funding rates, assuming a fixed 8-hour funding interval for all symbols is a common error. Many Binance perpetual symbols (especially newer or smaller-cap altcoins) operate on 4-hour, 1-hour, or even 24-hour cycles, leading to significant miscalculations.
  Fix: Do not hardcode `3 * 365` or `1095` for annualization. Query Binance's exchange information or specific funding rate endpoints to determine the actual funding interval for each symbol. If an endpoint only returns non-default intervals, assume 8-hour for symbols not listed.

Install

• pip install python-binance Install latest version

Imports

• Client

  from binance.client import Client

  For synchronous REST API interactions.
• AsyncClient

  from binance import AsyncClient

  AsyncClient is imported directly from the top-level 'binance' package, not 'binance.client'. Forgetting 'await' on AsyncClient.create() is also a common error.
• BinanceSocketManager

  from binance import BinanceSocketManager

  For asynchronous WebSocket stream management. Requires an AsyncClient instance.
• ThreadedWebsocketManager

  from binance.threaded_websocket import ThreadedWebsocketManager

  While 'ThreadedApiManager' exists, 'ThreadedWebsocketManager' is the commonly used class for a simpler, threaded (non-asyncio) websocket approach. Note that the direct path from search was `binance.ws.threaded_stream`, but `binance.threaded_websocket` is the correct top-level import for `ThreadedWebsocketManager`.

Quickstart

This quickstart demonstrates how to initialize an `AsyncClient` with API keys from environment variables, fetch account balances, and retrieve a symbol's latest price. It uses `asyncio.run` to execute the asynchronous operations. Remember to replace placeholder API keys with your actual Binance API key and secret, ensuring they are stored securely as environment variables.

import asyncio
import os
from binance import AsyncClient

async def main():
    api_key = os.environ.get('BINANCE_API_KEY', '')
    api_secret = os.environ.get('BINANCE_SECRET_KEY', '')

    if not api_key or not api_secret:
        print("Please set BINANCE_API_KEY and BINANCE_SECRET_KEY environment variables.")
        return

    client = await AsyncClient.create(api_key, api_secret)

    try:
        # Get account information
        account_info = await client.get_account()
        print("Account Status:")
        for asset in account_info['balances']:
            if float(asset['free']) > 0 or float(asset['locked']) > 0:
                print(f"  {asset['asset']}: Free {asset['free']}, Locked {asset['locked']}")

        # Get latest price for BTCUSDT
        btc_price = await client.get_symbol_ticker(symbol='BTCUSDT')
        print(f"\nLatest BTCUSDT Price: {btc_price['price']}")

    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        await client.close_connection()

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