Freqtrade list-pairs 命令完全指南：查询、过滤与多格式输出交易所交易对

本篇技术指南基于 Freqtrade 仓库中 docs/commands/list-pairs.md 的命令参考文档展开，系统讲解 freqtrade list-pairs 子命令的完整用法、全部命令行参数、四种输出格式，并结合仓库源码剖析其底层实现（市场加载、币种过滤、活跃度判定、最小下单量与最大杠杆计算），帮助你快速摸清任一交易所可用的交易对，为编写 trading_pair_whitelist 配置或调试 pairlist 策略提供可直接复制的实操方案。

1. 命令概览与完整帮助信息

list-pairs 是 Freqtrade 提供的只读工具命令之一，用于列出指定交易所上可交易的交易对（pair）。它与 list-markets 共享同一套参数与实现，区别仅在于 list-pairs 只输出 pair 形态的市场，而 list-markets 输出交易所全部市场（见 docs/utils.md 中 "List pairs/list markets" 章节）。

docs/commands/list-pairs.md 收录了该命令完整的 --help 输出，原文如下，这也是本指南的参数骨架：

usage: freqtrade list-pairs [-h] [-v] [--no-color] [--logfile FILE] [-V]
                            [-c PATH] [-d PATH] [--userdir PATH]
                            [--exchange EXCHANGE] [--print-list]
                            [--print-json] [-1] [--print-csv]
                            [--base BASE_CURRENCY [BASE_CURRENCY ...]]
                            [--quote QUOTE_CURRENCY [QUOTE_CURRENCY ...]] [-a]
                            [--trading-mode {spot,margin,futures}]

options:
  -h, --help            show this help message and exit
  --exchange EXCHANGE   Exchange name. Only valid if no config is provided.
  --print-list          Print list of pairs or market symbols. By default data
                        is printed in the tabular format.
  --print-json          Print list of pairs or market symbols in JSON format.
  -1, --one-column      Print output in one column.
  --print-csv           Print exchange pair or market data in the csv format.
  --base BASE_CURRENCY [BASE_CURRENCY ...]
                        Specify base currency(-ies). Space-separated list.
  --quote QUOTE_CURRENCY [QUOTE_CURRENCY ...]
                        Specify quote currency(-ies). Space-separated list.
  -a, --all             Print all pairs or market symbols. By default only
                        active ones are shown.
  --trading-mode, --tradingmode {spot,margin,futures}
                        Select Trading mode

Common arguments:
  -v, --verbose         Verbose mode (-vv for more, -vvv to get all messages).
  --no-color            Disable colorization of hyperopt results. May be
                        useful if you are redirecting output to a file.
  --logfile, --log-file FILE
                        Log to the file specified. Special values are:
                        'syslog', 'journald'. See the documentation for more
                        details.
  -V, --version         show program's version number and exit
  -c, --config PATH     Specify configuration file (default:
                        `userdir/config.json` or `config.json` whichever
                        exists). Multiple --config options may be used. Can be
                        set to `-` to read config from stdin.
  -d, --datadir, --data-dir PATH
                        Path to the base directory of the exchange with
                        historical backtesting data. To see futures data, use
                        trading-mode additionally.
  --userdir, --user-data-dir PATH
                        Path to userdata directory.

关键点：该命令不连接真实 API 密钥，只需知道"哪个交易所"即可——要么通过配置文件 -c（读取其中的 exchange 配置段），要么在没给配置文件时直接用 --exchange 指定。这一点从源码可以确认：list-pairs 子命令在 freqtrade/commands/arguments.py 中通过 partial(start_list_markets, pairs_only=True) 注册，即 list-pairs 就是 list-markets 的"仅 pair"变体；而 start_list_markets 内部使用 RunMode.UTIL_EXCHANGE 初始化交易所对象（freqtrade/commands/list_commands.py），因此属于"需要交易所市场数据、但无需账户权限"的 utils 命令。

2. 参数详解：过滤器与输出格式

2.1 交易所与市场范围过滤器

