台湾期货与期权 API

12 个端点

最后更新 2026-10

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

台湾期货分线

GET/studio/market/twfutures/ohlcv/<symbol>/<schema>

数据起始: TXF 2011-01-03；MXF 2020-03-22（1d）；个股期货依各合约而定
更新频率: 接近即时

参数

名称	说明	可用值	默认
`symbol` string · path必填	近月连续合约	`TXF`（台指期）、`MXF`（小台），或 `ohlcv/symbols` 列出的个股期货代码（不分大小写）
`schema` string · path必填	K 棒周期	`1m`, `5m`, `15m`, `30m`, `60m`, `1d`
`start` string · query	起始日	`YYYY-MM-DD`	`end` − 该周期的最大区间
`end` string · query	结束日期	`YYYY-MM-DD`	今天（UTC）

每次请求的最大区间（end − start）：1m 31 天 · 5m 62 天 · 15m 93 天 · 30m 186 天 · 60m 365 天 · 1d 3650 天。

范例

Python

from datetime import date, timedeltadata = requests.get(f"{BASE_URL}/studio/market/twfutures/ohlcv/TXF/1d", headers=headers,                    params={"start": "2024-01-01", "end": "2024-12-31"}, timeout=60).json()["data"]# [{"ts": "2024-01-01 16:00:00+00:00", "open": 17838.0, "high": 17920.0, "low": 17751.0, "close": 17798.0, "volume": 82820},#  {"ts": "2024-01-02 16:00:00+00:00", "open": 17793.0, "high": 17817.0, "low": 17507.0, "close": 17546.0, "volume": 149638}, ...]def fetch_txf_chunked(schema, start, end, chunk_days=28):    result, cur, end_date = [], date.fromisoformat(start), date.fromisoformat(end)    while cur < end_date:        chunk_end = min(cur + timedelta(days=chunk_days), end_date)        resp = requests.get(f"{BASE_URL}/studio/market/twfutures/ohlcv/TXF/{schema}", headers=headers,                            params={"start": cur.isoformat(), "end": chunk_end.isoformat()}, timeout=60)        result.extend(resp.json().get("data", []))        cur = chunk_end    return result

回应

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

字段	类型	单位	说明
`ts`	string	UTC ISO 格式	K 棒开盘时间
`open` / `high` / `low` / `close`	float	指数点数（个股期货为价格）	价格
`volume`	int	口	成交量

错误

状态码	回应内容	情况
400	`{"error": "Invalid symbol. Allowed: [...]"}`	未涵盖的代码
400	`{"error": "Invalid schema. Allowed: [...]"}`	周期不对
400	`{"error": "Invalid date format. Use YYYY-MM-DD"}`	日期格式错误
400	`{"error": "date_range_too_large", "message": "...", "max_days": <n>}`	区间超过上限
503	错误信息	数据来源暂时无法使用

备注

2017-05-15 以前的盘中 K 棒只有日盘（夜盘 15:00–05:00 台北时间从那天才开始），所以每天的 K 棒数在那一天从约 300 根跳到约 1,140 根。
序列在每月结算时换月，价格不做调整，回测时请把换月那段遮掉。
换月规则（所有周期；TXF、MXF 与个股期货都一样）：每月结算日（第 3 个周三，该周三休市时为下一个交易日）整天都算到期月份。到期月份一路交易到台北时间 13:30 收盘，当天没有任何 K 棒的时间落在台北时间 13:31–14:59，从 15:00 夜盘起序列换成下个月份。结算日的 1d K 棒属于到期月份，所以它的收盘价是该合约 13:30 的最后一笔成交。
要抓好几年的历史，用 ohlcv/<symbol>/export/<year>，不要分段抓 JSON。
区间内没有数据时回 200 与 []。
不要假设序列会一路到最后一个交易日：MXF 与 CAF 要求抓到请求当天为止，回来的最后一根 K 棒都是几个月前的。请读 data[-1]["ts"]。
1d K 棒带的时间是 16:00:00+00:00（台北时间 00:00），不是 UTC 午夜；日期请从 ts 取，不要假设时间戳对齐日期。
TXF 的起始日适用于 1d 与盘中周期；MXF 的起始日是 1d 的。个股期货依各合约而定，CAF 的 1d K 棒至少从 2016-09-18 就有。
K 棒在请求时更新。

