Binance Connector

3.12.0 · active · verified Fri Apr 17

This is the lightweight, official Python library for connecting to Binance's public API. It provides interfaces for Spot, Futures, and other market data and trading endpoints. Currently at version 3.12.0, it receives active development and frequent updates to align with Binance API changes.

Common errors

```
ModuleNotFoundError: No module named 'binance.client'
```
cause You are likely attempting to use an import path belonging to the `python-binance` library, not `binance-connector`.

fix After installing `binance-connector` (`pip install binance-connector`), update your client import to `from binance.spot import Spot as Client` for Spot trading or `from binance.futures import Futures as Client` for Futures.
```
binance.exceptions.APIError: APIError(code=-1002): Invalid API-key, IP, or permissions for action.
```
cause The provided API key or secret is incorrect, your IP address is not whitelisted, or the API key lacks necessary permissions for the requested operation.

fix Double-check your `BINANCE_API_KEY` and `BINANCE_API_SECRET` environment variables. If applicable, ensure your IP address is whitelisted in Binance API settings, and verify that the API key has the required permissions enabled on Binance's website.
```
binance.exceptions.APIError: APIError(code=-1003): Too many requests. Please try again later.
```
cause Your application has exceeded Binance's API rate limits for a given time period.

fix Reduce the frequency of your API calls. Implement delays or a backoff strategy between requests to stay within the limits. Review Binance's official API documentation for specific endpoint rate limits.

Warnings

breaking Module structure change in 3.x: The client import path for `binance-connector` changed in version 3.x to differentiate between Spot and Futures clients.
Fix: Update your imports to explicitly use `from binance.spot import Spot as Client` or `from binance.futures import Futures as Client`. Direct `from binance import Client` will no longer work.
gotcha Confusion with `python-binance`: `binance-connector` is the *official* library provided by Binance, distinct from the popular community-maintained `python-binance`. Their APIs and import paths are incompatible.
Fix: Ensure you are installing `binance-connector` (`pip install binance-connector`) and using its specific import paths and methods. Do not mix code or documentation from the two libraries.
gotcha API Rate Limiting: Binance API has strict rate limits. Exceeding them frequently will result in `APIError(code=-1003)` and potentially temporary IP bans.
Fix: Implement proper rate-limiting strategies in your application, such as introducing delays between requests, using a queue system, or employing exponential backoff for retries. Consult Binance's official API documentation for current rate limits.
gotcha API Key Permissions: Even with correct API keys, certain operations may fail with `APIError(code=-1002)` if the key lacks the necessary permissions (e.g., 'Enable Spot & Margin Trading', 'Enable Withdrawals').
Fix: Log in to your Binance account, navigate to API Management, and verify that your API key has all the required permissions enabled for the actions you are trying to perform.

Install

pip install binance-connector Install stable version

Imports

Spot
wrong:
```
from binance.client import Client
```
correct:
```
from binance.spot import Spot as Client
```
The `binance-connector` library uses `Spot` (or `Futures`) for its client, not a direct `Client` import. The `from binance.client import Client` pattern belongs to the community-maintained `python-binance` library, which is distinct.
Futures
wrong:
```
import binance.client
```
correct:
```
from binance.futures import Futures as Client
```
Similar to Spot, the Futures client is imported from `binance.futures`. Avoid attempting to directly import `binance.client` as it's not part of this library's structure.

Quickstart

This example demonstrates how to initialize the `Spot` client and make basic calls to public endpoints like getting the server time and exchange information. For Futures API, replace `Spot` with `Futures`. For endpoints requiring authentication, ensure `BINANCE_API_KEY` and `BINANCE_API_SECRET` environment variables are set.

import os
from binance.spot import Spot as Client # For Spot API. Use 'from binance.futures import Futures as Client' for Futures.

api_key = os.environ.get('BINANCE_API_KEY', '')
api_secret = os.environ.get('BINANCE_API_SECRET', '')

# Initialize the client (API keys are optional for public endpoints like server time)
client = Client(api_key=api_key, api_secret=api_secret)

try:
    # Get server time (public endpoint)
    response = client.time()
    print(f"Binance Server Time: {response['serverTime']}")

    # Get exchange information (public endpoint)
    exchange_info = client.exchange_info()
    print(f"Number of symbols listed: {len(exchange_info['symbols'])}")

    # Example of a signed endpoint (requires API key permissions)
    # account_info = client.account()
    # print(f"Account balance: {account_info['balances'][0]['free']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Make sure your API keys (BINANCE_API_KEY, BINANCE_API_SECRET) are correctly set in your environment if required for the endpoint, and check network connectivity.")

view raw JSON →