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](okx_collector.md)** - *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:

```python
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

```python
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

```python
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:

```python
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:

```python
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:

```python
# 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:

```python
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

```python
# 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](../components/)** - Core system components
- **[Architecture Overview](../architecture/)** - System design
- **[Setup Guide](../guides/setup.md)** - Configuration and deployment
- **[API Reference](../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](../README.md).*