TurtleTrader (Crypto Turtle Trading with Alerts and Backtesting)

TurtleTrader is a Python implementation of a Donchian Channel breakout strategy ("Turtle" style) for BTC and other crypto pairs. It includes:

• Live signal bot that sends Telegram alerts on entries/exits.
• Backtesting with CCXT historical data (Binance) and CLI parameters.
• Configurable risk management with ATR-based sizing.

This repository is designed and tested for Python 3.13 with prebuilt wheels for key dependencies.

Features

• Donchian breakout entries using prior-N bars (classical Turtle).
• ATR-based risk sizing and affordability cap.
• Telegram notifications for live signals.
• Robust backtesting via Backtrader with CCXT data fallback.
• CLI for symbol, timeframe, start date, and parameters.

Quick Start

Clone and set up a Python 3.13 virtual environment:

python3.13 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Copy the example environment file and edit your secrets:

cp .env.example .env
# set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in .env

Live Signal Bot (Telegram)

Start the live signal bot (signals only; no order execution):

python turtle_trader.py

Default parameters are in turtle_trader.py constructor. You can change:

• symbol: default BTC/USDT
• timeframe: default 1h
• atr_period: default 20
• donchian_channel: default 20
• risk_per_trade: default 0.01 (1%)

The bot sends messages on startup, entries, and exits to your configured Telegram chat.

Backtesting

Run backtests with CCXT historical data from Binance by default, or use Yahoo (daily works, intraday is flaky):

# CCXT (recommended)
python backtest.py --source ccxt --symbol "BTC/USDT" --start 2020-01-01 --timeframe 4h --donchian 20 --atr 20 --risk 0.01

# Faster signal frequency (intraday)
python backtest.py --source ccxt --symbol "BTC/USDT" --start 2023-01-01 --timeframe 1h --donchian 10 --atr 14 --risk 0.01

# Yahoo Finance (daily only recommended)
python backtest.py --source yfinance --symbol BTC-USD --start 2020-01-01 --timeframe 1d --donchian 20 --atr 20 --risk 0.01

Command line flags:

--source      ccxt | yfinance        (default: ccxt)
--symbol      e.g., BTC/USDT (ccxt) or BTC-USD (yfinance)
--start       YYYY-MM-DD (default: 2023-01-01)
--timeframe   1h | 4h | 1d (default: 1h)
--donchian    int, Donchian window (default: 20)
--atr         int, ATR window (default: 20)
--risk        float, risk per trade fraction (default: 0.01)

Outputs:

• Logs trades to console with time, side, price, cost, and PnL.
• Saves chart to backtest_results/turtle_strategy_YYYYMMDD_HHMMSS.png.

Project Structure

.
├── backtest.py          # Backtesting engine with CCXT/yfinance loader and CLI
├── turtle_trader.py     # Live signal bot with Telegram alerts
├── requirements.txt     # Python dependencies (Python 3.13-compatible)
├── .env.example         # Template for secrets
├── .gitignore           # Git ignore rules
└── README.md            # This file

Configuration (.env)

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Optional exchange API keys (not required for signals/backtests)
EXCHANGE_API_KEY=your_api_key
EXCHANGE_SECRET=your_api_secret

Obtain a bot token from @BotFather and your chat ID from @userinfobot.

Notes on Data

• CCXT pulls Binance spot OHLCV with a rate limit; the loader pages until the requested end.
• yfinance intraday sometimes fails (JSONDecodeError). Use --source ccxt for intraday testing.
• Ensure at least ~60 bars exist for indicators.

Troubleshooting

• If import errors occur, confirm you’re in the venv and using Python 3.13:

  source venv/bin/activate
  python --version
  which python

• If yfinance returns empty data, switch to --source ccxt.
• If you see no trades, try a longer start period, --timeframe 4h or 1d, or lower --donchian.
• Telegram not receiving alerts: verify TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID and that the bot can message you (you must start a chat with the bot).

Security

• Do not commit secrets. .env is ignored by .gitignore.
• This code sends alerts only by default. To execute live orders you must add and test exchange keys and order placement logic yourself.

Disclaimer

This software is for educational purposes only and comes with no warranty. Crypto trading involves risk. Use at your own responsibility.

License

MIT

turtletrader

turtletrader