Freqtrade list-markets 命令详解：查询交易所全部交易市场的参数、输出格式与源码实现

list-markets 是 Freqtrade 提供的市场数据查询工具，用于打印指定交易所上所有「交易品种（market）」的清单，包括现货、杠杆与永续合约市场，并附带杠杆上限、最小下单金额等关键字段。本文完整覆盖该命令的全部命令行参数与输出格式，并结合 list_commands.py 与 exchange.py 等源码剖析其过滤逻辑与数据列的生成原理，帮助你在策略开发前期快速筛选候选交易对。

命令定位：list-markets 与 list-pairs 的区别

list-markets 与 list-pairs 共用同一套参数选项（ARGS_LIST_PAIRS），在 arguments.py 中分别注册为两个子命令：

• list-markets：set_defaults(func=partial(start_list_markets, pairs_only=False)) —— 打印全部市场（含合约、杠杆等非可交易对）；
• list-pairs：set_defaults(func=partial(start_list_markets, pairs_only=True)) —— 仅打印 Freqtrade 判定为可交易的交易对。

两者的差异由 start_list_markets 的第二个参数 pairs_only 控制，该参数会透传给底层 exchange.get_markets() 的 tradable_only 过滤条件（见下文源码分析）。因此：需要评估全交易所市场结构时用 list-markets，需要快速拿到可配置进策略的交易对清单时用 list-pairs。

完整命令行参数说明

官方文档 list-markets.md 收录了该命令的完整帮助输出，以下逐条说明其用法与取值：

usage: freqtrade list-markets [-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}]

市场筛选参数

参数	说明
--exchange EXCHANGE	指定交易所名称。仅在未提供配置文件时有效；如果提供了 config，则从 config 的 exchange 配置读取
--base BASE_CURRENCY [BASE_CURRENCY ...]	按基础币种过滤，支持空格分隔的多币种列表，如 --base BTC ETH
--quote QUOTE_CURRENCY [QUOTE_CURRENCY ...]	按计价币种过滤，如 --quote USDT
-a, --all	打印全部市场符号。默认只显示 active（活跃）市场；加上该参数后已下架/暂停的市场也会展示

输出格式参数

参数	说明
--print-list	以逗号分隔的列表形式打印市场符号（附带汇总行），默认为表格形式
--print-json	以 JSON 数组形式打印市场符号，便于脚本解析
-1, --one-column	每行一个符号的纯文本输出，适合管道处理
--print-csv	以 CSV 格式打印完整市场数据（含表头），可直接导入表格工具
--trading-mode {spot,margin,futures}	选择交易模式，影响交易所初始化行为（如需查看期货数据需配合 --datadir 与配置）

通用参数（Common arguments）

参数	说明
-v, --verbose	详细日志级别（-vv 更多，-vvv 全部）
--no-color	禁用输出着色，重定向到文件时有用
--logfile, --log-file FILE	日志写入文件；支持 syslog、journald 特殊值
-V, --version	打印版本号后退出
-c, --config PATH	指定配置文件（默认为 userdir/config.json 或 config.json 中先存在者），可多次指定合并，- 表示从 stdin 读取
-d, --datadir, --data-dir PATH	历史回测数据基础目录；查看期货数据时需额外指定 --trading-mode
--userdir, --user-data-dir PATH	指定用户数据目录

这些选项在 cli_options.py 中以 Arg 结构定义：--print-list、--print-json、--print-csv 均为 store_true 开关，--base/--quote 使用 nargs="+" 因此接受空格分隔的多币种。

典型用法示例

查看 Binance 上全部 USDT 计价市场（默认仅活跃市场）：

freqtrade list-markets --config config.json --quote USDT

只保留 BTC 作为基础币种，且包含非活跃市场：

freqtrade list-markets --config config.json --base BTC --all

不依赖配置文件，直接指定交易所（等价于测试/CI 场景）：

freqtrade list-markets --exchange binance --print-list

导出为 CSV 供进一步分析：

freqtrade list-markets --config config.json --print-csv > markets.csv

管道中仅取市场符号列表：

freqtrade list-markets --config config.json --one-column
# 或 JSON：
freqtrade list-markets --config config.json --print-json

单元测试 test_commands.py 中 test_list_markets 验证了这些行为：未提供交易所配置时会抛出 OperationalException: This command requires a configured exchange...；提供 --exchange binance 时输出类似 Exchange Binance has 12 active markets 的汇总行；加 --all 后同一测试数据集中市场数从 12 变为 14，印证了「默认只显示 active 市场」的行为。