期货分线覆盖清单

GET/studio/market/twfutures/ohlcv/symbols

数据起始: 快照
更新频率: 即时

参数

无。

范例

Python

symbols = requests.get(f"{BASE_URL}/studio/market/twfutures/ohlcv/symbols", headers=headers, timeout=30).json()["data"]

回应

{"data": ["CDF", "DHF", "MXF", "TXF", ...]}：ohlcv、ohlcv/export 与 bid_ask_vol 接受的商品代码，包含 TXF、MXF，加上依流动性挑出、有分钟线的部分个股期货（231 档个股期货大多未涵盖）。

错误

只有共用错误。

期货分线年档下载

GET/studio/market/twfutures/ohlcv/<symbol>/export/<year>

数据起始: 2011（TXF）
更新频率: 当年度的文件在下载时更新

参数

名称	说明	可用值	默认
`symbol` string · path必填	商品代码	同 `ohlcv/symbols`
`year` int · path必填	西元年	2014 – 今年

范例

Python

import ioimport pandas as pdr = requests.get(f"{BASE_URL}/studio/market/twfutures/ohlcv/TXF/export/2024", headers=headers, timeout=120)raw = pd.read_parquet(io.BytesIO(r.content))raw.index = pd.to_datetime(raw["ts"], utc=True)bars_60m = (raw[["open", "high", "low", "close", "volume"]]            .resample("60min")            .agg(open=("open", "first"), high=("high", "max"), low=("low", "min"),                 close=("close", "last"), volume=("volume", "sum"))            .dropna(subset=["open"]))

回应

application/octet-stream，一个 parquet 档（<SYMBOL>_<year>_1m.parquet），字段为 ts、open、high、low、close、volume（1m K 棒）。

错误

状态码	回应内容	情况
400	`{"error": "Invalid symbol. Allowed: [...]"}`	未涵盖的代码
400	`{"error": "Invalid year. Allowed: 2014-<current>"}`	年份超出范围
404	`{"error": "no_data", "message": "No 1m data on disk for <symbol> in <year>"}`	没有文件

备注

一年一个请求，服务器端零运算；重新取样请在本机做。
与 ohlcv/<symbol>/1m 是同一条近月连续序列，套用同一套结算日换月规则（每月结算日没有时间落在台北时间 13:31–14:59 的 K 棒）。
过去年度的文件不会再变；当年度的文件在下载前更新。

台指期内外盘

GET/studio/market/twfutures/bid_ask_vol/<symbol>

数据起始: 2018-02-22（TXF）
更新频率: 由逐笔成交汇总，请求时更新

参数

名称	说明	可用值	默认
`symbol` string · path必填	商品代码	`TXF`、`MXF`（两者都验证过有数据）；其他 `ohlcv/symbols` 代码未测试
`start` string · query	起始日	`YYYY-MM-DD`	`end` − 31 天
`end` string · query	结束日；`end` − `start` ≤ 31 天	`YYYY-MM-DD`	今天（UTC）

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/twfutures/bid_ask_vol/TXF", headers=headers,                    params={"start": "2026-05-29", "end": "2026-05-29"}, timeout=60).json()["data"]# [{"ts": "2026-05-29 00:45:00+00:00", "bid_vol": 669, "ask_vol": 447, "total_vol": 1156}, ...]

回应

{"symbol", "start", "end", "data": [...]}，1 分钟一列，含日盘与夜盘。

字段	类型	单位	说明
`ts`	string	UTC ISO 格式	K 棒开盘时间
`bid_vol`	int	口	内盘：成交在买价的成交量（卖方主动）
`ask_vol`	int	口	外盘：成交在卖价的成交量（买方主动）
`total_vol`	int	口	总量，含无法分类的逐笔成交

错误

