crypto_trader/docs/architecture/exchange_integration.md

Exchange Integration Architecture

This document describes how exchange adapters integrate with the trading system.

Adapter Pattern

All exchanges use the adapter pattern to provide a unified interface:

Trading Engine
        │
        ▼
BaseExchange (Interface)
        │
        ├──► CoinbaseExchange
        ├──► BinanceExchange (future)
        └──► KrakenExchange (future)

Base Exchange Interface

All exchanges implement BaseExchange:

class BaseExchange(ABC):
    async def connect()
    async def disconnect()
    async def fetch_balance()
    async def place_order()
    async def cancel_order()
    async def fetch_order_status()
    async def fetch_ohlcv()
    async def subscribe_ohlcv()
    async def subscribe_trades()
    async def subscribe_order_book()
    async def fetch_open_orders()
    async def fetch_positions()
    async def fetch_markets()

Exchange Factory

The factory pattern creates exchange instances:

ExchangeFactory
        │
        ├──► get_exchange(name)
        │         │
        │         ├──► Lookup registered adapter
        │         ├──► Get API keys from KeyManager
        │         └──► Instantiate adapter
        │
        └──► register_exchange(name, adapter_class)

Exchange Registration

Exchanges are registered at module import:

# In exchange module
from src.exchanges.factory import ExchangeFactory

ExchangeFactory.register_exchange("coinbase", CoinbaseExchange)

CCXT Integration

Most exchanges use the CCXT library:

import ccxt.pro as ccxt

class CoinbaseExchange(BaseExchange):
    def __init__(self, ...):
        self.exchange = ccxt.coinbaseadvanced({
            'apiKey': api_key,
            'secret': secret_key,
            'enableRateLimit': True,
        })

WebSocket Support

Real-time data via WebSockets:

async def subscribe_ohlcv(self, symbol, timeframe, callback):
    """Subscribe to OHLCV updates."""
    await self.exchange.watch_ohlcv(symbol, timeframe, callback)

Rate Limiting

All exchanges respect rate limits:

• CCXT handles rate limiting automatically
• enableRateLimit: True in exchange config
• Custom rate limiting for non-CCXT exchanges

Error Handling

Exchange-specific error handling:

try:
    order = await self.exchange.create_order(...)
except ccxt.NetworkError as e:
    # Handle network errors
    logger.error(f"Network error: {e}")
    raise
except ccxt.ExchangeError as e:
    # Handle exchange errors
    logger.error(f"Exchange error: {e}")
    raise

Connection Management

• Connection Pooling: Reuse connections when possible
• Auto-Reconnect: Automatic reconnection on disconnect
• Health Monitoring: Monitor connection health
• Graceful Shutdown: Properly close connections

Adding New Exchanges

See Adding Exchanges for detailed guide.

Exchange-Specific Features

Some exchanges have unique features:

• Coinbase: Requires passphrase for some operations
• Binance: Futures and margin trading
• Kraken: Different order types

These are handled in exchange-specific adapters.

WebSocket Implementation

Coinbase WebSocket Support

The Coinbase adapter includes WebSocket subscription methods:

• subscribe_ticker(): Subscribe to real-time price updates
• subscribe_orderbook(): Subscribe to order book changes
• subscribe_trades(): Subscribe to trade executions

WebSocket Architecture

Exchange WebSocket API
    ↓
CoinbaseAdapter.subscribe_*()
    ↓
Callback Functions
    ↓
DataCollector (with signals)
    ↓
UI Widgets (via signals)

Reconnection Strategy

• Automatic reconnection on disconnect
• Message queuing during disconnection
• Heartbeat/ping-pong for connection health
• Fallback to polling if WebSocket unavailable

Implementation Notes

• Uses websockets library for async WebSocket connections
• Callbacks are wrapped to emit Qt signals for UI updates
• Basic implementation provided; can be extended for full Coinbase Advanced Trade WebSocket API