源码剖析：市场过滤与输出列生成

核心调用链

命令入口在 start_list_markets，整体流程为：

1. setup_utils_configuration(args, RunMode.UTIL_EXCHANGE) 初始化配置——由于是 UTIL_EXCHANGE 运行模式，该命令会真实连接交易所拉取市场元数据（区别于纯本地工具命令）；
2. ExchangeResolver.load_exchange(config, validate=False) 加载交易所实例；
3. 读取 --all（list_pairs_all）决定 active_only；读取 --base/--quote 得到币种过滤列表；
4. 调用 exchange.get_markets(base_currencies=..., quote_currencies=..., tradable_only=pairs_only, active_only=active_only) 获取市场字典，并按符号排序。

过滤逻辑：get_markets

Exchange.get_markets 是实际的过滤实现，它对 ccxt 加载的 markets 字典做链式过滤：

def get_markets(
    self,
    base_currencies: list[str] | None = None,
    quote_currencies: list[str] | None = None,
    spot_only: bool = False,
    margin_only: bool = False,
    futures_only: bool = False,
    tradable_only: bool = True,
    active_only: bool = False,
) -> dict[str, Any]:

• --base/--quote 分别匹配 v["base"]、v["quote"] 字段；
• tradable_only（即 list-pairs 的 pairs_only=True）通过 market_is_tradable 过滤——该检查要求 base/quote 非空，并校验价格精度不能过低（exchange.py），各交易所可覆写此方法增加特判（例如 kraken.py 会排除 darkpool 交易对）；
• active_only 由 market_is_active 判定，规则为：active 字段未显式设为 False 即视为活跃（缺失或为 true 均算活跃）。

表格输出列的生成

表格模式（默认输出）的列由 start_list_markets 硬编码，每一列的取值来源如下：

列名	来源
Id / Symbol / Base / Quote	ccxt 市场对象字段
Active	market_is_active(v)
Spot / Margin / Future	分别由 exchange.market_is_spot/margin/future 判定，命中才显示对应标签
Leverage	exchange.get_max_leverage(symbol, 20)——以 20 USDT 权益估算该市场当前可获取的最大杠杆；现货模式恒为 1.0（见 get_max_leverage）
Min Stake	exchange.get_min_pair_stake_amount(...)，价格取自实时 ticker 的 last/ask 价，结果保留 8 位小数

其中 market_is_future 的判定条件是 swap 类型且 linear 为真（exchange.py），即只有线性永续合约会被标为 Future。

输出格式的分支逻辑

代码末尾按优先级选择输出分支（list_commands.py）：

1. --print-list → 打印 汇总行: SYMBOL1, SYMBOL2, ... 单行；
2. --one-column → 每行一个符号；
3. --print-json → 使用 rapidjson 输出符号数组；
4. --print-csv → 用 csv.DictWriter 输出表头 + 完整 9 列数据；
5. 默认 → print_rich_table 渲染 Rich 表格。

值得注意：选择机器可读格式（one-column/json/csv）时，汇总行改为写入日志（logger.info）而非 stdout，保证 stdout 只有纯净的数据流——这正是这些格式适合接入脚本管道的设计意图。

适用前提与限制

• 该命令需要在线连接交易所（RunMode.UTIL_EXCHANGE），无法离线使用；--exchange 仅在未提供 --config 时生效，二者同时给出时以 config 为准（--exchange 参数帮助文本亦明确注明 "Only valid if no config is provided"）。
• Min Stake 依赖实时 ticker 数据，若某市场无 ticker 记录，价格会回退为 0.0，该列数值仅供参考。
• Leverage 列以 20 的权益值估算，与 get_max_leverage 的实际杠杆档位规则一致；现货模式下恒显示 1.0。
• 结合 list-timeframes 等兄弟命令，可覆盖「交易所支持什么市场 → 什么时间周期 → 配置哪些交易对」的策略前期调研全流程。

小结

freqtrade list-markets 以极少参数覆盖了市场调研的常见需求：--base/--quote 做币种过滤，--all 放开活跃限制，--print-list/--print-json/--one-column/--print-csv 四种输出形式兼顾人类阅读与自动化管道。从源码看，其核心是 Exchange.get_markets 的一组正交过滤器（币种、tradable、active、交易模式），输出表格中的 Leverage 与 Min Stake 列则复用了下单前的风控计算逻辑，因此该命令的输出生成结果可直接用于评估候选交易对是否符合最小仓位约束。