{"id":9551,"library":"binance-connector","title":"Binance Connector","description":"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.","status":"active","version":"3.12.0","language":"en","source_language":"en","source_url":"https://github.com/binance/binance-connector-python","tags":["binance","crypto","trading","exchange","api","spot","futures"],"install":[{"cmd":"pip install binance-connector","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from binance.client import Client","symbol":"Spot","correct":"from binance.spot import Spot as Client"},{"note":"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.","wrong":"import binance.client","symbol":"Futures","correct":"from binance.futures import Futures as Client"}],"quickstart":{"code":"import os\nfrom binance.spot import Spot as Client # For Spot API. Use 'from binance.futures import Futures as Client' for Futures.\n\napi_key = os.environ.get('BINANCE_API_KEY', '')\napi_secret = os.environ.get('BINANCE_API_SECRET', '')\n\n# Initialize the client (API keys are optional for public endpoints like server time)\nclient = Client(api_key=api_key, api_secret=api_secret)\n\ntry:\n    # Get server time (public endpoint)\n    response = client.time()\n    print(f\"Binance Server Time: {response['serverTime']}\")\n\n    # Get exchange information (public endpoint)\n    exchange_info = client.exchange_info()\n    print(f\"Number of symbols listed: {len(exchange_info['symbols'])}\")\n\n    # Example of a signed endpoint (requires API key permissions)\n    # account_info = client.account()\n    # print(f\"Account balance: {account_info['balances'][0]['free']}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    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.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"3.x onwards"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"API Rate Limiting: Binance API has strict rate limits. Exceeding them frequently will result in `APIError(code=-1003)` and potentially temporary IP bans.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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').","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"You are likely attempting to use an import path belonging to the `python-binance` library, not `binance-connector`.","error":"ModuleNotFoundError: No module named 'binance.client'"},{"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.","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.","error":"binance.exceptions.APIError: APIError(code=-1002): Invalid API-key, IP, or permissions for action."},{"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.","cause":"Your application has exceeded Binance's API rate limits for a given time period.","error":"binance.exceptions.APIError: APIError(code=-1003): Too many requests. Please try again later."}]}