bian-saomiao/README.md

# Universe Selection Engine (USE)

一个基于币安实时数据的加密货币标的池筛选引擎，支持 **多报价币扫描** 与三种主流量化策略：**趋势跟踪**、**均值回归**、**统计套利**。

> 所有阈值、报价币、代理地址、K 线周期等参数均通过 `config/config.yaml` 管理，**零硬编码**。

---

## 一、项目特点

- ✅ **多报价币混扫**：USDT / USDC / BUSD / BTC 任选组合，一次扫描多个计价市场
- ✅ **按报价币独立阈值**：BTC 交叉盘流动性差，可单独放宽成交额门槛
- ✅ **自适应稳定币黑名单**：扫 USDC 时不会误杀 USDC 标的
- ✅ **上市天数过滤**：剔除刚上线的新币
- ✅ **K 线拉取带重试**：网络抖动不会丢失标的
- ✅ **异步并发 + 限频**：使用 `asyncio.Semaphore` 防 429 封禁
- ✅ **三种策略并行**：趋势 / 均值回归 / 统计套利

---

## 二、快速开始

### 2.1 环境要求

- Python >= 3.10
- Windows / Linux / macOS 全平台
- **代理工具**（国内访问币安 API 必需）

### 2.2 安装

```bash
cd crypto_use
pip install -r requirements.txt
```

依赖：`ccxt`, `pandas`, `numpy`, `statsmodels`, `pyyaml`, `scipy`

### 2.3 代理配置

> ⚠️ **国内直连币安 API 会被阻断，必须配置代理**。

编辑 `config/config.yaml`，修改 `exchange.proxy`：

```yaml
exchange:
  proxy: "http://127.0.0.1:7890"   # 改成你的代理地址
```

如不需要代理，填 `null`。系统会判断：有代理则注入自定义 aiohttp session（`ThreadedResolver` 绕过 aiodns DNS 失败问题），无代理则走 ccxt 默认行为。

### 2.4 运行

```bash
python main.py
```

输出结果保存到 `output/universe_results.json`。**任何目录下运行均可**，项目根路径自动锁定 `main.py` 所在位置。

---

## 三、输出说明

```json
{
    "timestamp": "2026-07-14 07:24:52",
    "timeframe": "1h",
    "quote_currencies": ["USDT", "USDC"],
    "trend_universe": ["BTC/USDT", "ETH/USDT", "BNB/USDT", ...],
    "mr_universe": [],
    "starb_pairs": []
}
```

| 字段 | 类型 | 含义 |
|------|------|------|
| `timestamp` | string | 运行时间 |
| `timeframe` | string | 使用的 K 线周期 |
| `quote_currencies` | list | 本次扫描的报价币列表 |
| `trend_universe` | list | 趋势跟踪策略标的池 |
| `mr_universe` | list | 均值回归策略标的池 |
| `starb_pairs` | list | 统计套利配对池，格式 `[["ETH/USDT", "SOL/USDT"], ...]` |

---

## 四、配置参数详解

所有参数集中在 `config/config.yaml`，共 8 个顶级字段。

### 4.1 `exchange` 交易所设置

```yaml
exchange:
  name: binance              # 交易所名称（ccxt 支持列表）
  market: spot               # spot=现货, future=U本位合约
  proxy: "http://127.0.0.1:7890"  # 代理地址，留空或 null 直连
```

### 4.2 `data` 数据设置

```yaml
data:
  timeframe: 1h              # K线周期：1m, 5m, 15m, 1h, 4h, 1d
  lookback_candles: 500      # 拉取历史K线根数
  max_concurrency: 15        # K 线并发拉取上限（防 429）
```

| 参数 | 调小 | 调大 |
|------|------|------|
| `timeframe` | 1m/5m → 捕捉短期波动，适合日内 | 1d → 过滤噪声，适合长线 |
| `lookback_candles` | 100 → 计算快但统计不显著 | 1000+ → 更稳健但增加 API 压力 |
| `max_concurrency` | 5~8 → 更安全 | 20 → 更快但易触发 429 |

### 4.3 `base_filter` 基础流动性过滤

```yaml
base_filter:
  # 报价币列表 —— 引擎会扫描所有这些计价市场，写几个就扫几个
  # 支持混配：['USDT', 'USDC'] 会同时扫 USDT 对和 USDC 对
  quote_currencies:
    - USDT
    - USDC
  # 单一计价模式（兼容老配置），如果 quote_currencies 未设置则使用此值
  quote_currency: USDT
  min_quote_volume_24h: 20000000  # 默认成交额门槛（按对应报价币计算）
  # 按报价币覆盖成交额门槛 —— 低流动性报价币可单独放宽
  # 未列出的报价币沿用 min_quote_volume_24h
  volume_thresholds:
    BTC:  50             # BTC 交叉盘流动性远低于 USDT 对
    BUSD: 5000000        # BUSD 对同样冷门
    USDC: 5000000        # USDC 对略低于 USDT
  max_spread_pct: 0.05           # 最大买卖价差 (%)
  min_listing_days: 90           # 最小上市天数（0 = 不限制）
  # 报价币对应的稳定币黑名单（不同计价场景需要不同定义）
  stablecoin_bases:
    USDT: [USDC, FDUSD, DAI, TUSD, BUSD, EUR, TRY]
    USDC: [USDT, FDUSD, DAI, TUSD, BUSD, EUR, TRY]
    BUSD: [USDT, USDC, FDUSD, DAI, TUSD, EUR, TRY]
    BTC:  [USDT, USDC, FDUSD, DAI, TUSD, BUSD, EUR, TRY, WBTC]
    USD:  [USDT, USDC, FDUSD, DAI, TUSD, BUSD, EUR, TRY]
  exclude_stablecoins: true      # 是否启用稳定币过滤
```

