使用 DefiLlama 与 CoinGecko 构建 DeFi 链上数据管道：machine-learning-for-trading 的 TVL 替代数据实战
【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading
在《Machine Learning for Trading》第三版（本仓库 machine-learning-for-trading）中，第 4 章用真实公开的链上数据演示"替代数据（alternative data）"如何进入量化研究流程。本指南围绕 data/crypto/onchain/README.md 展开，完整讲解两路免密钥公开数据源（DefiLlama 的 DeFi 总锁仓量 TVL、CoinGecko 的币种日频价格/成交量）的获取、落盘、加载与消费方式。读完本文，你将能够一键拉取链上指标到本地 parquet 存储，通过统一 Loader API 读取并用于信号研究，并复现第 4 章完整的替代数据评估框架。
数据集概览：两条免费、免密钥的链上数据源
该数据集定位是"公共善品（public-good）"链上指标，专门服务于第 4 章"理解替代数据"一节中关于如何评估交易 alpha 替代数据的教学场景。两个数据源均为公共 API、无需 API Key：
| 数据源 | 内容 | 粒度 | 历史范围 |
|---|---|---|---|
| DefiLlama | 全链聚合 TVL 与分链 TVL | 日频 | 数年（可回溯至 DeFi 行业起步阶段） |
| CoinGecko | 币种每日价格 + 成交量（OHLCV 精简版） | 日频 | 免费档上限 365 天 |
下载器把两个源的原始 HTTP 响应统一归一化为单频率 parquet 文件（见 download.py），使笔记本通过load_defillama_chain_tvl()与load_coingecko_ohlcv()即可消费，而无需在任何 notebook 里写网络请求代码。
默认拉取（1 个全链 TVL + 4 个分链 TVL + 1 个 ETH 价格文件）磁盘占用小于 5 MB，运行时间不超过 1 分钟。
许可与成本边界
- DefiLlama：公共 API，无 Key、无公开限速。数据按开放数据库许可（
ODbL-1.0）发布；在公开发表的作品中使用该数据时，必须注明出处 "DefiLlama"。 - CoinGecko：免费档 Public API。免费档将历史限制为 365 天，吞吐量约 10–50 次请求/分钟，并有署名要求。
这两条边界不是细节，而是第 4 章评估框架中"法律（Legal）"硬门槛的直接输入：数据本身是公开的链上状态聚合，不构成重大非公开信息，但商用或再分发需遵守各自许可。
下载：一键脚本与全部 CLI 参数
默认使用uv run执行下载脚本（仓库采用 uv 管理 Python 环境）：
# 默认：全链总 TVL + 4 条主要链 + ETH 价格 uv run python data/crypto/onchain/download.py # 仅 DefiLlama（全链总 TVL + 分链） uv run python data/crypto/onchain/download.py --dataset defillama # 仅 ETH 价格 uv run python data/crypto/onchain/download.py --dataset coingecko # 自定义链集合 uv run python data/crypto/onchain/download.py --chains Ethereum,Solana,Arbitrum # 换一个币（CoinGecko id，小写） uv run python data/crypto/onchain/download.py --dataset coingecko --coins bitcoin对照源码 download.py 的 argparse 定义，完整参数表如下：
| 参数 | 默认值 | 说明 |
|---|---|---|
--dataset | both | 可选defillama/coingecko/both |
--chains | Ethereum,Solana,BSC,Arbitrum | 逗号分隔的链名；传空字符串跳过分链（源码中DEFAULT_CHAINS） |
--skip-total | False | 跳过全链聚合 TVL 序列 |
--coins | ethereum | 逗号分隔的 CoinGecko 币 id（自动转小写，源码中DEFAULT_COINS） |
--days | 365 | CoinGecko 回溯窗口天数（免费档上限 365） |
--data-path | $ML4T_DATA_PATH | 覆盖输出根目录 |
输出位置由resolve_data_dir()决定（utils/downloading.py），优先级为：CLI 参数--data-path>ML4T_DATA_PATH环境变量 /.env> 仓库默认data/目录。最终文件落在$ML4T_DATA_PATH/crypto/onchain/下：
| 文件 | 来源 | 内容 |
|---|---|---|
defillama_tvl_total.parquet | DefiLlama | 全链聚合 TVL |
defillama_tvl_<chain>.parquet | DefiLlama | 分链 TVL（如ethereum、solana） |
coingecko_<coin>.parquet | CoinGecko | 日频price_usd、volume_usd（365 天窗口） |
所有文件采用统一规范 schema：timestamp（Date 类型）加一个或两个数值列。实现细节：DefiLlama 的两个端点https://api.llama.fi/v2/historicalChainTvl（聚合）与https://api.llama.fi/v2/historicalChainTvl/{chain}（分链）返回秒级 epoch，下载器用pl.from_epoch(..., time_unit="s").cast(pl.Date)归一为日期；CoinGecko 的/coins/{id}/market_chart返回毫秒级 epoch 的prices与total_volumes数组，用毫秒级转换并排序。
加载：统一 Loader API 与缺失提示
数据加载通过 data/crypto/loader.py 中两个加载器完成，它们在 data/init.py 中被导出：
from data import load_defillama_chain_tvl, load_coingecko_ohlcv total_tvl = load_defillama_chain_tvl() # 全链聚合 eth_tvl = load_defillama_chain_tvl("Ethereum") eth_px = load_coingecko_ohlcv() # ETH，默认 btc_px = load_coingecko_ohlcv("bitcoin")load_defillama_chain_tvl(chain="total")：chain参数匹配文件名后缀（自动小写），默认"total"返回全链聚合，传入"Ethereum"、"Solana"、"BSC"、"Arbitrum"等返回对应分链；返回timestamp（Date）与tvl_usd（float）两列。load_coingecko_ohlcv(coin="ethereum")：默认 ETH；返回timestamp（Date）、price_usd、volume_usd三列。
若请求的 parquet 缺失，加载器会抛出DataNotFoundError（定义于 data/exceptions.py），错误信息中直接给出可复制的完整下载命令，包括正确的--chains/--coins参数。例如缺失某分链时会提示data/crypto/onchain/download.py --dataset defillama --chains {chain}，缺失某币价时会提示... --dataset coingecko --coins {coin}，并附上readme=data/crypto/onchain/README.md的完整说明路径；异常还会报告当前解析到的数据根目录及其来源（环境变量 /.env/ 默认），避免读者在错误的数据目录下反复重下。
限速处理与刷新策略
- DefiLlama：无文档化上限，下载器采用串行请求、无人工延迟。
- CoinGecko：免费档约 10–50 次请求/分钟。下载器在币与币之间默认 sleep 2 秒（源码常量
COINGECKO_SLEEP = 2.0），足以覆盖第 4 章所用的少量币种；需要更多币种时应提升套餐额度或提供演示用 API Key。
对 CoinGecko 而言，免费档窗口固定 365 天，load_coingecko_ohlcv的 docstring 明确提示"重新运行下载器即可刷新"。同时 notebook 中有一个值得一提的数据细节：CoinGecko 免费档会在当日午夜 bar 之上追加一条实时盘中快照，导致最后一天可能重复出现，消费方需要按timestamp去重保留最后一行（09_onchain_fundamentals.py用unique(subset="timestamp", keep="last")，11_defi_tvl_evaluation.py用group_by("timestamp").agg(pl.col(...).last())处理）。
消费端：第 4 章两个实战 Notebook
该数据集在第 4 章（04_fundamental_alternative_data）被两个 notebook 消费：
- NB 09 — 09_onchain_fundamentals.py：链上基本面入门。核心假设是"资金流入 DeFi 先于以太坊价格上涨"，围绕 TVL 与 ETH 价格构建特征：
- 将 TVL 水平值转换为动量特征（
tvl_growth，30 日 pct_change）、标准化水平（tvl_zscore，90 日滚动 z-score）与三档 regime（expansion/neutral/contraction，以REGIME_Z = 1.0个标准差为界，z-score 未满窗口期置空而非归入中性档）； - 用价格两端直接计算前向收益（
shift(-FORWARD_DAYS) / price - 1，默认 30 日），强调不能用平移尾随收益代替； - 由于日频采样与 30 日前向窗口的重叠，所有统计量都用Newey-West HAC 协方差（
maxlags = FORWARD_DAYS - 1）修正，并统计"样本中真正独立的 30 日窗口数量"（len(tested) / FORWARD_DAYS），得出关键结论：制约研究的不是 TVL 序列（全历史免费），而是价格免费档的 365 天窗口。
- 将 TVL 水平值转换为动量特征（
- NB 11 — 11_defi_tvl_evaluation.py：完整尽职调查案例，把替代数据评估拆成四个问题——信号（Signal）、数据（Data）、法律（Legal）、商业（Commercial）：
- 信号：3 种信号定义 × 4 个前向窗口（7/14/30/60 天）共 12 对关系，全部用 HAC 修正 t 统计量，并做 180 日滚动相关性看稳定性；结论是"未能证实而非证伪"——12 次测量中最大 |t| 仍不足以越过阈值，且滚动相关性在一年内变号；
- 数据：审计缺失天数、空值与单日极端变动（阈值 20%），发现极端变动几乎都集中在 2020 年前的增长期，应按日期过滤而非按水平值过滤；
- 法律：硬门槛。数据源自公开链上状态聚合，不构成重大非公开信息，许可要求署名，禁止将原始数据作为产品再分发；
- 商业：按 AUM（1 千万到 50 亿美元）计算盈亏平衡 alpha（bps），集成成本假设为一次性 40 小时 + 每年 20 小时工程维护、150 美元/小时；
- 最终裁决：数据干净、许可宽松、成本低，但DefiLlama 不提供历史 vintage（历史版本）快照，序列会被持续重述，因此"数据"维度构成硬门槛，正确动作是从今天开始每日快照建库，一年后再回来重测信号。
延伸阅读
- 同一仓库的加密市场数据（Binance 永续合约与资金费率溢价指数）见 data/crypto/README.md 与 data/crypto/market/download.py，其加载器（
load_crypto_perps、load_crypto_premium）与链上加载器同属于 data/crypto/loader.py，共用相同的DataNotFoundError缺失提示机制。 - 仓库所有数据加载器的统一入口与完整清单见 data/init.py；数据目录总览见 data/README.md。
- 环境安装与数据路径配置说明见 docs/installation.md 与 docs/running-notebooks.md。
通过本指南，你可以零成本、免密钥地复现第 4 章从数据拉取、本地缓存、Loader 读取到替代数据四维评估的完整链路，并在自己的研究环境中把同样的评估框架迁移到任意新的替代数据源上。
【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
