第 5 章 · 01 历史数据下载

第 5 章 · 01 历史数据下载

本节摘要:本节讲清 freqtrade 数据获取的第一步——用 download-data 命令从交易所拉取历史 K 线(OHLCV)。回测、Hyperopt、Dry-Run 启动时算指标,都离不开历史数据。本节先讲命令的最小用法(指定交易所、币种、周期、时间范围),再逐项拆解关键参数:--exchange / --pairs / --timeframes / --days / --timerange,以及现货与合约场景下的 --trading-mode 与 --candle-type。最后讲增量更新、--prepend 向前补数据、用正则一次拉全 USDT 交易对等实用技巧。读完本节,你能为任意交易所、任意币种、任意周期下载到干净连续的历史数据。

内容来源:原项目文档 docs/data-download.md,汉化并套用体系化模板。

学习目标

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

1. 用 download-data 命令从交易所下载历史 K 线。
2. 正确组合 exchange / pairs / timeframes / days / timerange 五个核心参数。
3. 区分 trading-mode(spot/futures)与 candle-type(spot/futures/mark/index)。
4. 用 增量更新 与 --prepend 维护连续的长历史数据。
5. 用 正则 一次下载某个计价币的全部交易对。

一、为什么先下数据

量化交易「垃圾进,垃圾出」——回测和 Hyperopt 把历史 K 线喂给策略,策略才能算指标、产信号。download-data 是这一切的入口:

下载好的数据存放在 user_data/data/<exchange>/ 下,文件名形如 BTC_USDT-5m-feather(默认 feather 格式,见第 02 节)。Dry-Run 虽然用实时行情,但策略启动时算指标(比如 200 周期均线)需要一段历史铺垫,所以也要先下数据。

二、最小命令

不带任何额外参数时,download-data 默认下载 1m 和 5m、最近 30 天的数据,交易所和币种从配置文件读:

freqtrade download-data --exchange binance
​

如果没配置文件,--exchange 是必填项。Docker 用户把 freqtrade 换成 docker compose run --rm freqtrade。

更常见的是显式指定币种和周期:

freqtrade download-data \
    --exchange binance \
    --pairs BTC/USDT ETH/USDT \
    --timeframes 5m 1h \
    --days 30
​

三、核心参数逐项拆解

💡 相对 vs 绝对:--days 30 是「从今天往前 30 天」,适合增量更新(每周跑一次 --days 8);--timerange 20260101- 是「从 2026 年 1 月 1 日到今天」,适合一次性拉一段固定历史。

四、trading-mode 与 candle-type

现货和合约的数据不一样,freqtrade 用两个参数区分:

下载合约数据:

freqtrade download-data \
    --exchange binance \
    --pairs BTC/USDT:USDT ETH/USDT:USDT \
    --timeframes 5m \
    --trading-mode futures \
    --days 60
​

注意合约交易对通常带 :USDT 后缀(隔离合约的命名约定)。合约模式下,freqtrade 会自动把 mark、funding_rate 等必要 candle type 一起拉下来,除非你显式用 --candle-types 覆盖。

⚠️ 数据要「对齐」:回测、Hyperopt、Dry-Run 用的交易所、周期、币种、trading-mode 必须和策略预期完全一致。混交易所、混周期会导致指标失真,产出虚假信号。

五、增量更新与向前补数据

download-data 是增量的——如果磁盘上已有数据,它会自动只下载缺失部分,不会重下整段:

# 周一跑一次,补足到今天(无需 --days / --timerange)
freqtrade download-data --exchange binance --pairs BTC/USDT ETH/USDT --timeframes 5m
​

如果你想往已有数据的更早之前补数据,用 --prepend(配合 --timerange 指定结束点):

# 已有 2022 至今的数据,现在想补 2021 这一整年
freqtrade download-data --exchange binance \
    --pairs BTC/USDT ETH/USDT --timeframes 5m \
    --prepend --timerange 20210101-20220101
​

--prepend 模式下,freqtrade 会自动把结束时间对齐到已有数据的起点,避免重叠。

如果你在已有数据上新增了交易对,老的币种只想增量、新币种想下整段,用 --new-pairs-days:

freqtrade download-data --exchange binance --pairs BTC/USDT SOL/USDT --new-pairs-days 365
​

BTC/USDT 只补最近缺失;SOL/USDT(新加入)下最近 365 天。

六、用正则一次拉全部 USDT 交易对

很多场景下你想把某交易所「所有 USDT 计价的活跃币」一次拉下来,用正则简写:

freqtrade download-data --exchange binance --pairs ".*/USDT" --timeframes 5m --days 30
​

".*/USDT" 会被展开成该交易所所有 XXX/USDT 活跃交易对。如果连已下架的币也要,加 --include-inactive-pairs。

💡 慎拉全量:某交易所可能有上千个 USDT 交易对,1m 周期拉一年动辄几十 GB。先小范围验证策略,再决定要不要全量。

七、pairs.json:配置之外的备用清单

除了配置文件里的白名单,你也可以在 user_data/data/<exchange>/pairs.json 放一份纯交易对清单:

[
    "ETH/BTC",
    "ETH/USDT",
    "BTC/USDT",
    "XRP/ETH"
]
​

只有在没加载配置时它才会被使用;推荐还是用配置里的 exchange.pair_whitelist 或 pairs 字段,更可控。

八、用 list-data 确认下载结果

下完之后,用 list-data 查看本地有哪些数据(第 03 节详讲):

freqtrade list-data --userdir user_data/
​

输出会列出每个币种的可用周期和类型,确认下载覆盖了策略所需。

九、trades 数据(高级,慎用)

download-data 默认拉 OHLCV K 线。少数场景(如 Kraken 不提供历史 OHLCV)需要拉逐笔成交(trades),用 --dl-trades,再用 trades-to-ohlcv 重采样成各周期:

freqtrade download-data --exchange kraken --pairs XRP/EUR ETH/EUR --days 20 --dl-trades
freqtrade trades-to-ohlcv --exchange kraken -t 5m 1h --pairs BTC/EUR ETH/EUR
​

⚠️ 不要无脑用 trades:绝大多数交易所直接提供 OHLCV,比逐笔 trades 快得多、小得多。只有 Kraken 这种没有历史 OHLCV 的才需要走 trades 路径。

本节要点回顾

1. 命令入口:download-data 是 freqtrade 数据获取的统一入口,数据落 user_data/data/<exchange>/,默认 feather 格式。
2. 五个核心参数:--exchange(交易所)、--pairs(币种)、--timeframes(周期)、--days(相对)/--timerange(绝对)、--datadir(目录)。
3. 现货 vs 合约:--trading-mode spot/futures 切换;合约会自动补 mark / funding_rate;合约交易对常带 :USDT 后缀。
4. 增量更新:已下数据会自动只补缺失;--prepend 配 --timerange 向前补;--new-pairs-days 区分新老币。
5. 正则拉全量:--pairs ".*/USDT" 展开该交易所全部 USDT 活跃币;加 --include-inactive-pairs 含下架币。
6. list-data 验收:list-data 列出本地数据,确认覆盖策略需求。
7. trades 慎用:只有 Kraken 等无历史 OHLCV 的交易所才走 --dl-trades + trades-to-ohlcv 路径。

下一节,我们看数据落盘的格式——feather / json / jsongz / parquet 各有优劣,以及如何在格式之间互相转换。