# Binance Futures AI Trading Bot

A systematic crypto futures trading bot powered by Claude (Anthropic) as the AI decision engine, with quant-research-backed signal filters and volatility-targeted position sizing.

---

## What it does

Every 5 minutes the bot:
1. Scans 10 approved high-liquidity USDT perpetual pairs
2. Runs a free rule-based filter (ADX regime, Efficiency Ratio, EMA stack, MACD, RSI, Z-score)
3. Calls Claude only on the top 2 scoring symbols (cost control)
4. Opens / manages positions with ATR-based stop-loss, 1:3 R:R take-profit, and trailing stops

---

## Architecture

```
config/settings.py          — all config knobs, .env loading
data/fetcher.py             — Binance Futures REST (OHLCV, account, positions)
features/indicators.py      — ADX, Efficiency Ratio, RSI, MACD, BB, ATR, OBV, VWAP, Z-score
features/feature_engineer.py— assembles 51-feature matrix from OHLCV
signals/generator.py        — two-phase pipeline: free rules → Claude confirmation
models/claude_trader.py     — Claude API integration, structured JSON output
risk/risk_manager.py        — volatility-targeted sizing, SL/TP, daily/drawdown guards
risk/position_advisor.py    — adaptive leverage/sizing via Claude (fallback table for small accounts)
execution/order_manager.py  — full trade lifecycle, position health, trailing SL, rotation
monitoring/                 — Rich console logging, Telegram alerts, performance CSV
backtesting/                — event-driven backtest engine with Claude signal sampling
web/app.py                  — Flask dashboard at http://localhost:8080
scripts/main.py             — CLI entry point
```

---

## Quant techniques used

| Technique | Source | Purpose |
|-----------|--------|---------|
| ADX regime filter | Wilder (1978) | Only trade in trending markets (ADX > 20) |
| Kaufman Efficiency Ratio | Kaufman (1995) | Skip choppy price action (ER < 0.20) |
| Volatility targeting | Hurst, Ooi & Pedersen (2012) | Scale position size inversely with realized vol |
| Z-score entry timing | Standard quant practice | Enter on pullbacks, not extended moves |
| ATR-based SL/TP | Wilder (1978) | Adaptive stop distances (1.5× and 4.5× ATR) |
| Two-phase Claude calls | Cost optimization | Free rules first, Claude only on top candidates |

---

## Setup

### 1. Clone & install

```bash
git clone https://github.com/yourusername/binance-futures-ai-bot.git
cd binance-futures-ai-bot
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
```

### 2. Configure

```bash
cp .env.example .env
# fill in your API keys:
#   BINANCE_API_KEY, BINANCE_API_SECRET  — from Binance Futures
#   ANTHROPIC_API_KEY                    — from console.anthropic.com
#   TELEGRAM_TOKEN, TELEGRAM_CHAT_ID     — optional, for trade alerts
```

### 3. Run (testnet first — always)

**Option A — Web dashboard (recommended):**
```bash
python web/app.py
# open http://localhost:8080
# toggle Testnet, click Start
```

**Option B — CLI:**
```bash
python scripts/main.py          # testnet (safe default)
python scripts/main.py --live   # live trading — only after testing!
```

> ⚠️ Testnet requires separate testnet API keys from https://testnet.binancefuture.com

---

## Configuration (config/settings.py)

| Parameter | Default | Description |
|-----------|---------|-------------|
| `TIMEFRAME` | `4h` | Candle interval |
| `SYMBOLS` | 10 pairs | Approved high-liquidity pairs |
| `MAX_OPEN_POSITIONS` | 2 | Max simultaneous trades |
| `RISK_PER_TRADE_PCT` | 0.02 | 2% equity risk per trade |
| `DEFAULT_LEVERAGE` | 3x | Near-spot leverage |
| `STOP_LOSS_ATR_MULT` | 1.5 | SL = 1.5 × ATR |
| `TAKE_PROFIT_ATR_MULT` | 4.5 | TP = 4.5 × ATR (1:3 R:R) |
| `DAILY_LOSS_LIMIT_PCT` | 0.08 | Halt if daily loss > 8% |
| `MAX_DRAWDOWN_PCT` | 0.20 | Halt if drawdown > 20% |
| `TRADE_MAX_HOLD_HOURS` | 48 | Exit dead trades after 48h |
| `LOOP_INTERVAL_SEC` | 300 | Scan every 5 minutes |

---

## Signal entry criteria

**LONG** — needs 3+ of 5:
1. Price above EMA200 (uptrend)
2. RSI 30–45 or crossing above 50 with momentum
3. MACD histogram positive, line above signal
4. Volume ≥ 1.5× 20-period average
5. Price pulling back to support / EMA level

**Hard gates** (always HOLD):
- ADX < 20 (choppy market)
- Efficiency Ratio < 0.20 (price going nowhere)
- 24h move > 8% in trade direction (chasing)
- RSI > 72 / < 28 (overextended)
- Claude confidence < 68%

---

## Cost control

With the default 5-minute loop and 1-hour Claude cache:
- ~2 Claude calls per 5-min cycle max
- Estimated API spend: ~$3–8/month (Haiku model)
- Position Advisor skips Claude for accounts < $500

---

## Backtesting

```bash
python scripts/backtest.py --symbol BTCUSDT --days 90
```

---

## Testing

```bash
pytest tests/ -v
```

---

## Risk disclaimer

This software is for educational and research purposes. Crypto futures trading involves significant risk of loss. Past performance does not guarantee future results. Never trade with money you cannot afford to lose. Always test on testnet first.

---

## License

MIT License — see [LICENSE](LICENSE)