trade-replay 0.1.0

Practice trading without hindsight bias. Replay historical price action.

Trade Replay

Practice trading without hindsight bias. Learn by doing.

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

pip install trade-replay

Quick Start

# 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

trade-replay start BTC --from 2021-11-01 --to 2021-12-01

Replay a specific period. Good for studying known events.

Random Mode

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

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

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)

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

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

Track Progress

# 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

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