**核心设计**：扫 USDT 时，`USDC/FDUSD/DAI...` 这些 base 会被当作稳定币排除；扫 USDC 时不会误杀 USDC 标的；扫 BTC 时还会排除 `WBTC`（防止 WBTC/BTC 这种没意义的循环对）。

### 4.4 `trend_filter` 趋势跟踪过滤

```yaml
trend_filter:
  min_annualized_vol: 0.40    # 最小年化波动率（40%）
  min_hurst: 0.55             # 最小 Hurst 指数（>0.5 表示趋势持续）
```

### 4.5 `mean_reversion_filter` 均值回归过滤

```yaml
mean_reversion_filter:
  max_adf_pvalue: 0.05        # ADF 检验最大 p-value（<0.05 表示平稳）
  max_hurst: 0.45             # 最大 Hurst 指数（<0.5 表示反持续）
  max_kurtosis: 10.0          # 最大峰度（剔除极端肥尾/黑天鹅币）
```

### 4.6 `starb_filter` 统计套利过滤

```yaml
starb_filter:
  max_coint_pvalue: 0.05      # 协整检验最大 p-value
  # 板块分类 —— 键为板块名，值为标的列表
  # 标的格式必须为 BASE/QUOTE，必须在 quote_currencies 里有对应 quote
  sectors:
    L1:   ["ETH/USDT", "SOL/USDT", "AVAX/USDT", "ADA/USDT", "DOT/USDT", "NEAR/USDT"]
    DeFi: ["UNI/USDT", "AAVE/USDT", "MKR/USDT", "SNX/USDT", "COMP/USDT", "LDO/USDT"]
    Meme: ["DOGE/USDT", "SHIB/USDT", "PEPE/USDT", "WIF/USDT", "FLOKI/USDT", "BONK/USDT"]
    AI:   ["RNDR/USDT", "FET/USDT", "AGIX/USDT", "TAO/USDT", "ARKM/USDT"]
    # 交叉盘示例：
    # BTC_Pairs: ["ETH/BTC", "SOL/BTC", "AVAX/BTC"]
```

> ⚠️ 板块分类需要**根据市场叙事动态更新**，不是一成不变的。

### 4.7 `fetcher` K 线拉取设置

```yaml
fetcher:
  max_retries: 3              # 单个标的最大重试次数
  retry_delay: 1.0            # 重试基础间隔（秒），实际为 retry_delay × 第几次
```

### 4.8 `output` 输出设置

```yaml
output:
  save_path: "./output/universe_results.json"  # 相对路径相对项目根，也可写绝对路径
```

---

## 五、参数调优指南

### 5.1 标的池太少？→ 放宽阈值

| 场景 | 操作 |
|------|------|
| 没有任何标的过基础过滤 | 降低 `min_quote_volume_24h` 或在 `volume_thresholds` 给冷门 quote 设小门槛 |
| 趋势池为空 | 降低 `min_hurst`（如 0.55 → 0.52）或降低 `min_annualized_vol`（0.40 → 0.25） |
| 均值回归池为空 | 降低 `max_kurtosis`（10.0 → 15.0）或提高 `max_hurst`（0.45 → 0.50） |
| 套利配对为空 | 提高 `max_coint_pvalue`（0.05 → 0.10）或扩大板块覆盖 |

### 5.2 标的池太多？→ 收紧阈值

| 场景 | 操作 |
|------|------|
| 趋势池全是"死币" | 提高 `min_hurst` 到 0.60+ |
| 均值回归池出现单边下跌币 | 降低 `max_kurtosis` 到 5.0 以下 |
| 套利配对太多 | 降低 `max_coint_pvalue` 到 0.01 |

### 5.3 多报价币策略

| 需求 | 配置示例 |
|------|----------|
| 同时扫 USDT + USDC 主流市场 | `quote_currencies: [USDT, USDC]` |
| 只扫 BTC 交叉盘（量化做 BTC 对统计套利） | `quote_currencies: [BTC]` + `volume_thresholds.BTC: 50` |
| 全量扫描（不推荐，慢） | `quote_currencies: [USDT, USDC, BUSD, BTC, USD]` + 对应 `volume_thresholds` |

---

## 六、与实盘对接

### 6.1 读取结果