状态码	回应内容	情况
400	`{"error": "Invalid symbol. Allowed: [...]"}`	未涵盖的代码
400	`{"error": "Invalid date format. Use YYYY-MM-DD"}`	日期格式错误
400	`{"error": "date_range_too_large", "message": "...", "max_days": 31}`	区间超过 31 天
503	错误信息	数据来源暂时无法使用

备注

数据列是近月连续合约，换月规则与 ohlcv 相同：每月结算日，从到期月份台北时间 13:30 收盘到 15:00 夜盘开盘之间没有数据列；夜盘起的数据列属于下个月份。

期货日行情

GET/studio/market/twfutures/daily/<futures_id>

数据起始: TX 1998-07-21；MTX 2001-04-09；CDF 2010-01-25
更新频率: 每日，台北时间约 15:00 之后

参数

名称	说明	可用值	默认
`futures_id` string · path必填	商品	2–6 个字母，不分大小写，例如 `TX`、`MTX`、`TMF`、`TE`、`TF`，或个股期货代码（例如 `CDF`）
`start` string · query	起始日	`YYYY-MM-DD`	`1998-07-01`
`end` string · query	结束日	`YYYY-MM-DD`	今天

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/twfutures/daily/TX", headers=headers,                    params={"start": "2026-08-01"}, timeout=60).json()["data"]

回应

{"futures_id", "data": [...]}；每天多列（每个合约月份 × 交易时段各一列）。

字段	说明
`date`, `futures_id`	日期、商品
`contract_date`	合约月份（价差合约含 `/`）
`open` / `max` / `min` / `close`	价格（`max` = 最高、`min` = 最低）
`spread` / `spread_per`	涨跌／涨跌幅 %
`volume`	成交口数
`settlement_price`	结算价
`open_interest`	未平仓量
`trading_session`	`position`（一般交易时段）或 `after_market`（夜盘）

错误

状态码	回应内容	情况
400	`{"error": "Invalid futures_id"}`	格式检查未通过
404	`{"error": "No data found for futures_id: <id>"}`	没有数据
503	`{"error": "Upstream rate limit. Please retry shortly."}`	上游配额耗尽

备注

TX／MTX／TMF 最新一天的数据取自 TAIFEX 官方公布数据。
TX 是最早的商品；其他商品较晚开始（CDF 是个股期货）。
服务器缓存：5 分钟。

股票期货批次日行情

GET/studio/market/twfutures/stock_futures/batch/daily

数据起始: 依各合约上市日而定（CDF：2010-01-25）
更新频率: 同 twfutures/daily

参数

名称	说明	可用值	默认
`futures_ids` string · query必填	代码	以逗号分隔的个股期货代码，≤ 250 个
`start` string · query	起始日	`YYYY-MM-DD`	`1998-07-01`
`end` string · query	结束日	`YYYY-MM-DD`	今天

范例

Python

body = requests.get(f"{BASE_URL}/studio/market/twfutures/stock_futures/batch/daily", headers=headers,                    params={"futures_ids": "CDF,DHF", "start": "2026-08-01"}, timeout=120).json()

回应

{"data": {"<futures_id>": [...rows as /daily...]}, "failed": [...]}。failed = 抓取失败的代码（请重试）；两边都没有的代码就是真的没有数据。

错误

状态码	回应内容	情况
400	`{"error": "futures_ids parameter required"}`	缺少
400	`{"error": "futures_ids exceeds max 250 per request"}`	超过上限
400	`{"error": "Invalid stock futures_id(s): [...]"}`	有任何一个代码不是个股期货
503	`{"error": "Stock futures symbol list temporarily unavailable. Please retry shortly."}`	商品清单无法取得

期货三大法人

GET/studio/market/twfutures/institutional/<futures_id>

数据起始: 2018-06-05
更新频率: 每日，台北时间约 15:00 之后

参数

名称	说明	可用值	默认
`futures_id` string · path必填	商品	指数期货：`TX`、`MTX`、`TMF`、`TE`、`TF`（都验证过有数据）；不支持个股期货
`start` string · query	起始日	`YYYY-MM-DD`	`2018-06-05`
`end` string · query	结束日	`YYYY-MM-DD`	今天

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/twfutures/institutional/TX", headers=headers,                    params={"start": "2026-08-01"}, timeout=60).json()["data"]

