# quant-bot

Hummingbot V2 风格的加密量化交易 bot（币安 USDT-M 永续，5m），参考
`/data/app/dylan/trending-web` 的趋势网格研究与生产策略 v5_d48 构建。

## ⚠️ 首要结论（真实数据回测，2026-01-01 数据，费率 0.035%）

| 策略 | 区间 | 交易数 | 收益 | PF | 胜率 | 最大回撤 | 裁决 |
|---|---|---:|---:|---:|---:|---:|---|
| vol_breakout | 训练 01-01~05-01 | 74 | **+22.27%** | 1.47 | 64.9% | -13.46% | ✅ 通过 |
| vol_breakout | 验证 05-01~07-10 | 36 | **+3.31%** | 1.15 | 55.6% | -10.23% | ✅ 通过 |
| trend_grid | 训练 01-01~05-01 | 1658 | **-24.90%** | 0.62 | 50.6% | -25.05% | ❌ 否决 |
| trend_grid | 验证 05-01~07-10 | 853 | **-7.95%** | 0.73 | 51.9% | -8.01% | ❌ 否决 |

### vol_breakout 高波动币对扩展测试（2026-07-17）

| 币对组合 | 训练 01-01~05-01 | 验证 05-01~07-10 | 裁决 |
|---|---|---|---|
| 四大主流（基准） | +22.27% / PF 1.47 / DD -13.5% | +3.31% / PF 1.15 / DD -10.2% | ✅ |
| 高波动 6 对（WIF/PEPE/SUI/DOGE/XRP/AVAX） | +4.42% / PF 1.06 / DD **-23.5%** | +5.45% / PF 1.12 / DD -18.7% | ⚠️ 正但薄、回撤大 |
| 混合 10 对 | +12.74% / PF 1.17 / DD -17.2% | **-0.64%** / PF 1.00 / DD -12.2% | ❌ 验证段被稀释 |

逐对拆解（01-01~07-10 合并）：DOGE +127U / SUI +95U / XRP +21U 盈利；
AVAX -6U / PEPE -50U / WIF -81U 亏损。**波动最高的 meme 对（WIF/PEPE）
假突破噪音最大，趋势策略同样受伤**——币对扩展需逐对筛选，不能整组加入。

### trend_grid 变体压力测试（均带越界冷却 12h）

| 变体 | 币对 | 训练 | 验证 | 裁决 |
|---|---|---|---|---|
| 2x 单向（基准复测） | 四大主流 | -17.45% / PF 0.73 | — | ❌ |
| 2x 单向 | 高波动组（WIF/PEPE/SUI/DOGE） | **-43.60%** / PF 0.81 | -12.58% / PF 0.67 | ❌ 更差 |
| 5x 多空双开 | 四大主流 | **-99.71%**（爆仓） | — | ❌ 灾难 |
| 5x 多空双开 | 高波动组 | **-98.72%**（爆仓） | -95.40% | ❌ 灾难 |

结构证据（高波动组 2x 训练段）：止盈 1172 笔平均 +0.18U 合计 +210U；
越界 660 笔平均 -0.40U 合计 -262U。**单笔越界=单笔止盈的 2.21 倍**，
且越界在趋势段成簇出现。高波动同时放大止盈频率与越界幅度，后者更快。

trend_grid 的亏损结构与 trending-web 研究文档完全一致：979 笔反弹止盈
被 679 笔越界亏损压倒——**均值回归网格的尾部盈亏结构问题，不是参数问题**。
该结论复现了原项目「不部署任何网格候选」的裁决。trend_grid 代码保留仅作
研究复现，请勿实盘。

## 架构（Hummingbot V2 风格）

```
Controller（信号层）          Executor（执行层）           Context（记账/撮合）
─────────────────           ──────────────────           ─────────────────
VolatilityBreakout  ──信号──▶ PositionExecutor ──────────▶ 三重屏障出场
  Donchian48+ATR扩张            趋势仓位+trailing            硬止损-5%/trail3%(5%)
  ADX>25+EMA200+BTC200DMA      ATR风险定仓/敞口限制
TrendGrid           ──配置──▶ GridExecutor ──────────────▶ 分层限价成交
  EMA48中心+ADX12~35            冻结边界/库存递减3:2:1:1      越界退出/48h时限
  +滚动区间+BTC200DMA           禁无限马丁
```

