# Trader Bot — CLAUDE.md

Bot de trading ICT (Order Block + Liquidity Sweep) avec interface web.

## Architecture

```
trader-bot/
├── backend/          # Python / FastAPI
│   ├── app/
│   │   ├── main.py                          # Entry point FastAPI
│   │   ├── core/
│   │   │   ├── config.py                    # Paramètres via .env
│   │   │   ├── database.py                  # SQLAlchemy async + SQLite
│   │   │   ├── exchange/
│   │   │   │   ├── base.py                  # AbstractExchange interface
│   │   │   │   └── oanda.py                 # Implémentation OANDA
│   │   │   ├── strategy/
│   │   │   │   ├── base.py                  # AbstractStrategy + dataclasses
│   │   │   │   └── order_block_sweep.py     # Stratégie ICT principale
│   │   │   ├── backtester.py                # Moteur backtest
│   │   │   └── bot.py                       # BotRunner asyncio
│   │   ├── models/                          # SQLAlchemy (Candle, Trade, BacktestResult)
│   │   ├── services/
│   │   │   ├── market_data.py               # Fetch + cache candles
│   │   │   └── trade_manager.py             # Position sizing + exécution
│   │   └── api/
│   │       ├── routes/                      # GET/POST endpoints
│   │       └── websocket.py                 # WS broadcast manager
│   ├── requirements.txt
│   └── .env                                 # Clés OANDA (NE PAS COMMITER)
└── frontend/         # React / TypeScript / Vite
    └── src/
        ├── components/Chart/                # CandlestickChart (lightweight-charts)
        ├── components/Dashboard/            # BotStatus, PnLSummary, TradeList
        ├── components/Backtest/             # BacktestForm, BacktestResults
        ├── pages/                           # Dashboard.tsx, Backtest.tsx
        ├── hooks/useWebSocket.ts            # WS auto-reconnect
        └── lib/api.ts                       # Axios client typé
```

## Stack technique

- **Backend** : Python 3.11+, FastAPI, SQLAlchemy async, oandapyV20, pandas, pandas-ta
- **Frontend** : React 18, TypeScript, Vite, Tailwind CSS, lightweight-charts (TradingView)
- **Base de données** : SQLite (fichier `backend/trader_bot.db`)
- **Exchange** : OANDA v20 REST API (environment practice/live via `.env`)

## Commandes de développement

### Backend
```bash
cd backend
pip install -r requirements.txt
# Copier et configurer les variables d'environnement
cp .env.example .env
# Remplir OANDA_API_KEY et OANDA_ACCOUNT_ID dans .env
uvicorn app.main:app --reload --port 8000
```

### Frontend
```bash
cd frontend
npm install
npm run dev   # http://localhost:5173
```

## Configuration OANDA

Variables dans `backend/.env` :
- `OANDA_API_KEY` : clé API (Settings → API Access sur fxpractice.oanda.com)
- `OANDA_ACCOUNT_ID` : ID du compte (format `001-004-XXXXXXX-001`)
- `OANDA_ENVIRONMENT` : `practice` (paper trading) ou `live`

Pour retrouver l'Account ID après démarrage du backend :
```
GET http://localhost:8000/api/bot/status
```
Ou via curl vers l'API OANDA :
```
curl -H "Authorization: Bearer <API_KEY>" https://api-fxpractice.oanda.com/v3/accounts
```

## Instruments supportés

| Instrument | Description |
|---|---|
| EUR_USD | Euro / Dollar |
| GBP_USD | Livre / Dollar |
| USD_JPY | Dollar / Yen |
| SPX500_USD | S&P 500 (CFD) |
| NAS100_USD | Nasdaq 100 (CFD) |
| XAU_USD | Or / Dollar |

## Stratégie — Order Block + Liquidity Sweep (ICT/SMC)

### Logique de détection (order_block_sweep.py)

1. **Swing Detection** : swing high/low sur `swing_strength` bougies de chaque côté
2. **Equal Highs/Lows** : deux swings proches (< `liquidity_tolerance_pips`) = pool de liquidité
3. **Liquidity Sweep** : wick qui dépasse le niveau ET close de l'autre côté
4. **Order Block** : dernière bougie bearish avant impulse haussière (bullish OB) / inverse
5. **Signal** : sweep confirmé + prix revient dans la zone OB
6. **SL** : au-delà de l'OB · **TP** : R:R fixe (`rr_ratio`)

### Paramètres configurables

| Param | Défaut | Description |
|---|---|---|
| `swing_strength` | 5 | N bougies de chaque côté pour valider un swing |
| `liquidity_tolerance_pips` | 2.0 | Tolérance Equal H/L en pips |
| `rr_ratio` | 2.0 | Ratio Risk/Reward cible |
| `min_impulse_candles` | 3 | Bougies min dans l'impulsion |
| `min_impulse_factor` | 1.5 | Taille impulsion vs corps moyen |

## API Endpoints

| Method | Route | Description |
|---|---|---|
| GET | `/api/candles` | Candles OANDA (params: instrument, granularity, count) |
| GET | `/api/trades` | Historique des trades (params: source, status) |
| POST | `/api/backtest` | Lance un backtest, retourne métriques + trades |
| GET | `/api/backtest/history` | 20 derniers backtests |
| GET | `/api/bot/status` | État du bot |
| POST | `/api/bot/start` | Démarrer le bot |
| POST | `/api/bot/stop` | Arrêter le bot |
| WS | `/ws/live` | Stream events temps réel |

## Roadmap / TODO

- [ ] Remplir `OANDA_ACCOUNT_ID` dans `backend/.env`
- [ ] Tester la connexion OANDA (`GET /api/candles?instrument=EUR_USD`)
- [ ] Valider la détection des Order Blocks sur données réelles
- [ ] Afficher les zones OB et niveaux de liquidité sur le chart (overlay)
- [ ] Ajouter le support multi-timeframe (HTF pour context + LTF pour entrée)
- [ ] Implémenter le trailing stop-loss
- [ ] Ajouter des notifications (email/telegram) sur les trades
- [ ] Ajouter tests unitaires pour la stratégie