黄金原油等大宗商品历史行情与 CFTC 持仓怎么查?FMP 商品实时报价、分钟线与 COT 机构净持仓接入实战(Commodities & COT API)
做黄金、原油与有色金属的宏观择时、跨品种套利或通胀因子研究时,开发者经常面临“行情与持仓数据两张皮”的割裂问题:大宗商品价格要从财经门户或期货行情源爬取,而美国商品期货交易委员会(CFTC)定期发布的交易者持仓报告(Commitment of Traders,简称 COT)又得单独去官网下载原始文本,手动清洗合约代码并对齐报告日。
本文基于 FMP数据源中文站 对 FMP 旗下 Commodity(大宗商品接口)、CommitmentOfTraders(交易者持仓接口)与 Quote(实时行情接口)模块的实盘抽样(数据快照截至 2026-11-14 08:53 UTC),拆解如何用同一套 /stable/ 接口同时拉取 40 个大宗商品实时报价与多年历史日/分时 K 线,并与 65 个合约的 CFTC COT 非商业净持仓报告完成字段级对接。
为什么做黄金、原油投研不能只看期货现价,还要把行情与 CFTC COT 持仓接在一起?
大宗商品的短中周期定价高度依赖资金结构与交割预期。单纯拉取期货或现货连续价格只能做技术面形态回测,无法分辨上涨是由商业套保盘回补驱动,还是由对冲基金等非商业投机多头集中加仓推动。传统免费方案往往缺失统一接口:免费行情页缺少可回溯的多周期分钟线,而 CFTC 官网原始 CSV 需要自行维护合约代码映射与多头/空头/套利三类仓位拆分。
下表对比了传统拼装方案与 FMP 商品及 COT 统一接口方案的核心差异:
| 对比维度 | 传统多源拼装方案 | FMP 商品与 COT 统一方案 | 核心支撑端点 |
|---|---|---|---|
| 商品目录与代码 | 各交易所合约后缀不统一 | 统一 40 个标准化商品代码(含金属、能源、农产品与指数期货) | /stable/commodities-list |
| 实时批量快照 | 需逐个品种轮询 | 单次请求直接返回全部 40 个商品最新价、涨跌与成交量 | /stable/batch-commodity-quotes |
| 历史日线与分时 | 免费源多缺分钟级历史 | 黄金日线回溯至 1975-01-02,分时覆盖 1min、5min、1hour | /stable/historical-price-eod/full |
| CFTC 持仓报告 | 需定期解析 CFTC 原始文件 | 收录 65 个合约,GC 历史记录可查至 1986-01-15 | /stable/commitment-of-traders-report |
| 多空情绪衍生 | 需自行计算净持仓与环比 | 原生返回投机净持仓、环比变化百分比与多空情绪标签 | /stable/commitment-of-traders-analysis |
全球 40 个大宗商品(黄金 GCUSD / 原油 CLUSD / 布伦特 BZUSD)实时报价与多年日/分时行情怎么拉?
接入大宗商品行情的第一步是明确代码规范。调用 Commodities List(大宗商品清单接口,/stable/commodities-list)会返回 40 个标准化代码(如黄金 GCUSD、WTI 原油 CLUSD、布伦特原油 BZUSD、白银 SIUSD、铜 HGUSD、天然气 NGUSD),同时附带当前主力交割月 tradeMonth 与计价单位 currency(注意如活牛 LEUSX 等部分品种以美分 USX 计价)。
实时报价方面,Commodities Quote(大宗商品报价接口,/stable/quote)与 Commodities Quote Short(大宗商品快速报价接口,/stable/quote-short)提供单品种全字段与轻量快照;若需一次拉齐全部 40 个商品的最新价格,直接调用 All Commodities Quotes(大宗商品批量报价接口,/stable/batch-commodity-quotes,对应 Quote 分类下的 /apis/full-commodities-quotes/)。
历史行情方面,Full Chart(大宗商品全量日线接口,/stable/historical-price-eod/full)与 Light Chart(大宗商品精简日线接口,/stable/historical-price-eod/light)均支持 from 与 to 参数,单次请求上限为 5,000 条(已实测 light 对 GCUSD 同样截断于 5,000 条),配合逆向日期滑窗即可拉齐全历史。分时端点包括 1-Minute Interval Commodities Chart(大宗商品1分钟分时接口,/stable/historical-chart/1min)、5-Minute Interval Commodities Chart(大宗商品5分钟分时接口,/stable/historical-chart/5min)与 1-Hour Interval Commodities Chart(大宗商品1小时分时接口,/stable/historical-chart/1hour)。
下表汇总了 4 个代表性商品的历史日线全量实测结果,以及黄金(GCUSD)分时 K 线的默认容量与最早可用年份探针:
| 品种或周期 | 接口端点 | 全量或默认条数 | 实测最早日期或起点 | 最新收盘或样本区间(截至 2026-11-13) | 实盘结构特征 |
|---|---|---|---|---|---|
| GCUSD(黄金日线) | historical-price-eod/full | 全量 13,201 条(3 页) | 1975-01-02(175.1) | 最新收盘 3886.3,volume 151,049 | 1992-12-30 起 volume 非零 |
| CLUSD(WTI 原油) | historical-price-eod/full | 全量 6,644 条(2 页) | 2000-08-23(32.05) | 最新收盘 88.56,定盘 volume 270,072 | 首条日线即非零(共 6,637 条非零) |
| BZUSD(布伦特原油) | historical-price-eod/full | 全量 5,304 条(2 页) | 2006-05-25(70.71) | 最新收盘 95.84,定盘 volume 23,148 | 首条日线即非零(共 5,272 条非零) |
| SIUSD(白银日线) | historical-price-eod/full | 全量 14,438 条(3 页) | 1970-01-05(1.89) | 最新收盘 49.121,volume 49,657 | 1998-07-13 起 volume 非零 |
| GCUSD 分时(1min/1hour) | historical-chart/1min · 1hour | 默认 3,782 条 / 1,532 条 | 2024 年 1 月窗有数据(2023 年 1 月窗空) | 周四(11-12)单日 1,381 根 1min | 1min 默认覆盖 11-11 至 11-13 |
使用商品行情数据时,需注意三项实测口径边界:
- 2025 年起日线才出现周日记录:全量统计显示,GCUSD、CLUSD、BZUSD 与 SIUSD 在 2025 年之前均无周日日线;2025 年起开始出现 8 根周日记录,2026 年截至 11 月中旬出现 27~28 根。跨 2025 年回测计算年化指标时,需先统一周日日历口径。
- 已定盘
vwap、未定盘临时值与changePercent口径:核验 CLUSD(11-09 至 11-13)与 GCUSD(11-09 至 11-12)可见,已定盘日线vwap均等于四价均值(open + high + low + close) / 4的舍入值;而最新一根未定盘日线(如 11-13 的 GCUSD 3894.87、BZUSD 96.01)可能临时采用(high + low + close) / 3,且部分品种日线volume与batch-commodity-quotes实时快照存在更新时差(如 CLUSD 11-13 定盘日线volume270,072 与 11-12 相同,而实时快照为 184,224)。回测时应剔除最新未定盘日线或等次日定盘后再取。此外,日线change = close - open、changePercent ≈ 100 × (close - open) / open(如 CLUSD 11-13 为 -0.23 与 -0.259%),跨日收益率须用close[t] / close[t-1] - 1自行计算。 - 行情代码与 COT 合约需显式映射:商品清单存在 RTYUSD 等 6 位代码及 GC、GM 多合约,不能简单按字符串截断映射,建议维护显式字典(如 GCUSD 对应 GC / COMEX Gold 088691、CLUSD 对应 CL / NYMEX WTI-Physical 067651,外汇期货则使用 E6、J6 等
x6形式 CME 根代码)。同时 COT 汇总多个交割月全市场持仓,不能等同于单一主力合约持仓。
CFTC COT 交易者持仓报告(商业套保 vs 非商业投机净持仓)怎么对齐?
在 CommitmentOfTraders(交易者持仓接口)分类下,FMP 提供三个按层递进的端点:
- 合约清单:COT Report List(COT 报告清单接口,
/stable/commitment-of-traders-list)返回 65 个支持 COT 报告的期货合约(覆盖黄金GC、迷你黄金GM、WTI 原油CL、白银SI、铜HG及股指、利率、外汇期货)。 - 持仓明细原表:COT Report(COT 持仓报告接口,
/stable/commitment-of-traders-report)支持传入symbol与from/to日期范围(实测GC最早可查至 1986-01-15,2000 年起为周度发布),完整保留未平仓总合约数(openInterestAll)、非商业机构多空与套利(noncommPositionsLongAll/noncommPositionsShortAll/noncommPositionsSpreadAll)、商业套保多空(commPositionsLongAll/commPositionsShortAll)、交易者家数及前 4 / 前 8 大交易商持仓集中度。 - 多空情绪与净持仓分析:COT Analysis By Dates(COT 报告分析接口,
/stable/commitment-of-traders-analysis)直接输出计算好的多空占比、净持仓量与市场情绪标签(marketSituation与marketSentiment)。
以下展示黄金 GC 在 2026-11-03 报告期通过 commitment-of-traders-report 与 commitment-of-traders-analysis 返回的核心 JSON 字段(为便于对照,每条仅节选关键业务字段):
// 1. GET https://quote-fmp.com/stable/commitment-of-traders-report?symbol=GC&from=2026-10-01&to=2026-11-14
[
{
"symbol": "GC", "date": "2026-11-03 00:00:00", "name": "Gold (GC)", "sector": "METALS",
"openInterestAll": 399169,
"noncommPositionsLongAll": 220530, "noncommPositionsShortAll": 40982, "noncommPositionsSpreadAll": 68289,
"commPositionsLongAll": 64326, "commPositionsShortAll": 269228,
"changeInOpenInterestAll": 2359, "changeInNoncommLongAll": -3194, "changeInNoncommShortAll": 3709,
"contractUnits": "(CONTRACTS OF 100 TROY OUNCES)"
}
]
// 2. GET https://quote-fmp.com/stable/commitment-of-traders-analysis?symbol=GC&from=2026-10-01&to=2026-11-14
[
{
"symbol": "GC", "date": "2026-11-03 00:00:00", "name": "Gold (GC)",
"currentLongMarketSituation": 84.33, "currentShortMarketSituation": 15.67, "marketSituation": "Bullish",
"netPostion": 179548, "previousNetPosition": 186451, "changeInNetPosition": -3.7,
"marketSentiment": "Increasing Bearish", "reversalTrend": false
}
]
对接 COT 报告分析接口时,有两个工程细节极易踩坑:
- 接口返回字段名拼写
netPostion(缺少字母i):实盘 JSON 中当期净持仓键名为netPostion,而上期净持仓键名为previousNetPosition。解析代码切勿凭直觉写成netPosition,否则会静默取到None。 - 多空占比口径与发布时滞对齐:以黄金 2026-11-03(COMEX 088691,Legacy Futures Only)为例,非商业多头 220,530 手、空头 40,982 手,非商业多头占多空方向性持仓的 84.33%(
220,530 ÷ (220,530 + 40,982));净多头为 179,548 手(占全市场未平仓量 399,169 手的 44.98%),因此marketSituation标为"Bullish";但净多头较上期 186,451 手减少 6,903 手(降幅 3.70%),故marketSentiment标为"Increasing Bearish"。回测时还须区分持仓统计日(date)与 CFTC 实际公布日(通常延后数日,遇节假日顺延),信号只能在公布之后使用。
可直接运行的 Python 商品行情与 COT 净持仓联动脚本
以下零第三方依赖 Python 脚本封装了商品实时快照、5,000 条逆向滑窗拉取完整日线,以及将 CFTC COT 明细与分析情绪按报告日对齐。运行前请先设置环境变量:Linux/macOS 执行 export FMP_KEY="你的密钥",Windows PowerShell 执行 $env:FMP_KEY="你的密钥"。
import datetime, json, os, urllib.parse, urllib.request
BASE_URL = "https://quote-fmp.com/stable"
API_KEY = os.environ["FMP_KEY"]
def fmp_get(path, params=None):
q = urllib.parse.urlencode({**(params or {}), "apikey": API_KEY})
req = urllib.request.Request(f"{BASE_URL}/{path}?{q}", headers={"User-Agent": "Mozilla/5.0"})
with urllib.request.urlopen(req, timeout=25) as resp:
return json.loads(resp.read().decode("utf-8"))
def fetch_commodity_eod(symbol, start_date, end_date):
records, cursor_to = {}, end_date
while cursor_to >= start_date:
batch = fmp_get("historical-price-eod/full", {"symbol": symbol, "from": start_date, "to": cursor_to})
if not batch:
break
for r in batch:
records[r["date"]] = r
oldest = batch[-1]["date"]
if len(batch) < 5000 or oldest <= start_date:
break
cursor_to = (datetime.date.fromisoformat(oldest) - datetime.timedelta(days=1)).isoformat()
return [records[d] for d in sorted(records)]
def fetch_cot_net_positions(cot_symbol, start_date, end_date):
reports = fmp_get("commitment-of-traders-report", {"symbol": cot_symbol, "from": start_date, "to": end_date})
analysis = {a["date"]: a for a in fmp_get("commitment-of-traders-analysis", {"symbol": cot_symbol, "from": start_date, "to": end_date})}
out = []
for r in reports[:3]:
nc_net = r["noncommPositionsLongAll"] - r["noncommPositionsShortAll"]
cm_net = r["commPositionsLongAll"] - r["commPositionsShortAll"]
ana = analysis.get(r["date"], {})
out.append({
"symbol": cot_symbol, "date": r["date"][:10], "open_interest": r["openInterestAll"],
"noncomm_net": nc_net, "comm_net": cm_net,
"api_net_postion": ana.get("netPostion"), "sentiment": ana.get("marketSentiment"),
})
return out
if __name__ == "__main__":
quotes = {q["symbol"]: {"price": q["price"], "change": q["change"], "volume": q["volume"]}
for q in fmp_get("batch-commodity-quotes") if q.get("symbol") in {"GCUSD", "CLUSD", "BZUSD"}}
print("quotes:", json.dumps(quotes, ensure_ascii=False))
for sym in ["GCUSD", "CLUSD"]:
bars = fetch_commodity_eod(sym, "1970-01-01", "2026-11-13")
print(json.dumps({"symbol": sym, "total_days": len(bars), "earliest": bars[0]["date"], "latest_close": bars[-1]["close"]}, ensure_ascii=False))
for cot_sym in ["GC", "CL"]:
print("cot:", json.dumps(fetch_cot_net_positions(cot_sym, "2026-10-01", "2026-11-14"), ensure_ascii=False))
在终端直接执行上述脚本,实盘输出如下(数据快照截至 2026-11-14 08:53 UTC):
quotes: {"CLUSD": {"price": 88.56, "change": -0.18, "volume": 184224}, "GCUSD": {"price": 3886.3, "change": 1, "volume": 151049}, "BZUSD": {"price": 95.84, "change": 0.02, "volume": 23148}}
{"symbol": "GCUSD", "total_days": 13201, "earliest": "1975-01-02", "latest_close": 3886.3}
{"symbol": "CLUSD", "total_days": 6644, "earliest": "2000-08-23", "latest_close": 88.56}
cot: [{"symbol": "GC", "date": "2026-11-03", "open_interest": 399169, "noncomm_net": 179548, "comm_net": -204902, "api_net_postion": 179548, "sentiment": "Increasing Bearish"}, {"symbol": "GC", "date": "2026-10-27", "open_interest": 396810, "noncomm_net": 186451, "comm_net": -215624, "api_net_postion": 186451, "sentiment": "Increasing Bearish"}, {"symbol": "GC", "date": "2026-10-20", "open_interest": 402279, "noncomm_net": 199865, "comm_net": -235582, "api_net_postion": 199865, "sentiment": "Increasing Bearish"}]
cot: [{"symbol": "CL", "date": "2026-11-03", "open_interest": 1908732, "noncomm_net": 80289, "comm_net": -111277, "api_net_postion": 80289, "sentiment": "Increasing Bullish"}, {"symbol": "CL", "date": "2026-10-27", "open_interest": 1886280, "noncomm_net": 74343, "comm_net": -102968, "api_net_postion": 74343, "sentiment": "Increasing Bearish"}, {"symbol": "CL", "date": "2026-10-20", "open_interest": 1835144, "noncomm_net": 89325, "comm_net": -116158, "api_net_postion": 89325, "sentiment": "Increasing Bearish"}]
若需要将大宗商品波动与美元汇率或美债宏观周期联合建模,可参考 全球货币对实时汇率与历史 K 线获取方案 与 非农与 CPI 公布时刻回测对齐与美债利率实战。
常见问题(FAQ):接入大宗商品与 CFTC COT 数据还有哪些实用细节?
Q1:除了黄金原油,CFTC COT 接口还支持股指期货或外汇期货吗?
支持。/stable/commitment-of-traders-list 收录的 65 个合约同时覆盖标普 500(ES)、纳指 100(NQ)、10 年期美债(ZN)以及欧元(E6)、日元(J6)、英镑(B6)、加元(D6)、澳元(A6)等金融期货(外汇期货采用 x6 形式的 CME 根代码),传参结构与 GC、CL 完全一致。
Q2:如果只需要批量拉取商品历史收盘价做大类资产相关性矩阵,哪个接口更省流量?
可以使用 Light Chart(大宗商品精简日线接口,/stable/historical-price-eod/light),仅返回 symbol、date、price 与 volume 四个字段,同样支持 from / to 区间与 5,000 条分页。如需亲自跑通上述商品行情与 COT 持仓代码,可前往 快速接入指南 免费申领 Ultimate 全接口试用密钥。