商品期货与宏观 API 参考文档

商品期货与宏观 API

2 个端点 · 商品 · 总体经济

最后更新 2026-10

Base URL: https://api.blave.org
认证: 每个请求都要带 api-key 与 secret-key 请求头
权限: API plan or Blave Agent plan
频率限制: 每组密钥、每个 IP 各 5 分钟 500 次

认证与错误这些数据涵盖什么：加密货币数据 · 宏观事件

CME / ICE 期货 K 线

GET/studio/market/db/ohlcv/<dataset>/<symbol>/<schema>

数据起始: 2010-06-06
更新频率: 延迟约 4 小时

参数

名称	说明	可用值	默认
`dataset` string · path必填	交易所数据集	`GLBX.MDP3`（CME）、`IFEU.IMPACT`（ICE）
`symbol` string · path必填	近月连续合约	`GLBX.MDP3`：`CL`（WTI 原油）、`GC`（黄金）；`IFEU.IMPACT`：`BRN`（布兰特原油）
`schema` string · path必填	K 棒周期	`ohlcv-1d`, `ohlcv-1h`, `ohlcv-1m`
`start` string · query	起始日	`YYYY-MM-DD`	`end` − 该周期的最大区间
`end` string · query	结束日期	`YYYY-MM-DD`	今天（UTC）

每次请求的最大区间（end − start）：ohlcv-1d 3650 天 · ohlcv-1h 730 天 · ohlcv-1m 31 天。

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/db/ohlcv/GLBX.MDP3/CL/ohlcv-1d", headers=headers,                    params={"start": "2024-01-01", "end": "2024-12-31"}, timeout=60).json()["data"]# [{"ts": "2024-01-02 00:00:00+00:00", "open": 71.95, "high": 73.64, "low": 70.06, "close": 70.5,#   "volume": 263594, "instrument_id": 686071},#  {"ts": "2024-01-03 00:00:00+00:00", "open": 70.49, "high": 73.23, "low": 69.28, "close": 73.05,#   "volume": 253755, "instrument_id": 686071}, ...]

回应

{"dataset", "symbol", "schema", "data": [...]}.

字段	类型	单位	说明
`ts`	string	UTC ISO 格式	K 棒开盘时间
`open` / `high` / `low` / `close`	float	美元（原油：每桶；黄金：每盎司）	价格
`volume`	int	口	成交量
`instrument_id`	int	—	上游的商品 id，从来源 K 棒原样带出

错误

状态码	回应内容	情况
400	`{"error": "Invalid schema. Allowed: [...]"}`	周期不对
400	`{"error": "Invalid dataset/symbol combination"}`	组合不对
400	`{"error": "Invalid date format. Use YYYY-MM-DD"}`	日期格式错误
400	`{"error": "date_range_too_large", "message": "...", "max_days": <n>}`	区间超过上限
404	错误信息	没有数据

备注

最近约 4 小时的数据无法取得。
要抓长区间的 ohlcv-1m 历史，请以 ≤ 31 天为一段分次请求再接起来（一段要几秒）。

总经事件行事历

GET/studio/market/anue/economic_calendar

权限: Any valid key
频率限制: 每个账号每分钟 100 次请求
数据起始: 滚动窗口：大约过去一个月到未来几周
更新频率: 服务器缓存 5 分钟

参数

全部选填；不筛选会回整份数据（约 1,400 列），所以一律要筛选。

名称	说明	可用值	默认
`start` string · query	这个日期（含）之后的事件	`YYYY-MM-DD`（台北日期）	无下限
`end` string · query	这个日期（含）之前的事件	`YYYY-MM-DD`（台北日期）	无上限
`country` string · query	国家筛选	ISO-2 代码，以逗号分隔，不分大小写，例如 `US,CN,TW`	所有国家
`max_priority` int · query	只留 `priority <= max_priority`。1 最重要，所以只看大事件 = `max_priority=1`	`1` / `2` / `3`	所有优先级
`limit` int · query	依事件时间排序后只留前 N 笔	≥ 1	不限
`lang` string · query	`countryName`／`subject` 的显示语言；服务器对照表里没有的名称会维持原样，所以 `en` 会回中英混杂的结果	`en` / `zh`	`en`

范例

Python

params = {"start": "2026-09-16", "end": "2026-09-23", "max_priority": 1, "lang": "zh"}response = requests.get(    f"{BASE_URL}/studio/market/anue/economic_calendar",    headers=headers, params=params, timeout=60,)data = response.json()# [{"id": 79382, "startDate": 1790121600, "date": 1788220800, "dateUnit": "month", "time": "16:30",#   "countryId": "GB", "countryName": "英國", "areaId": "4",#   "subject": "S&P Global Manufacturing PMI - 初值", "subjectTitle": "<9月>", "unit": "point",#   "predict": 51.7, "last": 51.7, "real": None, "correct": None, "correctMark": "N",#   "place": None, "priority": 1, "type": 2}, ...]

回应

一个裸的 JSON 数组（没有包在 {"data": ...} 里）。顺序是数据本身的顺序，除非有设 limit（这时依 startDate、time 排序）。

字段	类型	单位	说明
`startDate`	int	epoch 秒	事件的台北日历日期
`time`	string \| null	`HH:MM` 台北时间	公布时间；未公布时为 `null`
`countryId`	string	ISO-2	国家代码
`countryName`	string	—	国家名称（依 `lang`）
`subject`	string	—	指标名称（依 `lang`）
`subjectTitle`	string	—	期间标签，例如 `<7月>`、`<2季>`
`predict`	number \| null	`unit`	市场预期
`last`	number \| null	`unit`	前值
`real`	number \| null	`unit`	实际值；公布前为 `null`
`unit`	string	—	e.g. `%`, `point`, `億USD`
`priority`	int	1–3	1 = 最重要（非农就业、利率决议），3 = 最不重要（钻油井数）

实际回应还带了下列字段，是从上游数据原样带出的。这里只写观察到的内容，不要做更多解读。

字段	类型	观察到的内容
`id`	int	上游的事件 id，例如 `79382`
`date`	int	数据所属期间的 epoch 秒，不是公布时间：标示 `subjectTitle: "<9月>"` 的列，`date` = 2026-09-01，而 `startDate` 是 2026-09-23
`dateUnit`	string	`month`
`type`	int	`2`
`areaId`	string	`"4"`
`place`	string \| null	`null`
`correct`	number \| null	`null`
`correctMark`	string	`"N"`

错误

状态码	回应内容	情况
400	`{"error": "Invalid date format. Use YYYY-MM-DD"}`	`start`／`end` 格式错误
400	`{"error": "max_priority must be an integer"}`	`max_priority` 不是整数
400	`{"error": "limit must be an integer"}` / `{"error": "limit must be >= 1"}`	`limit` 不对
429	`{"error_code": "ERR429", "message": "User rate limit exceeded"}`	每分钟超过 100 次请求

备注

区间落在滚动窗口之外时回 200 与 []，意思是「未涵盖」，不是「没有排定的事件」。
有设 start／end 时，没有日期的事件会被丢掉；有设 max_priority 时，没有优先级的事件会被丢掉。
总经事件与其数字只认这个来源，绝不要用网络搜寻或记忆中的数值代替。财经日历汇整网站的表格会有错（有一个把已公布的实际值列成市场预期），页面没涵盖的字段则会被训练数据补上，前值只有一个正确答案，就曾经这样被写错。这个端点答不出来时，就直说。
窗口是滚动的，大约是过去一个月加上未来几周，不是历史数据库。
real 在公布后才会填入。