参数	作用	源码依据
-c, --config PATH	从配置文件读取交易所信息（默认查找 userdir/config.json 或 config.json）。可用 - 从 stdin 读取	docs/commands/list-pairs.md
--exchange EXCHANGE	直接指定交易所名称，仅在未提供配置文件时有效	同上
--base BASE [BASE ...]	按基础币种过滤，空格分隔多个币种（如 --base BTC ETH）	cli_options.py
--quote QUOTE [QUOTE ...]	按计价币种过滤（如 --quote USDT USD）	cli_options.py
-a, --all	输出所有交易对（含非 active 的）；默认只输出 active 的交易对	cli_options.py
--trading-mode {spot,margin,futures}	选择交易模式，影响加载哪些市场数据（如期货数据需要配合此参数）	docs/commands/list-pairs.md

从源码结构看，--base 与 --quote 过滤发生在 start_list_markets 调用 exchange.get_markets() 时（list_commands.py），而 get_markets 的实现是逐层字典推导式过滤：先按 v["base"] in base_currencies、v["quote"] in quote_currencies 缩小范围，再做 tradable_only 与 active_only 过滤（freqtrade/exchange/exchange.py）。多个币种之间是"或"关系（属于列表中任一个即可），而 base 与 quote 两个维度之间是"与"关系。

"active" 的判定逻辑在 freqtrade/exchange/exchange_utils.py：market.get("active", True) is not False——只要交易所没有把 active 显式标记为 false，就视为活跃。这与 docs/utils.md 中 "By default, only active pairs/markets are shown. Active pairs/markets are those that can currently be traded on the exchange" 的说明一致。

此外，list-pairs 传入的是 tradable_only=True（pairs_only=True 映射到 get_markets 的 tradable_only 参数），因此无法被 Freqtrade 交易的市场（如价格精度低于 1e-11 的市场）会被直接排除。docs/utils.md 明确指出："Pairs may be listed as untradeable if the smallest tradeable price for the market is very small, i.e. less than 1e-11"。该判定对应 exchange.py 中 market_is_tradable() 里的精度检查。

2.2 输出格式参数（四选一）

参数	输出形态	适用场景
默认（不带格式参数）	Rich 表格，含 Id/Symbol/Base/Quote/Active/Spot/Margin/Future/Leverage/Min Stake 十列	人工审阅、可视化筛选
--print-list	单行逗号分隔列表 + 汇总行	快速复制全部 symbol
-1, --one-column	每行一个 symbol	管道处理、脚本循环
--print-json	JSON 数组	程序解析、与其他工具链对接
--print-csv	CSV（带表头）	导入 Excel/数据库

这几种格式的分支逻辑集中在 start_list_markets：

• --print-list 打印 f"{summary_str}: {', '.join(pairs.keys())}"，即先输出汇总（哪个交易所、多少个、按什么币种过滤），再跟逗号分隔的 symbol 列表；
• --print-json 使用 rapidjson.dumps(list(pairs.keys()), default=str) 输出，是纯字符串数组（不含市场明细）；
• --print-csv 用 csv.DictWriter 输出完整十列明细；
• 默认表格模式通过 print_rich_table 输出。

有一个便于脚本化的细节：当使用 -1、--print-json、--print-csv 这类机器可读格式时，汇总字符串改走 logger.info() 写入日志，而不是打印到 stdout（list_commands.py），保证 stdout 是干净的单一格式数据，可直接 > file.json 重定向。

2.3 表格输出的十列含义

默认表格模式的列定义见 list_commands.py：

列	取值来源	说明
Id	ccxt 市场 id	交易所原始市场 ID（部分交易所为数字 ID）
Symbol	ccxt symbol	如 ETH/USDT
Base / Quote	ccxt base / quote	基础币种 / 计价币种
Active	market_is_active(v)	是否当前可交易
Spot / Margin / Future	exchange.market_is_spot/margin/future(v)	该市场支持的类型标记，命中才显示文字
Leverage	exchange.get_max_leverage(v["symbol"], 20)	该交易对支持的最大杠杆（spot 模式恒为 1.0；futures 按杠杆档位表 _leverage_tiers 查找，见 exchange.py）
Min Stake	exchange.get_min_pair_stake_amount(symbol, 最新价)	按 ticker 最新价（last，回退 ask）换算的最小下单金额，保留 8 位小数（list_commands.py）

