# Pairs Trading Strategy - Configuration Guide

This guide walks you through configuring and enabling the Statistical Arbitrage (Pairs Trading) strategy in your crypto trading application.

## Overview

Pairs Trading is a market-neutral strategy that profits from the relative price movements between two correlated assets. When the spread between two assets diverges beyond a statistical threshold (Z-Score), the strategy generates signals to trade the reversion.

---

## Step 1: Navigate to Strategy Management

1. Open your application in the browser (typically `http://localhost:5173`)
2. Click on **"Strategies"** in the navigation menu
3. You'll see the Strategy Management page

---

## Step 2: Create a New Strategy

1. Click the **"Create Strategy"** button in the top-right corner
2. The Strategy Dialog will open

---

## Step 3: Configure Basic Settings

Fill in the following fields:

| Field | Description | Example |
|-------|-------------|---------|
| **Strategy Name** | A descriptive name for your strategy | `SOL-AVAX Pairs Trade` |
| **Strategy Type** | Select from dropdown | `Statistical Arbitrage (Pairs)` |
| **Primary Symbol** | The main asset to trade | `SOL/USD` |
| **Exchange** | Your configured exchange | `Coinbase` or `Binance` |
| **Timeframe** | Candlestick interval | `1h` (recommended) |

---

## Step 4: Configure Pairs Trading Parameters

After selecting "Statistical Arbitrage (Pairs)" as the strategy type, you'll see the parameters section:

### Required Parameters:

| Parameter | Description | Default | Recommended Range |
|-----------|-------------|---------|-------------------|
| **Second Symbol** | The correlated asset to pair with | - | `AVAX/USD`, `ETH/USD`, etc. |
| **Lookback Period** | Rolling window for statistics | `20` | 15-50 |
| **Z-Score Threshold** | Trigger level for signals | `2.0` | 1.5-3.0 |

### Parameter Explanations:

- **Second Symbol**: Choose an asset that moves similarly to your primary symbol. Common pairs include:
  - `BTC/USD` ↔ `ETH/USD` (highly correlated)
  - `SOL/USD` ↔ `AVAX/USD` (Layer 1s)
  - `DOGE/USD` ↔ `SHIB/USD` (meme coins)

- **Lookback Period**: Number of candles used to calculate rolling mean and standard deviation. Higher values = smoother but slower to react.

- **Z-Score Threshold**: How many standard deviations from the mean before triggering:
  - `1.5` = More frequent signals, smaller moves
  - `2.0` = Balanced (default)
  - `2.5-3.0` = Fewer signals, larger moves

---

## Step 5: Additional Settings

| Setting | Description | Recommendation |
|---------|-------------|----------------|
| **Paper Trading** | Enable for testing | ✅ Start with Paper Trading ON |
| **Auto Execute** | Automatically place trades | ❌ Keep OFF initially to observe signals |

---

## Step 6: Save and Enable

1. Click **"Create"** to save the strategy
2. The strategy will appear in your strategy list with status "Disabled"
3. Click the **▶️ Play** button to enable the strategy

---

## Step 7: Monitor the Spread

Once enabled, scroll down on the Strategies page to see the **Pairs Trading Analysis** section:

- **Current Spread**: The ratio of Primary Symbol / Secondary Symbol prices
- **Z-Score**: How many standard deviations the current spread is from its mean
- **Signal State**: Shows if a signal is active (Long Spread, Short Spread, or Neutral)

### Understanding the Charts:

1. **Spread History Chart**: Shows the ratio over time
2. **Z-Score Chart**: Shows statistical deviation with threshold lines
   - Green dashed line: Buy threshold (-2.0)
   - Red dashed line: Sell threshold (+2.0)

---

## Signal Logic

| Condition | Signal | Action |
|-----------|--------|--------|
| Z-Score > +Threshold | **SELL** | Sell Primary, Buy Secondary |
| Z-Score < -Threshold | **BUY** | Buy Primary, Sell Secondary |
| Z-Score between thresholds | **HOLD** | No action (neutral) |

### Example:
If you're trading `SOL/USD` vs `AVAX/USD`:
- **Z-Score = +2.5**: SOL is overvalued relative to AVAX → Sell SOL, Buy AVAX
- **Z-Score = -2.5**: SOL is undervalued relative to AVAX → Buy SOL, Sell AVAX

---

## Tips for Success

1. **Choose Correlated Pairs**: The strategy works best with assets that historically move together. Check correlation before pairing.

2. **Start with Paper Trading**: Always test with paper trading first to understand signal frequency and behavior.

3. **Consider Timeframe**: 
   - `1h` is good for daily monitoring
   - `4h` for longer-term positions
   - `15m` for more active trading (higher risk)

4. **Monitor Volatility**: The strategy performs best in ranging/mean-reverting markets. Trending markets can cause losses.

5. **Adjust Threshold**: If you get too many signals, increase the threshold. Too few? Lower it.

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| No data appearing | Ensure both symbols are available on your selected exchange |
| Z-Score always near 0 | Try increasing lookback period or verify price data is flowing |
| Too many signals | Increase Z-Score threshold (e.g., 2.5 or 3.0) |
| Strategy not executing | Check if Auto Execute is enabled in Settings |

---

## Example Configuration

```
Name: ETH-SOL Mean Reversion
Type: Statistical Arbitrage (Pairs)
Primary Symbol: ETH/USD
Second Symbol: SOL/USD
Lookback Period: 20
Z-Score Threshold: 2.0
Timeframe: 1h
Paper Trading: ON
```

This configuration would:
1. Monitor the ETH/SOL price ratio
2. Generate a BUY signal when ETH is historically cheap vs SOL (Z-Score < -2)
3. Generate a SELL signal when ETH is historically expensive vs SOL (Z-Score > +2)

---

## How Execution Works

When you click **Start** on a Pairs Trading strategy:

1. **Strategy Scheduler starts** - Runs the strategy on a 60-second interval (configurable)
2. **Each tick**:
   - Fetches current prices for both symbols
   - Calculates spread ratio and Z-Score
   - If Z-Score exceeds threshold → generates signal
3. **Signal execution** (if enabled):
   - Executes both legs simultaneously
   - Primary symbol: BUY or SELL based on signal
   - Secondary symbol: Opposite action
4. **Status updates** visible on Strategies page

---

## Real-Time Status Panel

When strategies are running, you'll see a **green status panel** on the Strategies page showing:

- Strategy name and symbol
- Start time
- Number of signals generated
- Last signal type and price
- Last execution tick time

This updates every 5 seconds automatically.