回应

{"futures_id", "data": [...]}，每天 3 列（自营商／投信／外资）。

字段	说明
`date`, `futures_id`	日期、商品
`institutional_investors`	身分别
`long_deal_volume` / `long_deal_amount`	多方交易（口数／千元）
`short_deal_volume` / `short_deal_amount`	空方交易
`long_open_interest_balance_volume` / `long_open_interest_balance_amount`	多方未平仓
`short_open_interest_balance_volume` / `short_open_interest_balance_amount`	空方未平仓

错误

状态码	回应内容	情况
400	`{"error": "Invalid futures_id"}`	格式检查未通过
404	`{"error": "institutional data not available for stock futures (<id>)"}`	个股期货
404	错误信息	没有数据
503	上游频率限制／商品清单无法取得	稍后重试

备注

最新一天的数据取自 TAIFEX 官方公布数据。
*_amount 的单位是千元，是从数量级推断的，上游没有明写，但算得出来：一笔 TX 数据列的 long_open_interest_balance_amount 722870036 除以 ..._volume 78292，每口是 9,233，而一口 TX 是指数 × 200，所以 9,233 千 ÷ 200 ≈ 46,160 点，正是当天指数的位置。若当成元来读，会小 1,000×。
服务器缓存：5 分钟。

期货大额交易人

GET/studio/market/twfutures/large_traders/<futures_id>

数据起始: 2007-01-02
更新频率: 每日

参数

名称	说明	可用值	默认
`futures_id` string · path必填	商品	指数期货，例如 `TX`；不支持个股期货
`start` string · query	起始日	`YYYY-MM-DD`	`1998-07-01`
`end` string · query	结束日	`YYYY-MM-DD`	今天

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/twfutures/large_traders/TX", headers=headers,                    params={"start": "2026-08-01"}, timeout=60).json()["data"]

回应

{"futures_id", "data": [...]}，每天 3 列（contract_type：周／当月／全部）。

字段	说明
`date`, `futures_id`, `name`, `contract_type`	日期、商品、商品名称、合约范围
`buy_top5_trader_open_interest` / `buy_top10_trader_open_interest` (+ `_per`)	前 5 大／前 10 大交易人的多方未平仓（口数、占全市场 %）
`sell_top5_trader_open_interest` / `sell_top10_trader_open_interest` (+ `_per`)	前 5 大／前 10 大交易人的空方未平仓
`buy_top5_specific_open_interest` / `buy_top10_specific_open_interest` (+ `_per`)	前 5 大／前 10 大特定法人的多方未平仓
`sell_top5_specific_open_interest` / `sell_top10_specific_open_interest` (+ `_per`)	前 5 大／前 10 大特定法人的空方未平仓
`market_open_interest`	全市场未平仓量

错误

状态码	回应内容	情况
400	`{"error": "Invalid futures_id"}`	格式检查未通过
404	`{"error": "large_traders data not available for stock futures (<id>)"}`	个股期货
404	错误信息	没有数据
503	上游频率限制／商品清单无法取得	稍后重试

备注

服务器缓存：5 分钟。

选择权三大法人

GET/studio/market/twfutures/option/institutional/<option_id>

数据起始: 2018-06-05
更新频率: 每日

参数

名称	说明	可用值	默认
`option_id` string · path必填	选择权商品	`TXO`（接受 2–6 个字母）
`start` string · query	起始日	`YYYY-MM-DD`	`2018-06-05`
`end` string · query	结束日	`YYYY-MM-DD`	今天

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/twfutures/option/institutional/TXO", headers=headers,                    params={"start": "2026-08-01"}, timeout=60).json()["data"]

回应

{"option_id", "data": [...]}，每天 6 列（3 种身分别 × 买权／卖权）。字段：date、option_id、call_put（买权／卖权）、institutional_investors，以及与期货三大法人相同的 long_*／short_* 交易与未平仓口数／金额字段。