信号在第 t 根收盘产生，t+1 根成交；网格限价单触及 high/low 即成交
（保守假设，无 maker 排队优势）；双边计费。

## 目录

```
bot/
  models.py                  # Order/Position/TradeRecord/Side/CloseType
  indicators.py              # ATR(Wilder)/ADX/EMA/Donchian，纯 pandas
  executors/base.py          # ExecutorBase + ExecutionContext（保证金/费用记账）
  executors/grid.py          # GridExecutor（冻结边界、分层账本、越界退出）
  executors/position.py      # PositionExecutor（三重屏障）
  strategies/base.py         # ControllerBase
  strategies/trend_grid.py   # 趋势网格（研究复现，已否决）
  strategies/volatility_breakout.py  # v5_d48 移植（生产逻辑）
backtest/
  engine.py                  # 事件驱动回测，因果时序，权益曲线
  report.py                  # 交易数/收益/PF/胜率/回撤/平仓分布
scripts/
  download_data.py           # data.binance.vision → data/*.csv
  run_backtest.py            # 回测 CLI（--strategy/--start/--end/--fee）
  run_paper.py               # dry-run 实时循环（只模拟，不下单）
tests/test_grid.py           # 网格撮合/边界/权重/指标因果性
```

## 使用

```bash
pip install -r requirements.txt

# 1) 下载数据（本机直连 fapi.binance.com 受限，走公开数据仓库）
python scripts/download_data.py --pairs BTC/USDT:USDT --timeframe 1d --start 2025-04-01
python scripts/download_data.py --pairs BTC/USDT:USDT ETH/USDT:USDT \
    SOL/USDT:USDT BNB/USDT:USDT --timeframe 5m --start 2025-12-20

# 2) 回测（训练/验证分段，与 trending-web 协议一致）
python scripts/run_backtest.py --strategy vol_breakout --start 2026-01-01 --end 2026-05-01
python scripts/run_backtest.py --strategy vol_breakout --start 2026-05-01 --end 2026-07-10
python scripts/run_backtest.py --strategy trend_grid  --start 2026-01-01 --end 2026-05-01
# 费率压力测试（网格 edge 对成本极敏感，0.05% 即全线转负）
python scripts/run_backtest.py --strategy trend_grid --fee 0.0005 --start 2026-05-01 --end 2026-07-10

# 3) dry-run 实时（只模拟成交，不下单；fapi 受限，K 线走 data-api.binance.vision 现货镜像）
python scripts/run_paper.py --strategy vol_breakout

# 4) 测试
python -m pytest tests/ -q
```

## 与 trending-web 的口径差异

- 本引擎只用 5m K 线，无 freqtrade 的 `--timeframe-detail 1m` 明细撮合；
  网格在同一根 5m 内的多格成交顺序是近似的。
- vol_breakout 的绝对数值与 freqtrade 生产回测（训练 +18.97%/PF 1.14、
  验证 +14.25%/PF 1.23）有差异：成交建模（交易所 stop-market vs K 线极值
  近似）、白名单（12 对 vs 本回测 4 对）、regime.json 实时总闸未参与回测。
  方向性结论一致。
- trend_grid 参数取研究第二轮风格（step=1 ATR、bound=3.25 格、单层反弹
  止盈一格），非最佳候选的精调参数；但「越界尾损压倒止盈」的否决机制不变。

## 安全约定

- 不提供实盘下单路径；`run_paper.py` 只模拟成交。如需实盘，API key 放
  `.env`（参考项目 Secrets 规范），并先完成 maker 成交建模与滑点审计。
- trend_grid 保留仅为研究复现；其「部署」需新证据（可验证 maker 成交模型
  或显著降低越界尾损的机制），见原项目文档。