台灣期貨與選擇權 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 分鐘。