错误

400 {"error": "Invalid option_id"}；404 没有数据；503 上游频率限制。

备注

服务器缓存：5 分钟。

选择权大额交易人

GET/studio/market/twfutures/option/large_traders/<option_id>

数据起始: 2007-01-02
更新频率: 每日

参数

名称	说明	可用值	默认
`option_id` string · path必填	选择权商品	`TXO`（接受 2–6 个字母）
`start` string · query	起始日	`YYYY-MM-DD`	`1998-07-01`
`end` string · query	结束日	`YYYY-MM-DD`	今天

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/twfutures/option/large_traders/TXO", headers=headers,                    params={"start": "2026-08-01"}, timeout=60).json()["data"]

回应

{"option_id", "data": [...]}，每天 6 列（买权／卖权 × 周／当月／全部）。字段：date、option_id、name、put_call、contract_type，以及与期货大额交易人相同的前 5 大／前 10 大交易人与特定法人未平仓字段，加上 market_open_interest。

错误

400 {"error": "Invalid option_id"}；404 没有数据；503 上游频率限制。

备注

服务器缓存：5 分钟。

台指选择权买卖权比

GET/studio/market/twfutures/option/pcr

数据起始: 2001-12-24
更新频率: 每日

参数

名称	说明	可用值	默认
`start` string · query	起始日	`YYYY-MM-DD`	`2001-12-24`
`end` string · query	结束日	`YYYY-MM-DD`	今天

范例

Python

data = requests.get(f"{BASE_URL}/studio/market/twfutures/option/pcr", headers=headers,                    params={"start": "2024-01-01", "end": "2024-12-31"}, timeout=60).json()["data"]# [{"date": "2024-01-02", "put_volume": 309583, "call_volume": 404231, "volume_pcr": 76.59,#   "put_oi": 263673, "call_oi": 246495, "oi_pcr": 106.97, "pcr": 106.97},#  {"date": "2024-01-03", "put_volume": 622854, "call_volume": 729547, "volume_pcr": 85.38,#   "put_oi": 177203, "call_oi": 178062, "oi_pcr": 99.52, "pcr": 99.52}, ...]

回应

{"data": [...]}，每个交易日一列。

字段	单位	说明
`date`	—	交易日
`put_volume` / `call_volume`	口	卖权／买权成交量
`volume_pcr`	%	卖权／买权成交量比率
`put_oi` / `call_oi`	口	卖权／买权未平仓量
`oi_pcr`	%	卖权／买权未平仓量比率（买卖权未平仓量比率）
`pcr`	%	同 `oi_pcr`（为相容性保留）

错误

404 没有数据；503 数据库还没准备好或上游频率限制。

备注

这是 TAIFEX 官方公布的比率，不是从选择权三大法人或大额交易人数据推算的。
服务器缓存：5 分钟。

法人台指期持仓成本

GET/studio/market/twfutures/carrying_cost/<identity>

数据起始: 2023-10-18
更新频率: 每日，台北时间 15:40 与 17:40

Blave 对单一法人台指期净部位平均成本的估计，附未实现与已实现损益。这是由每日汇总数据估算的，不是该法人的真实成交。

算法：

部位 = 多方未平仓 − 空方未平仓，换算成大台（TX）口数：TX × 1、MTX × 1/4、TMF × 1/20（scope=all），或只算 TX（scope=tx）。
加码时，用该法人当天在加码那一方的自身平均成交价（TAIFEX 交易契约金额 ÷（口数 × 200））更新加权平均成本。减码时，以对向那一方的平均价认列已实现损益，成本不变。翻仓或平仓会把旧部位全部实现；新方向从当天的价格起算。
每个月结算日（第三个周三；休市时为下一个交易日）开始新的周期：成本重设为评价价格，已实现损益归 0。这样成本就不受数据起点影响。
评价价格 = TAIFEX 自己对未平仓部位的评价（未平仓契约金额 ÷（口数 × 200），也就是以各月份的结算价计）。未实现损益 =（评价价格 − 成本）× 净口数 × 200。

参数

