本文介绍如何通过调用 coincodex 官方未公开但可直接访问的 api 端点，稳定获取加密货币市场总值等高频时序图表数据，并将其结构化为 pandas dataframe，支持批量扩展与定时采集。
CoinCodex 的交互式图表（如全币种总市值曲线）虽未提供公开文档化的 API，但其前端实际通过 https://coincodex.com/api/v1/assets/get_charts 接口动态加载数据。该接口无需认证密钥，仅需构造合理参数即可返回 JSON 格式的时序数据，非常适合自动化采集用于模型训练的特征数据。
以下是一个完整、可复用的 Python 示例：
import pandas as pd
import requests
from datetime import datetime
def fetch_chart_data(
assets: str = "SUM_ALL_COINS",
include: str = "market_cap",
samples: str = "md", # 'sm' (small), 'md' (medium), 'lg' (large) — controls point density
charts: str = "ALL"
) -> pd.DataFrame:
"""
从 CoinCodex 抓取指定资产的图表数据
:param assets: 资产标识符，如 'BTC', 'ETH', 'SUM_ALL_COINS'
:param include: 数据类型，如 'market_cap', 'price', 'volume'
:param samples: 采样粒度（影响时间点数量），'md' 通常含 300+ 历史点
:param charts: 图表类型，'ALL' 表示全部时间范围
:return: 包含 Date, Value, Cap 列的 DataFrame（Cap 仅在 market_cap 场景下有效）
"""
api_url = "https://coincodex.com/api/v1/assets/get_charts"
# t 参数为时间戳（毫秒级），但实测该字段对响应无实质影响（服务端可能忽略或用作缓存键）
# 可固定使用任意合法值（如当前时间戳）或省略（部分请求中可不传）
params = {
"charts": charts,
"samples": samples,
"assets": assets,
"include": include,
# "t": str(int(datetime.now().timestamp() * 1000)) # 可选：动态时间戳
}
headers = {
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}
try:
response = requests.get(api_url, params=params, headers=headers, timeout=15)
response.raise_for_status()
data = response.json()
# 注意：响应结构为 {asset_id: {chart_type: [...data...]}}，例如 data["SUM_ALL_COINS"]["ALL"]
# 若请求多个 assets（逗号分隔），则需遍历；此处单 asset 简化处理
if assets not in data:
raise KeyError(f"Asset '{assets}' not found in API response. Available keys: {list(data.keys())}")
chart_data = data[assets].get(charts, [])
if not chart_data:
raise ValueError(f"No chart data returned for assets='{assets}', charts='{charts}'")
df = pd.DataFrame(chart_data, columns=["Date", "Value", "Cap"])
df["Date"] = pd.to_datetime(df["Date"], unit="s") # 时间戳单位为秒（非毫秒）
return df.sort_values("Date").reset_index(drop=True)
except requests.exceptions.RequestException as e:
raise ConnectionError(f"Failed to fetch data from {api_url}: {e}") from e
except (KeyError, ValueError, TypeError) as e:
raise RuntimeError(f"Unexpected API response format: {e}") from e
# ✅ 使用示例：获取全币种总市值历史数据
df_marketcap = fetch_chart_data(
assets="SUM_ALL_COINS",
include="market_cap",
samples="md"
)
print("✅ 全币种总市值（最近5条）：")
print(df_marketcap.tail())
# ✅ 批量采集示例：多资产 + 多指标
for asset in ["BTC", "ETH", "SOL"]:
try:
df_price = fetch_chart_data(assets=asset, include="price", samples="md")
print(f"\n? {asset} 价格数据形状: {df_price.shape}")
# 可保存为 CSV 或写入数据库
# df_price.to_csv(f"{asset}_price_history.csv", index=False)
except Exception as e:
print(f"⚠️ 获取 {asset} 数据失败: {e}")? 关键注意事项：
- 参数敏感性：assets 必须严格匹配 CoinCodex 内部 ID（如 "BTC" 而非 "bitcoin"）；可通过浏览器 Network 面板观察真实请求确认。
- 时间戳单位：Date 字段为 Unix 秒级时间戳（不是毫秒），务必使用 unit="s" 解析。
- 采样策略：samples=md 平衡精度与数据量（约 200–400 点）；lg 更密集但可能触发限流，sm 过于稀疏（仅 ~50 点）。
- 稳定性保障：添加 User-Agent 和超时设置；生产环境建议加入重试机制（如 tenacity 库）和错误日志。
- 合规提醒：请遵守 CoinCodex robots.txt 及其 Terms of Service，避免高频请求（建议 ≥30 秒间隔），并注明数据来源。
通过该方法，你不仅能自动化获取单个图表数据，还可轻松封装为定时任务（如 Airflow 或 cron），持续构建高质量时序特征库，为价格预测、波动率建模等任务提供可靠数据基础。
