TCPDashboard/docs/exchanges/README.md

Exchange Documentation

This section contains detailed documentation for all cryptocurrency exchange integrations in the TCP Dashboard platform.

📋 Contents

Supported Exchanges

Production Ready

• OKX Collector - Complete guide to OKX exchange integration
  • Real-time trades, orderbook, and ticker data collection
  • WebSocket connection management with OKX-specific ping/pong
  • Factory pattern usage and configuration
  • Data processing and validation
  • Monitoring and troubleshooting
  • Production deployment guide

Planned Integrations

• Binance - Major global exchange (development planned)
• Coinbase Pro - US-regulated exchange (development planned)
• Kraken - European exchange (development planned)
• Bybit - Derivatives exchange (development planned)

🏗️ Exchange Architecture

Modular Design

Each exchange implementation follows a standardized structure:

data/exchanges/
├── __init__.py              # Main exports and factory
├── registry.py              # Exchange registry and capabilities
├── factory.py               # Factory pattern for collectors
└── {exchange}/              # Exchange-specific implementation
    ├── __init__.py          # Exchange exports
    ├── collector.py         # {Exchange}Collector class
    └── websocket.py         # {Exchange}WebSocketClient class

Standardized Interface

All exchange collectors implement the same interface:

from data.exchanges import ExchangeFactory, ExchangeCollectorConfig
from data.base_collector import DataType

# Unified configuration across all exchanges
config = ExchangeCollectorConfig(
    exchange='okx',  # or 'binance', 'coinbase', etc.
    symbol='BTC-USDT',
    data_types=[DataType.TRADE, DataType.ORDERBOOK],
    auto_restart=True
)

collector = ExchangeFactory.create_collector(config)

🚀 Quick Start

Using Factory Pattern

import asyncio
from data.exchanges import get_supported_exchanges, create_okx_collector
from data.base_collector import DataType

async def main():
    # Check supported exchanges
    exchanges = get_supported_exchanges()
    print(f"Supported: {exchanges}")  # ['okx']
    
    # Create OKX collector
    collector = create_okx_collector(
        symbol='BTC-USDT',
        data_types=[DataType.TRADE, DataType.ORDERBOOK]
    )
    
    # Add data callback
    def on_trade(data_point):
        print(f"Trade: {data_point.data}")
    
    collector.add_data_callback(DataType.TRADE, on_trade)
    
    # Start collection
    await collector.start()
    await asyncio.sleep(60)
    await collector.stop()

asyncio.run(main())

Multi-Exchange Setup

from data.exchanges import ExchangeFactory, ExchangeCollectorConfig
from data.collector_manager import CollectorManager

async def setup_multi_exchange():
    manager = CollectorManager("multi_exchange_system")
    
    # Future: Multiple exchanges
    configs = [
        ExchangeCollectorConfig('okx', 'BTC-USDT', [DataType.TRADE]),
        # ExchangeCollectorConfig('binance', 'BTC-USDT', [DataType.TRADE]),
        # ExchangeCollectorConfig('coinbase', 'BTC-USD', [DataType.TRADE])
    ]
    
    for config in configs:
        collector = ExchangeFactory.create_collector(config)
        manager.add_collector(collector)
    
    await manager.start()
    return manager

📊 Exchange Capabilities

Data Types

Different exchanges support different data types:

Exchange	Trades	Orderbook	Ticker	Candles	Balance
OKX	✅	✅	✅	🔄	🔄
Binance	🔄	🔄	🔄	🔄	🔄
Coinbase	🔄	🔄	🔄	🔄	🔄

Legend: ✅ Implemented, 🔄 Planned, ❌ Not supported

Trading Pairs

Query supported trading pairs for each exchange:

from data.exchanges import ExchangeFactory

# Get supported pairs
okx_pairs = ExchangeFactory.get_supported_pairs('okx')
print(f"OKX pairs: {okx_pairs}")

# Get exchange information
okx_info = ExchangeFactory.get_exchange_info('okx')
print(f"OKX capabilities: {okx_info}")