```python
import json
from pathlib import Path

ROOT = Path(__file__).resolve().parent
with open(ROOT / "output" / "universe_results.json", "r", encoding="utf-8") as f:
    universe = json.load(f)

trend_symbols = universe["trend_universe"]      # 趋势策略使用
mr_symbols = universe["mr_universe"]            # 均值回归策略使用
starb_pairs = universe["starb_pairs"]           # 统计套利策略使用
quote_currencies = universe["quote_currencies"] # 本次扫描的报价币
```

### 6.2 定时调度

**建议执行频率**：每天凌晨 00:00 UTC 运行一次（流动性/统计量在日内变化不大）。

**Linux cron 示例**：
```bash
0 0 * * * cd /path/to/crypto_use && /usr/bin/python main.py >> /var/log/use_cron.log 2>&1
```

**Windows 任务计划程序**：新建基本任务 → 触发器"每天 00:00" → 操作"启动程序" `python main.py`，起始于 `crypto_use` 目录。

---

## 七、项目结构

```
crypto_use/
├── config/
│   └── config.yaml              # 全局配置（零硬编码的唯一来源）
├── universe_selector/
│   ├── __init__.py
│   ├── fetcher.py               # 异步数据拉取（ccxt + 限频 + 重试）
│   ├── filters.py               # 三种策略过滤器（Hurst/ADF/Coint）
│   ├── engine.py                # 流水线控制器
│   └── utils.py                 # 统计算法辅助函数
├── output/
│   └── universe_results.json    # 筛选结果（每次运行覆盖）
├── main.py                      # 入口脚本
├── use_engine.log               # 运行日志（每次追加）
├── requirements.txt             # 依赖包
└── README.md                    # 本文件
```

---

## 八、常见问题

**Q: 运行报 DNS 错误？**
A: 确认代理 7890 端口已启动，且 `config.yaml` 的 `exchange.proxy` 已正确填写。本项目在有代理时会自动注入 `ThreadedResolver`，绕过 aiodns 在代理环境下的 DNS 失败问题。

**Q: 报 429 限频？**
A: 降低 `data.max_concurrency` 到 8~10；或降低 `fetcher.max_retries` 减少重试风暴。

**Q: 某些标的 K 线拉不到？**
A: 项目对每个标的自动重试 3 次（指数退避），最终失败会在日志中输出 ERROR 但不中断流程。如大量失败，检查网络或降低并发。

**Q: 均值回归池一直是空的？**
A: 这是正常现象。`max_hurst < 0.45 + ADF p < 0.05 + kurtosis < 10` 三条件同时满足的标的在币安全市场现货里极少。降低 `max_kurtosis` 到 15+ 或提高 `max_hurst` 到 0.50 试试。

**Q: 统计套利配对一直是 0？**
A: 在 `starb_filter.sectors` 里扩大板块覆盖，或提高 `max_coint_pvalue` 到 0.10。

**Q: 想扫描 BTC 交叉盘但出不了标的？**
A: 在 `base_filter.volume_thresholds.BTC` 设置小门槛（如 50 BTC）。BTC 交叉盘流动性远低于 USDT 对，必须单独配置门槛。

**Q: 想看某币是因什么原因被过滤掉的？**
A: 当前版本未提供 verbose 调试模式。如需要可临时将 `fetcher.py` 中 `get_liquid_symbols` 的循环里加 `print(f"[skip] {symbol}: 原因")`。

**Q: 支持合约市场吗？**
A: 支持。把 `exchange.market` 改成 `future` 即可。但注意币安合约 API 的 ticker 字段与现货略有差异，可能需要根据实际情况微调。

**Q: 在哪个目录运行 main.py？**
A: 任意目录均可。项目根路径通过 `Path(__file__).resolve().parent` 自动锁定，配置/输出/日志路径与 cwd 无关。

---

## 九、扩展开发

### 9.1 新增一种策略过滤器

在 `universe_selector/filters.py` 的 `StrategyFilters` 类里添加新方法，例如：

```python
def filter_breakout(self, data_dict: dict[str, pd.DataFrame]) -> list[str]:
    """突破策略：检测近期价格是否突破 N 日高点"""
    universe = []
    for sym, df in data_dict.items():
        close = df['close'].values
        high_20d = close[:-1][-20*24:].max()  # 前 20 天最高
        if close[-1] > high_20d:
            universe.append(sym)
    return universe
```

然后在 `engine.py` 的 `run_pipeline` 中调用：
```python
results['breakout_universe'] = self.filters.filter_breakout(data_dict)
```

### 9.2 接入实盘自动下单

引擎输出 `output/universe_results.json` 后，下游策略可订阅文件变化（`watchdog` 库）或定时轮询，将新标的池与持仓比对，自动调整下单白名单。

---

## 十、版本

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0 | 2026-07 | 初始版本（USDT only） |
| 1.1 | 2026-07 | 多报价币 / 按 quote 独立门槛 / 上市天数 / K 线重试 / 路径稳健化 |

---

## 十一、许可

仅供学习和研究使用。加密货币交易有风险，请自行评估。