其中 Min Stake 一列对实盘配置尤其有用：它能帮你直接判断某个交易对在你计划的使用金额下是否"买得起"。注意该值依赖 exchange.get_tickers() 实时行情，行情获取失败时按 0.0 回退（safe_value_fallback），此时该列可能显示 0，属于数据缺省而非真实最小值。

market_is_spot / market_is_margin / market_is_future 的判定见 exchange.py：spot 要求 market["spot"] is True；futures 则要求是 swap 且 linear 合约。因此同一张表可以同时区分现货与线性合约市场，配合 --trading-mode futures 加载期货数据后可直接查看合约对。

3. 实战示例

以下示例继承自 docs/utils.md 的 "List pairs/list markets" 章节，均基于上文参数说明可直接运行。

示例 1：JSON 输出默认配置文件中交易所（Binance）的 active 且 quote 为 USD 的交易对

$ freqtrade list-pairs --quote USD --print-json

示例 2：输出 config_binance.json 中交易所的全部（含非 active）交易对，base 限定 BTC/ETH，quote 限定 USDT/USD，以人类可读列表加汇总的形式打印

$ freqtrade list-pairs -c config_binance.json --all --base BTC ETH --quote USDT USD --print-list

示例 3：表格模式输出 Kraken 全部市场（使用 list-markets 变体）

$ freqtrade list-markets --exchange kraken --all

示例 4：Docker 环境下免密钥查询（来自 docs/docker_quickstart.md）

像 list-pairs 这类不需要认证信息的命令，可以不用 docker compose，直接用 docker run 拉官方镜像执行：

docker run --rm freqtradeorg/freqtrade:stable list-pairs --exchange binance --quote BTC --print-json

文档指出这适合"抓取交易所信息来填充 config.json，而不影响正在运行的容器"的场景。

示例 5：结合 test-pairlist 生成回测用静态白名单

list-pairs 回答"交易所有什么"，而 docs/utils.md 中的 test-pairlist 命令回答"我的 pairlist 插件配置最终产出什么白名单"。典型工作流是：先用 list-pairs 确认目标 symbol 存在且 active，再用 freqtrade test-pairlist --config config.json --quote USDT BTC 校验动态 pairlist 的输出，最后把结果固化为回测/超参优化使用的静态白名单。

4. 特殊场景与注意事项

• 交易所特殊市场：以 Hyperliquid 为例，docs/exchanges.md 提示 HIP-3 DEX 市场的 pair 命名与普通 pair 不同，"Please use list-pairs subcommand to get the correct pair naming"——即特殊交易所市场应以本命令输出为准，不要凭经验拼 symbol。
• 期货数据：帮助信息中 -d, --datadir 提到 "To see futures data, use trading-mode additionally"。查询合约市场时加 --trading-mode futures，Leverage 列才会基于杠杆档位表给出有意义的值。
• spot 模式杠杆恒为 1：从 get_max_leverage 的实现看，TradingMode.SPOT 直接返回 1.0；futures 模式会按 stake_amount（表格模式固定传 20）匹配杠杆档位，若该 pair 不在 _leverage_tiers 中则回退为 1.0。
• 输出按 symbol 排序：start_list_markets 中 pairs = dict(sorted(pairs.items())) 保证输出按 symbol 字符串排序（与 docs/utils.md "Pairs/markets are sorted by its symbol string in the printed output" 一致），便于 diff 与重复执行结果对比。
• 获取市场失败的兜底：若交易所市场加载异常，命令会抛出 OperationalException(f"Cannot get markets. Reason: {e}")（list_commands.py），此时通常意味着网络/代理问题或 --exchange 名称拼写错误，可先用 list-exchanges -1 确认可用交易所名称。

5. 小结

list-pairs 是 Freqtrade 中与交易所交互的"侦察兵"命令：它以 RunMode.UTIL_EXCHANGE 初始化交易所对象，通过 Exchange.get_markets() 完成 base/quote/tradable/active 四重过滤，再以 Rich 表格、逗号列表、单列、JSON、CSV 五种形态输出，表格中还附带最小下单金额与最大杠杆两个实盘关键指标。理解它背后的 market_is_active、market_is_tradable、get_min_pair_stake_amount 等函数（freqtrade/exchange/exchange_utils.py、freqtrade/exchange/exchange.py），你就能准确解释输出中的每一列，并据此正确挑选交易对、配置 trading_pair_whitelist 与 stake_currency。