lowkey_backtest/live_trading/multi_pair/README.md

# Multi-Pair Divergence Live Trading

This module implements live trading for the Multi-Pair Divergence Selection Strategy on OKX perpetual futures.

## Overview

The strategy scans 10 cryptocurrency pairs for spread divergence opportunities:

1. **Pair Universe**: Top 10 assets by market cap (BTC, ETH, SOL, XRP, BNB, DOGE, ADA, AVAX, LINK, DOT)
2. **Spread Z-Score**: Identifies when pairs are divergent from their historical mean
3. **Universal ML Model**: Predicts probability of successful mean reversion
4. **Dynamic Selection**: Trades the pair with highest divergence score

## Prerequisites

Before running live trading, you must train the model via backtesting:

```bash
uv run python scripts/run_multi_pair_backtest.py
```

This creates `data/multi_pair_model.pkl` which the live trading bot requires.

## Setup

### 1. API Keys

Same as single-pair trading. Set in `.env`:

```env
OKX_API_KEY=your_api_key
OKX_SECRET=your_secret
OKX_PASSWORD=your_passphrase
OKX_DEMO_MODE=true  # Use demo for testing
```

### 2. Dependencies

All dependencies are in `pyproject.toml`. No additional installation needed.

## Usage

### Run with Demo Account (Recommended First)

```bash
uv run python -m live_trading.multi_pair.main
```

### Command Line Options

```bash
# Custom position size
uv run python -m live_trading.multi_pair.main --max-position 500

# Custom leverage
uv run python -m live_trading.multi_pair.main --leverage 2

# Custom cycle interval (in seconds)
uv run python -m live_trading.multi_pair.main --interval 1800

# Combine options
uv run python -m live_trading.multi_pair.main --max-position 1000 --leverage 3 --interval 3600
```

### Live Trading (Use with Caution)

```bash
uv run python -m live_trading.multi_pair.main --live
```

## How It Works

### Each Trading Cycle

1. **Fetch Data**: Gets OHLCV for all 10 assets from OKX
2. **Calculate Features**: Computes Z-Score, RSI, volatility for all 45 pair combinations
3. **Score Pairs**: Uses ML model to rank pairs by divergence score (|Z| x probability)
4. **Check Exits**: If holding, check mean reversion or SL/TP
5. **Enter Best**: If no position, enter the highest-scoring divergent pair

### Entry Conditions

- |Z-Score| > 1.0 (spread diverged from mean)
- ML probability > 0.5 (model predicts successful reversion)
- Funding rate filter passes (avoid crowded trades)

### Exit Conditions

- Mean reversion: |Z-Score| returns to ~0
- Stop-loss: ATR-based (default ~6%)
- Take-profit: ATR-based (default ~5%)

## Strategy Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `z_entry_threshold` | 1.0 | Enter when \|Z-Score\| > threshold |
| `z_exit_threshold` | 0.0 | Exit when Z reverts to mean |
| `z_window` | 24 | Rolling window for Z-Score (hours) |
| `prob_threshold` | 0.5 | ML probability threshold for entry |
| `funding_threshold` | 0.0005 | Funding rate filter (0.05%) |
| `sl_atr_multiplier` | 10.0 | Stop-loss as ATR multiple |
| `tp_atr_multiplier` | 8.0 | Take-profit as ATR multiple |

## Files

### Input

- `data/multi_pair_model.pkl` - Pre-trained ML model (required)

### Output

- `logs/multi_pair_live.log` - Trading logs
- `live_trading/multi_pair_positions.json` - Position persistence
- `live_trading/multi_pair_trade_log.csv` - Trade history

## Architecture

```
live_trading/multi_pair/
    __init__.py          # Module exports
    config.py            # Configuration classes
    data_feed.py         # Multi-asset OHLCV fetcher
    strategy.py          # ML scoring and signal generation
    main.py              # Bot orchestrator
    README.md            # This file
```

## Differences from Single-Pair

| Aspect | Single-Pair | Multi-Pair |
|--------|-------------|------------|
| Assets | ETH only (BTC context) | 10 assets, 45 pairs |
| Model | ETH-specific | Universal across pairs |
| Selection | Fixed pair | Dynamic best pair |
| Stops | Fixed 6%/5% | ATR-based dynamic |

## Risk Warning

This is experimental trading software. Use at your own risk:

- Always start with demo trading
- Never risk more than you can afford to lose
- Monitor the bot regularly
- The model was trained on historical data and may not predict future performance