# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Freqtrade BTC/USDT bot on the 1h timeframe. Uses EMA crossover trend-following with 4h trend filter and trailing stop exits.

## File Structure

```
├── docker-compose.yml          # freqtrade + download-data services
├── config.json                 # Exchange, pairs, stake, API server
├── CLAUDE.md
└── user_data/
    ├── strategies/
    │   ├── BTC_1h.py           # EMA crossover strategy
    │   └── TrendStructureExecutor.py  # 5m trend-continuation strategy
    ├── data/                   # Downloaded OHLCV data (gitignored)
    └── backtest_results/       # Backtest results (gitignored)
```

## Commands

### Download data
```bash
docker compose run --rm freqtrade download-data --exchange binance --pairs BTC/USDT --timeframe 1h 4h --days 400
```

### Backtest
```bash
docker compose run --rm freqtrade backtesting --strategy BTC1h --timeframe 1h --timerange 20251201-
```

### Hyperopt
```bash
docker compose run --rm freqtrade hyperopt --strategy BTC1h --timeframe 1h --epochs 500 --spaces buy sell stoploss
```

### Start live/dry-run
```bash
docker compose up -d
```

### View logs
```bash
docker compose logs -f
```

### Stop
```bash
docker compose down
```

## Configuration Notes

- Dry-run is enabled by default (`dry_run: true`). Set to `false` and add exchange API key/secret to `exchange.key` / `exchange.secret` to trade live.
- The API server runs on `127.0.0.1:8080`. Default credentials: `freqtrader` / `changeme`.
- Data and backtest results persist in `user_data/` across restarts.

## Strategy (BTC1h)

| Aspect | Detail |
|--------|--------|
| **Type** | Trend-following EMA crossover |
| **Entry** | 4h price > EMA50 + 1h price > EMA200 + 12 EMA crosses above 26 EMA |
| **Exit** | 12 EMA crosses below 26 EMA, or trailing stop at +1% after +2.5% peak |
| **Stop** | -2.5% fixed |
| **Performance** | +1.89 USDT in 157 days (BTC dropped 6.7%). 27 trades, 37% win rate, 0.29% drawdown. Winners avg +2.48%, losers avg -1.24%. |

The strategy is asymmetric: it wins big (trailing stop at +2.48% avg on 37% of trades) and loses small (exit signal at -1.24% avg on 63%). It loses on most trades but profits overall.