CCXT

Warnings

• gotcha Always enable and configure rate limiting to avoid being banned by exchanges. Set `enableRateLimit: True` and adjust `rateLimit` (in milliseconds) as needed, especially for high-frequency operations. Default `rateLimit` values may not always prevent issues with aggressive API usage.
  Fix: Initialize exchange with `{'rateLimit': <milliseconds>, 'enableRateLimit': True}`. Increase `rateLimit` if encountering `DDoSProtection` or `RateLimitExceeded` errors.
• gotcha Handle API keys and secrets securely. Never hardcode them directly in your script, especially when using private API methods. Use environment variables or a secure configuration management system.
  Fix: Load API keys and secrets from environment variables (e.g., `os.environ.get('API_KEY')`) or a separate, untracked configuration file.
• gotcha Differentiate between synchronous (`import ccxt`) and asynchronous (`import ccxt.async_support as ccxt`) imports. Using asynchronous methods (e.g., `await exchange.fetch_ticker`) requires the `async_support` module and an `asyncio` event loop. Mixing them without proper handling will lead to runtime errors.
  Fix: For async operations, use `import ccxt.async_support as ccxt` and ensure all API calls are `await`-ed within an `async` function. For sync, use `import ccxt` and regular blocking calls.
• gotcha Implement robust error handling for network and exchange-specific issues. API calls can fail due to network problems, exchange-specific errors (e.g., invalid symbol, insufficient funds), or rate limits.
  Fix: Wrap API calls in `try...except` blocks, specifically catching `ccxt.NetworkError`, `ccxt.ExchangeError`, and a general `Exception` for unexpected issues.
• breaking While CCXT aims for a unified interface, underlying exchange APIs frequently change. These changes, though often abstracted, can sometimes lead to unexpected behavior or require minor adjustments to your code (e.g., changes in error messages, supported parameters, or data formats for specific exchanges).
  Fix: Regularly update the library and review the CCXT GitHub releases and changelogs. Test your application thoroughly after updating. Check `exchange.has` properties for exchange-specific capabilities.
• gotcha CCXT.Pro, a distinct (though integrated) part of the library, provides WebSocket APIs for real-time, high-frequency trading. It has different `watch*` methods and incremental data structures. The standard CCXT library primarily uses REST APIs.
  Fix: Understand whether you need REST (standard CCXT) or WebSocket (CCXT.Pro) functionality. Use `ccxt.pro` for real-time streams and be aware of its specific `watch*` methods and caching mechanisms. The examples folder in the CCXT GitHub repository provides separate examples for `ccxt.pro`.

Install

• pip install ccxt Install stable version

Imports

• ccxt

  import ccxt

  Standard synchronous import.
• ccxt.async_support

  import ccxt.async_support as ccxt

  Import for asynchronous operations (requires Python 3.7+ and `asyncio`).

Quickstart

This quickstart demonstrates how to instantiate an exchange client and fetch public market data (a ticker) for a specified symbol. It includes basic error handling and illustrates how to configure rate limiting. For private API access (e.g., fetching balance, placing orders), API keys are required and should be loaded securely, ideally from environment variables.

import ccxt
import os

exchange_id = 'binance'
exchange_class = getattr(ccxt, exchange_id)

# Public API access (no API keys needed for public data)
exchange = exchange_class({
    'rateLimit': 1200,
    'enableRateLimit': True, # Important for respecting exchange limits
})

try:
    # Fetch ticker for a symbol
    symbol = 'BTC/USDT'
    ticker = exchange.fetch_ticker(symbol)
    print(f"Fetched ticker for {symbol} on {exchange_id}: {ticker['last']} (last price)")

    # For private API, uncomment and replace with actual keys (use environment variables in production)
    # exchange_private = exchange_class({
    #     'apiKey': os.environ.get('CCXT_BINANCE_API_KEY', ''),
    #     'secret': os.environ.get('CCXT_BINANCE_SECRET', ''),
    #     'rateLimit': 1200,
    #     'enableRateLimit': True,
    # })
    # if exchange_private.apiKey and exchange_private.secret:
    #     balance = exchange_private.fetch_balance()
    #     print(f"Fetched balance for {exchange_id}: {balance['total']}")

except ccxt.NetworkError as e:
    print(f"Network error: {type(e).__name__} {str(e)}")
except ccxt.ExchangeError as e:
    print(f"Exchange error: {type(e).__name__} {str(e)}")
except Exception as e:
    print(f"An unexpected error occurred: {type(e).__name__} {str(e)}")