🔧 Exchange Configuration

Common Configuration

All exchanges share common configuration options:

from data.exchanges import ExchangeCollectorConfig

config = ExchangeCollectorConfig(
    exchange='okx',                    # Exchange name
    symbol='BTC-USDT',                # Trading pair
    data_types=[DataType.TRADE],      # Data types to collect
    auto_restart=True,                # Auto-restart on failures
    health_check_interval=30.0,       # Health check interval
    store_raw_data=True,              # Store raw exchange data
    custom_params={                   # Exchange-specific parameters
        'ping_interval': 25.0,
        'max_reconnect_attempts': 5
    }
)

Exchange-Specific Configuration

Each exchange has specific configuration files:

• OKX: config/okx_config.json
• Binance: config/binance_config.json (planned)
• Coinbase: config/coinbase_config.json (planned)

📈 Performance Comparison

Real-time Data Rates

Approximate message rates for different exchanges:

Exchange	Trades/sec	Orderbook Updates/sec	Latency
OKX	5-50	10-100	~50ms
Binance	TBD	TBD	TBD
Coinbase	TBD	TBD	TBD

Note: Rates vary by trading pair activity

Resource Usage

Memory and CPU usage per collector:

Exchange	Memory (MB)	CPU (%)	Network (KB/s)
OKX	15-25	1-3	5-20
Binance	TBD	TBD	TBD
Coinbase	TBD	TBD	TBD

🔍 Monitoring & Debugging

Exchange Status

Monitor exchange-specific metrics:

# Get exchange status
status = collector.get_status()
print(f"Exchange: {status['exchange']}")
print(f"WebSocket State: {status['websocket_state']}")
print(f"Messages Processed: {status['messages_processed']}")

# Exchange-specific metrics
if 'websocket_stats' in status:
    ws_stats = status['websocket_stats']
    print(f"Reconnections: {ws_stats['reconnections']}")
    print(f"Ping/Pong: {ws_stats['pings_sent']}/{ws_stats['pongs_received']}")

Debug Mode

Enable exchange-specific debugging:

import os
os.environ['LOG_LEVEL'] = 'DEBUG'

# Detailed exchange logging
collector = create_okx_collector('BTC-USDT', [DataType.TRADE])
# Check logs: ./logs/okx_collector_btc_usdt_debug.log

🛠️ Adding New Exchanges

Implementation Checklist

To add a new exchange:

1. Create Exchange Folder: data/exchanges/{exchange}/
2. Implement WebSocket Client: {exchange}/websocket.py
3. Implement Collector: {exchange}/collector.py
4. Add to Registry: Update registry.py
5. Create Configuration: config/{exchange}_config.json
6. Add Documentation: docs/exchanges/{exchange}_collector.md
7. Add Tests: tests/test_{exchange}_collector.py

Implementation Template

# data/exchanges/newexchange/collector.py
from data.base_collector import BaseDataCollector, DataType
from .websocket import NewExchangeWebSocketClient

class NewExchangeCollector(BaseDataCollector):
    def __init__(self, symbol: str, **kwargs):
        super().__init__("newexchange", [symbol], **kwargs)
        self.ws_client = NewExchangeWebSocketClient()
    
    async def connect(self) -> bool:
        return await self.ws_client.connect()
    
    # Implement other required methods...

🔗 Related Documentation

• Components Documentation - Core system components
• Architecture Overview - System design
• Setup Guide - Configuration and deployment
• API Reference - Technical specifications

📞 Support

Exchange-Specific Issues

For exchange-specific problems:

1. Check Status: Use get_status() and get_health_status()
2. Review Logs: Check exchange-specific log files
3. Verify Configuration: Confirm exchange configuration files
4. Test Connection: Run exchange-specific test scripts

Common Issues

• Rate Limiting: Each exchange has different rate limits
• Symbol Formats: Trading pair naming conventions vary
• WebSocket Protocols: Each exchange has unique WebSocket requirements
• Data Formats: Message structures differ between exchanges

---

For the complete documentation index, see the main documentation README.