第 2 章 · 03 交易对与白名单黑名单

第 2 章 · 03 交易对与白名单黑名单

本节摘要:机器人能买哪些币?这由「白名单/黑名单」机制决定。本节讲透 Pairlist 体系:最简单的 StaticPairList(写死一份列表)与最常用的 VolumePairList(按成交量动态筛选),以及用多个过滤器串联成 Pairlist Handlers 链的做法。黑名单用于在白名单之上再做一次「永久排除」。读完本节,你能根据交易风格配置出静态、动态、混合三种白名单,并理解每个过滤器把哪些币留下了、哪些剔除了。

内容来源:原项目文档 docs/configuration.md 的 pairlist 部分、docs/plugins.md,汉化并套用体系化模板。

⚠️ 风险提示:动态白名单(尤其 VolumePairList)会把高成交量的「热门山寨币」自动纳入——它们波动剧烈、流动性可能瞬间枯竭。务必配合黑名单排除已知高风险币种,并控制 max_open_trades。

学习目标

阅读完本节,你应当能够:

1. 说清 Pairlist 机制在主循环中的角色。
2. 配置 StaticPairList(静态白名单)。
3. 配置 VolumePairList(按成交量动态筛选)。
4. 理解 Pairlist Handlers 链:多过滤器串联如何工作。
5. 使用常见过滤器:AgePairlist、PercentPrice、SpreadFilter。
6. 配置 黑名单与精准/正则两种匹配方式。

一、白名单的角色:主循环第二步

回忆第 01 节,FreqtradeBot.process() 的第二步就是「刷新白名单」——确定本轮迭代要为哪些交易对下载行情、跑策略。白名单是「所有后续工作的输入」:

💡 核心心法:白名单先「粗筛」到几十个,再由策略「精筛」出几个真正下单的——分工明确。把策略放在几百个对上跑既慢又无意义,先用白名单收紧范围。

二、StaticPairList:写死一份列表

最简单的方式——把要交易的币写死在配置里:

"pairlists": [{"method": "StaticPairList"}],
"exchange": {
    "name": "binance",
    "pair_whitelist": ["BTC/USDT", "ETH/USDT", "BNB/USDT"]
}
​

特点:

• 列表写死,每次刷新都一样,不随市场变化。
• 适合「只盯几个我懂的对」的交易者。
• 缺点:某个币下架、长期停牌时不会自动剔除,需要手动维护。

⚠️ 必须使用交易对的完整规范名:BTC/USDT(现货)或 ETH/USDT:USDT(合约)。写错大小写或漏掉 :settle 会被引擎当作「不存在的对」直接报错。

三、VolumePairList:按成交量动态筛

更常用的方式——按指定 quote 货币(如 USDT)下,近 N 个周期平均成交量排序,自动取前若干名:

"pairlists": [
    {
        "method": "VolumePairList",
        "number_assets": 20,
        "sort_key": "quoteVolume",
        "min_value": 0,
        "refresh_period": 1800,
        "lookback_days": 7,
        "lookback_timeframe": "1d"
    }
]
​

关键参数:

特点:

• 自动适应市场:新热门币会进,凉了的山寨会出。
• 适合「永远跟着流动性走」的 Trend-following 思路。
• 缺点:会把高成交量的妖币/拉盘币纳入,需配合下游过滤器或黑名单。

四、Pairlist Handlers 链:串联多个过滤器

pairlists 段是一个列表——可以放多个 handler,引擎会按顺序应用每一个。第一个必须是「生产者」(如 StaticPairList、VolumePairList),后续都是「过滤器」(Filter),每个都拿前一个的输出再筛一次。

"pairlists": [
    {"method": "VolumePairList", "number_assets": 50, "lookback_days": 7},
    {"method": "AgePairlist", "min_days_listed": 30},
    {"method": "PercentPrice", "max_price_change": 200, "min_price_change": -50, "refresh_period": 86400},
    {"method": "SpreadFilter", "max_spread_ratio": 0.005}
]
​

这条链做的事:取成交量前 50 → 排除上市不足 30 天的新币 → 排除一年内涨超 200% 或跌超 50% 的「极端币」 → 排除买卖盘价差超 0.5% 的「流动性差」币。

常见过滤器速览

五、黑名单:永久排除某些对

黑名单写在 exchange.pair_blacklist,作用在白名单之上——任何白名单阶段产生的对,只要命中黑名单就最终被剔除。支持正则:

"exchange": {
    "pair_blacklist": [
        "BNB/.*",                       // 排除所有 BNB 计价的对
        ".*DOWN/USDT",                  // 排除所有杠杆代币
        ".*UP/USDT",
        "(BTC|ETH)/USDT:.*",            // 合约下排除 BTC、ETH
        "PEPE/USDT"                     // 精准排除某个币
    ]
}
​

使用场景:

• 永久不想碰的币:已知 rug 风险的 meme、项目方有问题的代币。
• 结构化排除:所有杠杆代币(UP/DOWN)、所有非主流计价币(BNB/.*)。
• 合约/现货差异:不同交易模式下排除不同的对。

💡 黑名单 vs 白名单的分工:白名单「圈定池子」,黑名单「在池子里勾掉」。两者配合使用——白名单用 VolumePairList 自动选,黑名单手工排除其中你不想碰的。

六、Pair Lock:临时锁定的另一种「黑名单」

除了黑名单,还有一种临时的「单对锁定」——通过 Telegram /locks 命令或策略代码 PairLocks.lock_pair(pair, until) 临时锁定某个对一段时间。锁定期内机器人既不开新仓也不管理该对。常用于「这个币近期有异常,先别碰」的场景,详见第 10 章。

本节要点回顾

1. 角色:白名单是主循环第二步的输出,决定后续下载行情与跑策略的范围;先粗筛再让策略精筛。
2. StaticPairList:写死一份列表,适合只盯几个币,需手动维护。
3. VolumePairList:按 lookback_days 内的 quoteVolume 排序取前 N,自动跟随流动性。
4. Handlers 链:pairlists 是有序列表,首项是生产者、后续是过滤器(Age/PercentPrice/Spread 等),层层收敛。
5. 黑名单:exchange.pair_blacklist 支持精准与正则,作用在白名单之上做最终排除。
6. Pair Lock:PairLocks.lock_pair 临时锁单对,适合短期异常币,与黑名单互补。

下一章我们正式进入「策略开发基础」——先从 populate_indicators 开始,用 pandas 与 TA-Lib 实打实地算几类常用技术指标。