# Ping-Pong Bot: Backtesting & Optimization Guide

This guide explains how to use the local backtesting environment to test and optimize your BTC trading strategy using historical data from your PostgreSQL database.

## 1. Prerequisites
The backtesting engine requires `pandas`, `numpy`, and `asyncpg`. These are already installed in your `btc_ping_pong_bot` Docker container.

To run the backtester, use the following command:
```bash
docker exec -it btc_ping_pong_bot python src/strategies/backtest_engine.py
```

## 2. Local PC Setup (Recommended for Memory Savings)
Running the backtest on your local machine is much faster and saves server memory.

### Steps:
1.  **Clone/Sync your repo** to your local machine.
2.  **Install dependencies**:
    ```bash
    pip install -r requirements.txt
    ```
3.  **Configure `.env`**: Ensure your local `.env` file has the correct `DB_HOST` (e.g., `20.20.20.20`).
4.  **Run the engine**:
    ```bash
    # From the project root
    python3 src/strategies/backtest_engine.py --start_date 2024-01-01 --end_date 2024-01-31
    ```

## 3. Backtest Engine (`backtest_engine.py`)
The backtest engine reuses the core logic from `ping_pong_bot.py` via the `PingPongStrategy` class.

### Key Features:
*   **Virtual Exchange:** Simulates a $1,000 account with customizable leverage and fees.
*   **Fee Simulation:** Applies a 0.05% taker fee (configurable) to every entry and exit.
*   **Mark-to-Market:** Calculates real-time equity based on current price and position size.
*   **Data Sourcing:** Automatically pulls the last 10,000 candles from your `btc_data` database.

### How to Run:
```bash
# From the project root
docker exec -it btc_ping_pong_bot python src/strategies/backtest_engine.py
```

## 3. Regime Testing (MA Switching)
You can test different Moving Average (MA) settings to see which regime detector works best for switching between `long` and `short` modes.

### Examples:
*   **Test 15m SMA 200:**
    ```bash
    docker exec -it btc_ping_pong_bot python src/strategies/backtest_engine.py --ma_period 200 --ma_interval 15m
    ```
*   **Test 1h SMA 50:**
    ```bash
    docker exec -it btc_ping_pong_bot python src/strategies/backtest_engine.py --ma_period 50 --ma_interval 1h
    ```
*   **Test 4h SMA 100:**
    ```bash
    docker exec -it btc_ping_pong_bot python src/strategies/backtest_engine.py --ma_period 100 --ma_interval 4h --limit 20000
    ```

### How it works:
When `--ma_period` is provided, the engine:
1.  Loads the MA timeframe data from the DB.
2.  Merges it with the 1m price data.
3.  Switches modes (`long` <=> `short`) whenever the 1m price crosses the MA.
4.  **Automatically closes** the existing position on a mode switch, just like the live bot.

## 4. Parameter Overrides
You can quickly override strategy settings without editing the config file:
*   `--direction`: Force a specific mode (`long` or `short`).
*   `--limit`: Change the number of 1m candles to test (default 10,000).
*   `--config`: Use a different configuration file.

## 5. Interpreting Results
*   **Final Equity:** Your simulated account balance after all trades.
*   **ROI:** Return on Investment (Percentage).
*   **Total Fees:** Total cost paid to the "Virtual Exchange". High fees indicate over-trading.
*   **Trade Count:** Total number of Enter/Exit signals triggered.

## 6. Next Steps
1.  Run the backtester to see baseline performance.
2.  Adjust parameters in `config/ping_pong_config.yaml`.
3.  Rerun the backtest to see the impact of your changes.
4.  (Optional) Ask me to implement the `optimize_strategy.py` script once you have Optuna installed.