16 個端點
https://api.blave.orgapi-key 與 secret-key 標頭API plan or Blave Agent plan/studio/market/twfutures/ohlcv/<symbol>/<schema> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
symbolstring · path必填 | 近月連續合約 | TXF(台指期)、MXF(小台),或 ohlcv/symbols 列出的個股期貨代號(不分大小寫) | |
schemastring · path必填 | K 棒週期 | 1m, 5m, 15m, 30m, 60m, 1d | |
startstring · query | 起始日 | YYYY-MM-DD | end − 該週期的最大區間 |
endstring · query | 結束日期 | YYYY-MM-DD | 今天(UTC) |
每次請求的最大區間(end − start):1m 31 天 · 5m 62 天 · 15m 93 天 · 30m 186 天 · 60m 365 天 · 1d 3650 天。
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 | 錯誤訊息 | 資料來源暫時無法使用 |
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 取,不要假設時間戳對齊日期。1d 與盤中週期;MXF 的起始日是 1d 的。個股期貨依各合約而定,CAF 的 1d K 棒至少從 2016-09-18 就有。/studio/market/twfutures/ohlcv/symbols 無。
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,以及有分鐘線的個股期貨。涵蓋範圍會隨時間變動,要確認某個合約,看 stock_futures/list 裡它的 minute_line_enabled,不要假設固定檔數。
只有共用錯誤。
/studio/market/twfutures/ohlcv/<symbol>/export/<year> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
symbolstring · path必填 | 商品代號 | 同 ohlcv/symbols | |
yearint · path必填 | 西元年 | 2014 – 今年 |
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 棒)。/studio/market/twfutures/bid_ask_vol/<symbol> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
symbolstring · path必填 | 商品代號 | TXF、MXF(兩者都驗證過有資料);其他 ohlcv/symbols 代號未測試 | |
startstring · query | 起始日 | YYYY-MM-DD | end − 31 天 |
endstring · query | 結束日;end − start ≤ 31 天 | YYYY-MM-DD | 今天(UTC) |
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 夜盤開盤之間沒有資料列;夜盤起的資料列屬於下個月份。/studio/market/twfutures/daily/<futures_id> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
futures_idstring · path必填 | 商品 | 2–6 個字母,不分大小寫,例如 TX、MTX、TMF、TE、TF,或個股期貨代號(例如 CDF) | |
startstring · query | 起始日 | YYYY-MM-DD | 1998-07-01 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
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 是個股期貨)。/studio/market/twfutures/stock_futures/list 無。
rows = requests.get(f"{BASE_URL}/studio/market/twfutures/stock_futures/list" , headers=headers, timeout=30).json()["data"]# Live capture 2026-11-06 (abridged with ...):# [{"futures_id": "CAF", "code": "CA", "stock_id": "1303", "stock_name": "南亞",# "stock_full_name": "南亞塑膠工業股份有限公司", "unit": 2000, "minute_line_enabled": true}, ...,# {"futures_id": "CDF", "code": "CD", "stock_id": "2330", "stock_name": "台積電",# "stock_full_name": "台灣積體電路製造股份有限公司", "unit": 2000, "minute_line_enabled": true}, ...,# {"futures_id": "QFF", "code": "QF", "stock_id": "2330", "stock_name": "台積電",# "stock_full_name": "台灣積體電路製造股份有限公司", "unit": 100, "minute_line_enabled": true}, ... 240 rows]by_stock = {}for r in rows: # one stock can have a standard and a mini contract by_stock.setdefault(r["stock_id"], []).append(r["futures_id"]){"data": [...]},每個合約一列,依 futures_id 排序。
| 欄位 | 型別 | 說明 |
|---|---|---|
futures_id | string | 其他期貨端點使用的合約代碼,例如 CDF(= code + F) |
code | string | TAIFEX 商品代碼,例如 CD |
stock_id | string | 標的股票代號,例如 2330 |
stock_name / stock_full_name | string | 標的股票簡稱/全名 |
unit | int | 每口股數(標準型 2,000 股;小型 100 股) |
minute_line_enabled | bool | 合約有分鐘 K 棒時為 true(ohlcv/<symbol>/<schema>、bid_ask_vol/<symbol>) |
| 狀態碼 | 回應內容 | 情況 |
|---|---|---|
| 503 | {"error": "Stock futures symbol list temporarily unavailable. Please retry shortly."} | 取不到掛牌清單 |
stock_id → futures_id 是一對多:同一檔股票可能同時有標準型(2,000 股)與小型(100 股)合約。兩者的口數不能直接比,小型每口的名目金額是 1/20。stock_futures/batch/daily 接受的代碼。/studio/market/twfutures/stock_futures/liquidity_ranking 無。
rows = requests.get(f"{BASE_URL}/studio/market/twfutures/stock_futures/liquidity_ranking" , headers=headers, timeout=120).json()["data"]# Live capture 2026-11-06 (abridged with ...):# [{"rank": 1, "futures_id": "CCF", "code": "CC", "stock_id": "2303", "stock_name": "聯電",# "stock_full_name": "聯華電子股份有限公司", "unit": 2000,# "avg_volume": 50357.3, "avg_open_interest": 75444.95, "minute_line_enabled": true},# {"rank": 2, "futures_id": "QFF", "code": "QF", "stock_id": "2330", "stock_name": "台積電",# "stock_full_name": "台灣積體電路製造股份有限公司", "unit": 100,# "avg_volume": 44525.55, "avg_open_interest": 109939.75, "minute_line_enabled": true}, ... 240 rows]standard = [r for r in rows if r["unit"] == 2000][:20] # compare lots within one unit only{"data": [...]},每個有日資料的個股期貨合約,依 avg_volume 由大到小排序。
| 欄位 | 型別 | 單位 | 說明 |
|---|---|---|---|
rank | int | — | 依 avg_volume 的排名,從 1 起算 |
futures_id, code, stock_id, stock_name, stock_full_name, unit | — | — | 同 stock_futures/list |
avg_volume | float | 口 | 最近 20 個交易日的日均成交量:只算一般交易時段,每天把所有合約月份加總,不含價差合約與夜盤 |
avg_open_interest | float | 口 | 同一段期間的日均未平倉量,加總方式相同 |
minute_line_enabled | bool | — | 同 stock_futures/list |
| 狀態碼 | 回應內容 | 情況 |
|---|---|---|
| 503 | {"error": "Stock futures symbol list temporarily unavailable. Please retry shortly."} | 取不到掛牌清單 |
unit 內才能比:小型合約一口是標準型的 1/20,跨不同單位排名請改用名目金額(口數 × unit × 價格)。stock_futures/list 比對。/studio/market/twfutures/stock_futures/batch/daily | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
futures_idsstring · query必填 | 代號 | 以逗號分隔的個股期貨代號,≤ 250 個 | |
startstring · query | 起始日 | YYYY-MM-DD | 1998-07-01 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
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."} | 商品清單無法取得 |
/studio/market/twfutures/institutional/<futures_id> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
futures_idstring · path必填 | 商品 | 指數期貨:TX、MTX、TMF、TE、TF(都驗證過有資料);不支援個股期貨 | |
startstring · query | 起始日 | YYYY-MM-DD | 2018-06-05 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
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 | {"error": "No data found for futures_id: <id>"} | 該商品完全沒有資料。區間內沒有任何列時回 200 加 "data": [] |
| 503 | 上游頻率限制/商品清單無法取得 | 稍後重試 |
*_amount 的單位是千元,是從數量級推斷的,上游沒有明寫,但算得出來:一筆 TX 資料列的 long_open_interest_balance_amount 722870036 除以 ..._volume 78292,每口是 9,233,而一口 TX 是指數 × 200,所以 9,233 千 ÷ 200 ≈ 46,160 點,正是當天指數的位置。若當成元來讀,會小 1,000×。/studio/market/twfutures/large_traders/<futures_id> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
futures_idstring · path必填 | 商品 | 指數期貨,例如 TX;不支援個股期貨 | |
startstring · query | 起始日 | YYYY-MM-DD | 1998-07-01 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
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 | {"error": "No data found for futures_id: <id>"} | 該商品完全沒有資料。區間內沒有任何列時回 200 加 "data": [] |
| 503 | 上游頻率限制/商品清單無法取得 | 稍後重試 |
/studio/market/twfutures/retail_long_short_ratio/<futures_id> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
futures_idstring · path必填 | 商品 | 指數期貨,2–6 個字母,不分大小寫:TMF(微型臺指)、MTX(小型臺指)、TX(臺股期貨) | |
datestring · query | 單一交易日 | YYYY-MM-DD | 最近一個已結算的交易日 |
row = requests.get(f"{BASE_URL}/studio/market/twfutures/retail_long_short_ratio/TMF" , headers=headers, timeout=60).json()# Live capture 2026-11-06:# {"date": "2026-11-06", "futures_id": "TMF", "market_open_interest": 96708,# "institutional_long_open_interest": 6870, "institutional_short_open_interest": 52454,# "retail_long_open_interest": 89838, "retail_short_open_interest": 44254,# "retail_long_short_ratio": 47.13570749059023}# Same day: MTX 17.37, TX 5.92 — each product has its own retail share, so never compare across them# For a series use /retail_long_short_ratio/<futures_id>/history (one call for a whole range)一天一個物件(沒有 data 外層)。
| 欄位 | 型別 | 單位 | 說明 |
|---|---|---|---|
date | string | — | 交易日 |
futures_id | string | — | 商品 |
market_open_interest | int | 口 | 全市場未平倉量:所有合約月份、一般交易時段,不含價差合約 |
institutional_long_open_interest | int | 口 | 三大法人(自營商+投信+外資)的多方未平倉量 |
institutional_short_open_interest | int | 口 | 三大法人的空方未平倉量 |
retail_long_open_interest | int | 口 | market_open_interest − institutional_long_open_interest |
retail_short_open_interest | int | 口 | market_open_interest − institutional_short_open_interest |
retail_long_short_ratio | float | % | (散戶多方 − 散戶空方)÷ market_open_interest × 100。正值 = 散戶淨多 |
| 狀態碼 | 回應內容 | 情況 |
|---|---|---|
| 400 | {"error": "Invalid futures_id"} | 格式檢查未通過 |
| 400 | {"error": "Invalid date, expected YYYY-MM-DD"} | date 格式錯誤 |
| 404 | {"error": "No retail long/short ratio data for futures_id <id> on <date>"} | date 不是交易日,或資料還沒公布 |
| 404 | {"error": "No data found for futures_id: <id>"}(或類似的查無資料訊息) | 該商品沒有資料(個股期貨沒有法人資料) |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配額耗盡 |
daily/<futures_id> 裡一般交易時段(position)的列;夜盤的列沒有未平倉量,價差合約也排除。法人那一方是同一天 institutional/<futures_id> 三列的加總。TMF(微型臺指,每口指數 × 10)散戶比重是三者最高(多方幾乎全是散戶),MTX(小型臺指,指數 × 50)居中,TX(臺股期貨,指數 × 200)以法人為主,所以餘數很小。2026-11-06 當天 TMF 是 47.14、MTX 是 17.37、TX 是 5.92。請追蹤單一商品的時間序列,只跟它自己比。TMF 的歷史從上市日 2024-07-29 開始。/studio/market/twfutures/retail_long_short_ratio/<futures_id>/history | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
futures_idstring · path必填 | 商品 | 指數期貨,2–6 個字母,不分大小寫:TMF(微型臺指)、MTX(小型臺指)、TX(臺股期貨) | |
startstring · query | 起始日 | YYYY-MM-DD | 最早可取得的日期 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
import pandas as pdresp = requests.get(f"{BASE_URL}/studio/market/twfutures/retail_long_short_ratio/TMF/history" , headers=headers, params={"start": "2026-10-27", "end": "2026-11-07"}, timeout=60).json()# Live capture 2026-11-09: 9 rows, 2026-10-27 .. 2026-11-06# {"futures_id": "TMF", "data": [..., {"date": "2026-11-06", "futures_id": "TMF",# "market_open_interest": 96708, "institutional_long_open_interest": 6870,# "institutional_short_open_interest": 52454, "retail_long_open_interest": 89838,# "retail_short_open_interest": 44254, "retail_long_short_ratio": 47.13570749059023}]}df = pd.DataFrame(resp["data"]).set_index("date"){"futures_id", "data": [...]};每個交易日一列,由舊到新。每列欄位跟上面的單日端點相同(date, futures_id, market_open_interest, institutional_long_open_interest, institutional_short_open_interest, retail_long_open_interest, retail_short_open_interest, retail_long_short_ratio)。
| 狀態碼 | 回應內容 | 情況 |
|---|---|---|
| 400 | {"error": "Invalid futures_id"} | 格式檢查未通過 |
| 400 | {"error": "Invalid start date, expected YYYY-MM-DD"}(或 end) | 日期格式錯誤 |
| 400 | {"error": "start must not be after end"} | 區間顛倒 |
| 404 | {"error": "No data found for futures_id: <id>"} | 該商品完全沒有資料 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配額耗盡 |
區間內沒有任何已結算的交易日(例如週末,或早於該商品的歷史起點)時回 200 加 "data": [],不算錯誤。
TMF、MTX、TX 三者不能互比。start 會回整段歷史(TX 約 2,050 列,2026-11)。/studio/market/twfutures/option/institutional/<option_id> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
option_idstring · path必填 | 選擇權商品 | TXO(接受 2–6 個字母) | |
startstring · query | 起始日 | YYYY-MM-DD | 2018-06-05 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
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 {"error": "No data found for option_id: <id>"}(區間內沒有任何列則回 200 加 "data": []);503 上游頻率限制。
/studio/market/twfutures/option/large_traders/<option_id> | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
option_idstring · path必填 | 選擇權商品 | TXO(接受 2–6 個字母) | |
startstring · query | 起始日 | YYYY-MM-DD | 1998-07-01 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
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 {"error": "No data found for option_id: <id>"}(區間內沒有任何列則回 200 加 "data": []);503 上游頻率限制。
/studio/market/twfutures/option/pcr | 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
startstring · query | 起始日 | YYYY-MM-DD | 2001-12-24 |
endstring · query | 結束日 | YYYY-MM-DD | 今天 |
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(為相容性保留) |
503 資料庫尚未就緒或上游頻率限制。區間內沒有任何列時回 200 加 "data": []。
/studio/market/twfutures/carrying_cost/<identity> Blave 對單一法人台指期淨部位平均成本的估計,附未實現與已實現損益。這是由每日彙總資料估算的,不是該法人的真實成交。
算法:
scope=all),或只算 TX(scope=tx)。| 名稱 | 說明 | 可用值 | 預設 |
|---|---|---|---|
identitystring · path必填 | 外資/投信/自營商 | foreign, investment_trust, dealer | |
startstring · query | 起始交易日(含當日) | YYYY-MM-DD | 2023-10-18(完整歷史) |
endstring · query | 結束交易日(含當日) | YYYY-MM-DD | 今天 |
scopestring · query | all = TX + MTX + TMF,換算成大台口數;tx = 只算大台(多數台灣網站引用的口徑) | all, tx | all |
帳本一律從已存歷史的起點算起;start/end 只是裁切視窗,所以不管你要哪個視窗,同一天的數值都一樣。
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"} | 非預期的伺服器錯誤 |
scope=tx)。