trade-replay 0.1.0
Practice trading without hindsight bias. Replay historical price action.
License: MIT
Requires Python: >=3.10
Keywords: trading, backtesting, crypto, stocks, simulation, paper-trading

# Trade Replay

[![PyPI version](https://badge.fury.io/py/trade-replay.svg)](https://badge.fury.io/py/trade-replay)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Practice trading without hindsight bias. Learn by doing.

[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/brody4321)

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/brody4321)

Trade Replay lets you replay historical price action candle-by-candle, making trading decisions in real-time without knowing what comes next. Perfect for practicing pattern recognition, testing strategies, and building intuition.

## Features

- **Historical Replay**: Step through past price action one candle at a time
- **Paper Trading**: Execute fake trades during replay, track P&L
- **No Hindsight**: Chart only shows up to "current" candle - no peeking
- **Multiple Timeframes**: 1m, 5m, 15m, 1h, 4h, 1d candles
- **Random Mode**: Drop into random historical moments (no date bias)
- **Performance Tracking**: Track your simulated performance over sessions
- **Scenario Library**: Curated replays of famous pumps, dumps, and patterns

## Installation

```bash
pip install trade-replay
```

## Quick Start

```bash
# Start a replay session
trade-replay start BTC --timeframe 1h

# Random historical moment (no cheating!)
trade-replay random ETH --timeframe 15m

# Replay a specific date range
trade-replay start BTC --from 2021-01-01 --to 2021-03-01

# Famous scenarios
trade-replay scenario --list
trade-replay scenario "btc-2021-crash"
```

## Example Session

```
$ trade-replay random BTC --timeframe 1h

TRADE REPLAY - BTC/USD (1h)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Date hidden until session ends | Candle 1 of ???

        Price Chart (last 50 candles)
   ┌────────────────────────────────────────────┐
62k│                                    ▄       │
61k│                                   ██▄      │
60k│                              ▄▄▄ ████      │
59k│                         ▄██████████▀       │
58k│                    ▄▄▄██████████           │
57k│               ▄▄███████████▀               │
56k│          ▄▄███████████▀                    │
55k│     ▄▄██████████▀▀                         │
54k│▄▄██████████▀                               │
   └────────────────────────────────────────────┘
                                          NOW ▲

Current: $61,234 | High: $62,100 | Low: $60,890
Position: FLAT | Session P&L: $0

Commands:
  [n]ext candle   [b]uy   [s]ell   [c]lose position
  [j]ump 5        [q]uit  [i]nfo   [r]eview trades

> n

...advancing 1 candle...

   ┌────────────────────────────────────────────┐
62k│                                    ▄▄      │
61k│                                   ███▄     │
60k│                              ▄▄▄ █████▄    │
   ...
   └────────────────────────────────────────────┘

Current: $60,456 (-1.3%) | Position: FLAT

> b

BUY ORDER
Size [100-10000 USD]: 1000
Entry: $60,456 | Size: $1,000

Position opened! Stop loss? [price or 'n']: 59000
Take profit? [price or 'n']: 65000

Position: LONG $1,000 @ $60,456
Stop: $59,000 | Target: $65,000

> n
> n
> n

...advancing 3 candles...

Current: $58,200 (-3.7%)

⚠️  STOP LOSS HIT @ $59,000
Position closed: -$24.12 (-2.4%)

Session P&L: -$24.12

> q

SESSION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Reveal: This was BTC from 2024-03-15 to 2024-03-18
(The pre-halving pullback)

Session Stats:
  Candles played: 47
  Trades: 1
  Win rate: 0%
  Net P&L: -$24.12

Review your trades? [y/n]: y

Trade #1: LONG @ $60,456 → Stopped @ $59,000
  Result: -2.4%
  Notes: Bought into resistance, stop was too tight
```

## Modes

### Standard Replay
```bash
trade-replay start BTC --from 2021-11-01 --to 2021-12-01
```
Replay a specific period. Good for studying known events.

### Random Mode
```bash
trade-replay random ETH --timeframe 4h
```
Drops you into a random point in history. Prevents hindsight bias since you don't know what event you're in.

### Scenario Mode
```bash
trade-replay scenario "luna-crash"
```
Curated replays of famous market events:
- `btc-2017-bull` - The legendary 2017 bull run
- `btc-2021-crash` - May 2021 crash (65k → 30k)
- `luna-crash` - LUNA/UST collapse
- `ftx-collapse` - November 2022
- `covid-crash` - March 2020 Black Thursday
- `eth-merge` - The Merge event

### Practice Mode
```bash
trade-replay practice --patterns
```
Focuses on specific chart patterns (head & shoulders, double bottom, etc.)

## Commands During Replay

| Key | Action |
|-----|--------|
| `n` | Next candle |
| `j` | Jump 5 candles |
| `J` | Jump 20 candles |
| `b` | Buy / Long |
| `s` | Sell / Short |
| `c` | Close position |
| `i` | Info (volume, indicators) |
| `r` | Review trades |
| `q` | Quit session |

## Indicators (Optional)

```bash
# Add indicators to chart
trade-replay start BTC --indicators rsi,sma20,sma50
```

Available: `rsi`, `macd`, `sma{N}`, `ema{N}`, `bbands`, `volume`

## Track Progress

```bash
# View your replay statistics
trade-replay stats

REPLAY STATISTICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total sessions: 23
Total trades: 67
Win rate: 43%
Avg winner: +4.2%
Avg loser: -2.8%
Profit factor: 1.4

Best session: +$342 (ETH 2021-08)
Worst session: -$198 (BTC random)

Improving? Your last 10 sessions: 51% win rate (vs 38% first 10)
```

## Use as Library

```python
from trade_replay import Replay

replay = Replay("BTC", timeframe="1h", start="2021-06-01", end="2021-07-01")

while replay.has_next():
    candle = replay.next()
    print(f"Price: {candle.close}")

    # Your logic here
    if should_buy(candle):
        replay.buy(size=1000, stop_loss=candle.close * 0.95)

    if should_sell(candle):
        replay.close_position()

print(replay.results())
```

## Data Sources

- Crypto: CoinGecko, Binance historical (free)
- Stocks: Yahoo Finance (free)

Data is cached locally after first download.

## Philosophy

Reading about trading is not the same as trading. Trade Replay lets you:

1. **Practice decisions** under uncertainty
2. **Build pattern recognition** through repetition
3. **Test strategies** on historical data
4. **Remove hindsight bias** (you can't unknow what BTC did in 2021)

Paper trading is good. Replay trading is better - unlimited scenarios, faster iteration.

## License

MIT License