# CLAUDE.md

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

## Project Overview

Freqtrade BTC 1h trading bot. Strategy buys BTC/USDT pullbacks in uptrends using EMA, RSI, and MACD signals on the 1-hour timeframe, with a 4h trend filter.

## File Structure

```
├── docker-compose.yml          # Defines freqtrade + download-data services
├── config.json                 # Exchange, pairs, stake, API server settings
├── CLAUDE.md
└── user_data/
    └── strategies/
        └── BTC_1h.py           # The trading strategy class
```

## Commands

### Start trading (dry-run, default)
```bash
docker compose up -d
```

### Start live trading (after configuring API keys in config.json)
```bash
docker compose up -d
```

### Download historical data
```bash
docker compose run --rm download-data
```

### Download data for custom pairs/timeframes
```bash
docker compose run --rm freqtrade download-data --exchange binance --pairs BTC/USDT ETH/USDT --timeframe 1h 4h --days 365
```

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

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

### 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 trade live.
- The API server runs on `127.0.0.1:8080` (not exposed externally).
- Data persists in `user_data/` across container restarts.
- Update `pair_whitelist` in `config.json` to trade additional pairs.

## Strategy (BTC1h)

- **Timeframe**: 1h with 4h trend filter
- **Entry**: 4h bullish + pullback to short EMA + RSI dip + MACD turning up + volume confirmation
- **Exit**: RSI overbought or MACD bearish cross
- **Hyperoptable**: EMA periods, RSI thresholds