lowkey_backtest/live_trading/README.md

# Live Trading - Regime Reversion Strategy

This module implements live trading for the ML-based regime detection and mean reversion strategy on OKX perpetual futures.

## Overview

The strategy trades ETH perpetual futures based on:
1. **BTC/ETH Spread Z-Score**: Identifies when ETH is cheap or expensive relative to BTC
2. **Random Forest ML Model**: Predicts probability of successful mean reversion
3. **Funding Rate Filter**: Avoids trades in overheated/oversold market conditions

## Setup

### 1. API Keys

The bot loads OKX API credentials from `../BTC_spot_MVRV/.env`.

**IMPORTANT: OKX uses SEPARATE API keys for live vs demo trading!**

#### Option A: Demo Trading (Recommended for Testing)
1. Go to [OKX Demo Trading](https://www.okx.com/demo-trading)
2. Create a demo account if you haven't
3. Generate API keys from the demo environment
4. Set in `.env`:
```env
OKX_API_KEY=your_demo_api_key
OKX_SECRET=your_demo_secret
OKX_PASSWORD=your_demo_passphrase
OKX_DEMO_MODE=true
```

#### Option B: Live Trading (Real Funds)
Use your existing live API keys with:
```env
OKX_API_KEY=your_live_api_key
OKX_SECRET=your_live_secret
OKX_PASSWORD=your_live_passphrase
OKX_DEMO_MODE=false
```

**Note:** You cannot use live API keys with `OKX_DEMO_MODE=true` or vice versa.
OKX will return error `50101: APIKey does not match current environment`.

### 2. Dependencies

All dependencies are already in the project's `pyproject.toml`. No additional installation needed.

## Usage

### Run with Demo Account (Recommended First)

```bash
cd /path/to/lowkey_backtest
uv run python -m live_trading.main
```

### Command Line Options

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

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

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

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

### Live Trading (Use with Caution)

```bash
# Requires OKX_DEMO_MODE=false in .env
uv run python -m live_trading.main --live
```

## Architecture

```
live_trading/
    __init__.py          # Module initialization
    config.py            # Configuration loading
    okx_client.py        # OKX API wrapper
    data_feed.py         # Real-time OHLCV data
    position_manager.py  # Position tracking
    live_regime_strategy.py  # Strategy logic
    main.py              # Entry point
    .env.example         # Environment template
    README.md            # This file
```

## Strategy Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `z_entry_threshold` | 1.0 | Enter when \|Z-Score\| > threshold |
| `z_window` | 24 | Rolling window for Z-Score (hours) |
| `model_prob_threshold` | 0.5 | ML probability threshold for entry |
| `funding_threshold` | 0.005 | Funding rate filter threshold |
| `stop_loss_pct` | 6% | Stop-loss percentage |
| `take_profit_pct` | 5% | Take-profit percentage |

## Files Generated

- `live_trading/positions.json` - Open positions persistence
- `live_trading/trade_log.csv` - Trade history
- `live_trading/regime_model.pkl` - Trained ML model
- `logs/live_trading.log` - Trading logs

## 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
- Have a kill switch ready (Ctrl+C)

## Troubleshooting

### API Key Issues
- Ensure API keys have trading permissions
- For demo trading, use demo-specific API keys
- Check that passphrase matches exactly

### No Signals Generated
- The strategy requires the ML model to be trained
- Need at least 200 candles of data
- Model trains automatically on first run

### Position Sync Issues
- The bot syncs with exchange positions on each cycle
- If positions are closed manually, the bot will detect this