297 lines
8.7 KiB
Markdown
297 lines
8.7 KiB
Markdown
# 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).* |