名称	说明	可用值	默认
`identity` string · path必填	外资／投信／自营商	`foreign`, `investment_trust`, `dealer`
`start` string · query	起始交易日（含当日）	`YYYY-MM-DD`	`2023-10-18`（完整历史）
`end` string · query	结束交易日（含当日）	`YYYY-MM-DD`	今天
`scope` string · query	`all` = TX + MTX + TMF，换算成大台口数；`tx` = 只算大台（多数台湾网站引用的口径）	`all`, `tx`	`all`

账本一律从已存历史的起点算起；start／end 只是裁切窗口，所以不管你要哪个窗口，同一天的数值都一样。

范例

Python

body = requests.get(f"{BASE_URL}/studio/market/twfutures/carrying_cost/foreign", headers=headers,                    params={"start": "2026-10-06"}, timeout=60).json()rows = body["data"]# Live capture 2026-10-07 (scope=all):# {"identity": "foreign", "scope": "all", "data": [#   {"date": "2026-10-06", "net_open_interest": -78570.7, "net_open_interest_change": -3923.5,#    "cost": 46527.57, "txf_close": 50060.0, "mark_price": 50088.51,#    "unrealized_pnl": -55957022956, "realized_pnl": -5893982992, "total_pnl": -61851005948,#    "cycle_start": "2026-09-16"},#   {"date": "2026-10-07", "net_open_interest": -78435.8, "net_open_interest_change": 134.9,#    "cost": 46527.57, "txf_close": 49979.0, "mark_price": 49974.38,#    "unrealized_pnl": -54070636128, "realized_pnl": -5988669182, "total_pnl": -60059305310,#    "cycle_start": "2026-09-16"}]}gap = rows[-1]["txf_close"] - rows[-1]["cost"]   # points the market is above (+) / below (−) their cost

回应

{"identity", "scope", "data": [...]}，每个交易日一列，由旧到新；只有在服务器的数据落后 TAIFEX 最新公布日时才会加上 "stale": true（最新一列可能缺少）。

字段	类型	单位	说明
`date`	string	—	交易日（台北时间）
`net_open_interest`	float	约当大台口数	多方 − 空方未平仓（负值 = 净空单）
`net_open_interest_change`	float	口	与前一个交易日相比的变化
`cost`	float \| null	指数点数	净部位的加权平均成本；空手时为 `null`
`txf_close`	float \| null	指数点数	TX 近月日盘收盘价（结算日跳过到期合约）
`mark_price`	float \| null	指数点数	TAIFEX 对部位的评价，以结算价计
`unrealized_pnl`	int	元	（评价价格 − 成本）× 净口数 × 200
`realized_pnl`	int	元	自 `cycle_start` 以来的已实现损益；每个结算日归 0
`total_pnl`	int	元	`unrealized_pnl + realized_pnl`
`cycle_start`	string	—	开启目前周期的结算日

错误

状态码	回应内容	情况
400	`{"error": "Invalid identity. Allowed: ['dealer', 'foreign', 'investment_trust']"}`	未知的 identity
400	`{"error": "Invalid scope. Allowed: ['all', 'tx']"}`	未知的 scope
400	`{"error": "Invalid start date, expected YYYY-MM-DD"}`（或 `end`）／`{"error": "start must not be after end"}`	日期不对／区间颠倒
503	`{"error": "Market data is not ready on this server. Please retry later."}`	数据库还没准备好，稍后重试，绝不要当成「没有部位」
500	`{"error": "Internal error"}`	非预期的服务器错误

备注

只算期货：选择权部位（包含自营商的避险）不在账本里，所以自营商在这里的「亏损」可能在别处被抵销。
结算日刚过时，成本依定义就等于评价价格，所以周期头几天的数字看不太出部位实际建在哪里。
其他网站的外资成本用的规则不同（只算 TX、以近月收盘价当成交价，或未揭露），数字会不一样；请用相同口径比较（scope=tx）。
TAIFEX 只公布最近约三年的数据，起始日因此而定。
每天在 TAIFEX 公布后更新。
服务器缓存：5 分钟。