Skip to main content

Historical Candles

查詢期貨歷史 K 線（依商品代號查詢）。支援日／週／月 K 與分 K、日盤與夜盤，契約月份可填具體月份或連續合約 1!／2!／3!。單次查詢區間須小於 1 年；日／週／月 K 可回溯至 2010 年，分 K 自 2017-06 起提供。

historical/candles/{product}
版本資訊

v2.4.0 起新增功能

Parameters​

NameTypeDescription
product*string期貨商品代號，例如 TXF、MXF、CDF（大寫）。契約月份請用 contractMonth 指定；週契約亦以商品代號查詢（例：MXF 搭配 contractMonth=202609W2），MX4 這類週契約前綴不是商品代號。契約代碼（例：TXFI6）不可作為 product，會回傳 404，換算方式見下方說明。目前僅支援期貨，選擇權與價差契約尚未提供
contractMonthstring契約月份，未帶時預設為 1! 近月。可選：具體月份 yyyyMM（例：202609）；週契約（例：202609W2）；連續合約 1! 近月、2! 次近月、3! 第三近月（4! 以上回傳 400）
fromstring開始日期（格式：yyyy-MM-dd），未帶時預設為 1 週前
tostring結束日期（格式：yyyy-MM-dd），未帶時預設為今日
timeframestringK 線週期，未帶時預設為 D 日 K；可選 1 1 分 K；5 5 分 K；10 10 分 K；15 15 分 K；30 30 分 K；60 60 分 K；D 日 K；W 週 K；M 月 K
sessionstring交易時段，未帶時預設為 regular 日盤；可選 afterhours 夜盤（盤後交易時段）
fieldsstring欄位選擇，未帶時預設為 open,high,low,close,volume（不含 average、transaction、change，需要時請明確指定）；可選 open、high、low、close、volume、average、transaction、change（各欄位適用 timeframe 請見 Response 表格）。不提供成交金額 turnover，帶入會回傳 400
sortstring時間排序，未帶時預設為 desc 降冪；可選 asc 升冪
info
  • 日／週／月 K 可回溯至 2010 年。
  • 分 K（日盤與夜盤）自 2017-06 起提供（夜盤自當日 15:00 起，歸屬次一交易日）。
  • 分 K 依單式委託的成交計算；透過價差（組合）委託成交的兩腿與鉅額交易不計入分 K，因此同一合約的日 K 成交量可能大於當日分 K 加總，日 K 有量但當日分 K 查無資料屬正常。
  • 查詢區間（from ~ to）單次須小於 1 年，恰好或超過 1 年會回傳 400 Bad Request（錯誤訊息：Date range must be less than one year）。from 不可晚於 to，否則亦回傳 400。
  • from／to 以交易日計。夜盤依期交所規則歸屬次一交易日，例如 session=afterhours&from=2026-09-10&to=2026-09-10 回傳的是 2026-09-09 15:00 至 2026-09-10 05:00 這一場夜盤。
  • 連續合約（1!／2!／3!）依合約到期自動換月：最後交易日當天仍指向到期合約，次一交易日起切換至下一張；每根 K 線的 data.contractMonth 標示實際所屬合約。不做換月價差調整，換月日的 K 線會有跳空。連續合約只在月契約之間排序，不含週契約。
  • 查詢區間內查無資料會回傳 404 Resource Not Found，而非空陣列（例：區間完全為非交易日、早於該 timeframe 的資料起始日、商品代號或契約月份不存在、以選擇權商品代號查詢）。
  • 手上若是日內行情使用的契約代碼（例：TXFI6），請拆成商品代號與契約月份再查詢：前 3 碼為商品代號（TXF），第 4 碼為月份碼 A～L 對應 1～12 月（I = 9 月），第 5 碼為西元年末碼（6 = 2026），即 product=TXF、contractMonth=202609；連續月別名 TXF1! 則對應 product=TXF、contractMonth=1!。

Response​

NameTypeDescription適用 timeframe
product*string商品代號—
contractMonth*string查詢時帶入的契約月份（連續合約查詢時為 1!／2!／3!）—
exchange*string交易所—
session*string盤別，REGULAR 日盤、AFTERHOURS 夜盤—
timeframe*stringK 線週期—
sort*string排序方向（desc 或 asc）—
data*object[]K 線資料—
data.date*string日 K 為交易日、週 K 為該週週一、月 K 為當月 1 日（yyyy-MM-dd）；分 K 為 K 線起始時刻，ISO 8601 含時區（例：2026-09-10T08:45:00.000+08:00）全部
data.contractMonth*string該根 K 線實際所屬的契約月份。連續合約查詢時可藉此判斷換月發生在哪一根；跨換月的週／月 K 標示收盤時所屬的合約全部
data.opennumberK 線開盤價全部
data.highnumberK 線最高價全部
data.lownumberK 線最低價全部
data.closenumberK 線收盤價全部
data.volumenumberK 線成交量（口數）全部
data.averagenumber該根 K 線期間的成交量加權平均價（VWAP）僅分 K
data.transactionnumber該根 K 線的成交筆數僅分 K
data.changenumberK 線漲跌僅日／週／月 K
info

change 的計算基準：

  • 日 K 為該合約與其前一交易日收盤價之差。連續合約查詢時，換月當日的 change 以新合約自身的前一日收盤計算，不與前一張合約比較。
  • 週／月 K 為區間內各日漲跌之加總。

Examples​

日 K 範例（連續合約）​

以近月連續合約 1! 查詢日 K 並指定日期區間，區間跨越 2026 年 8 月合約到期日（8/19），可由 contractMonth 看到換月發生在 8/20：

from fubon_neo.sdk import FubonSDK, Order

sdk = FubonSDK()

accounts = sdk.login("Your ID", "Your password", "Your cert path", "Your cert password")  # 需登入後，才能取得行情權限

sdk.init_realtime() # 建立行情連線

restfutopt = sdk.marketdata.rest_client.futopt

## 2.2.4 及以後版本 (使用 Exception 進行例外處理)
from fubon_neo.fugle_marketdata.rest.base_rest import FugleAPIError

try:
  restfutopt.historical.candles(**{"product": "TXF", "contractMonth": "1!", "from": "2026-08-17", "to": "2026-08-21", "fields": "open,high,low,close,volume,change"})
except FugleAPIError as e:
  print(f"Error: {e}")
  print("------------")
  print(f"Status Code: {e.status_code}")  # 例: 429
  print(f"Response Text: {e.response_text}")  # 例: {"statusCode":429,"message":"Rate limit exceeded"}

Response Body：

{
  "product": "TXF",
  "contractMonth": "1!",
  "exchange": "TAIFEX",
  "session": "REGULAR",
  "timeframe": "D",
  "sort": "desc",
  "data": [
    {
      "date": "2026-08-21",
      "contractMonth": "202609",
      "open": 44887,
      "high": 45294,
      "low": 44566,
      "close": 45148,
      "volume": 51446,
      "change": 245
    },
    {
      "date": "2026-08-20",
      "contractMonth": "202609",
      "open": 44950,
      "high": 45122,
      "low": 44448,
      "close": 44868,
      "volume": 53693,
      "change": 368
    },
    {
      "date": "2026-08-19",
      "contractMonth": "202608",
      "open": 44411,
      "high": 44869,
      "low": 44208,
      "close": 44612,
      "volume": 27795,
      "change": -476
    },
    {
      "date": "2026-08-18",
      "contractMonth": "202608",
      "open": 45967,
      "high": 45977,
      "low": 45070,
      "close": 45085,
      "volume": 83392,
      "change": -782
    },
    {
      "date": "2026-08-17",
      "contractMonth": "202608",
      "open": 45850,
      "high": 46140,
      "low": 45738,
      "close": 45888,
      "volume": 79450,
      "change": 76
    }
  ]
}

分 K 範例​

以具體契約月份查詢 60 分 K 並指定日期區間（含均價 average 與成交筆數 transaction）：

from fubon_neo.sdk import FubonSDK, Order

sdk = FubonSDK()

accounts = sdk.login("Your ID", "Your password", "Your cert path", "Your cert password")  # 需登入後，才能取得行情權限

sdk.init_realtime() # 建立行情連線

restfutopt = sdk.marketdata.rest_client.futopt

## 2.2.4 及以後版本 (使用 Exception 進行例外處理)
from fubon_neo.fugle_marketdata.rest.base_rest import FugleAPIError

try:
  restfutopt.historical.candles(**{"product": "TXF", "contractMonth": "202609", "timeframe": "60", "from": "2026-09-10", "to": "2026-09-10", "fields": "open,high,low,close,volume,average,transaction"})
except FugleAPIError as e:
  print(f"Error: {e}")
  print("------------")
  print(f"Status Code: {e.status_code}")  # 例: 429
  print(f"Response Text: {e.response_text}")  # 例: {"statusCode":429,"message":"Rate limit exceeded"}

Response Body：

{
  "product": "TXF",
  "contractMonth": "202609",
  "exchange": "TAIFEX",
  "session": "REGULAR",
  "timeframe": "60",
  "sort": "desc",
  "data": [
    {
      "date": "2026-09-10T12:45:00.000+08:00",
      "contractMonth": "202609",
      "open": 46733,
      "high": 46949,
      "low": 46733,
      "close": 46870,
      "volume": 10066,
      "average": 46868.04,
      "transaction": 7729
    },
    {
      "date": "2026-09-10T11:45:00.000+08:00",
      "contractMonth": "202609",
      "open": 46673,
      "high": 46820,
      "low": 46666,
      "close": 46730,
      "volume": 4133,
      "average": 46745.72,
      "transaction": 3212
    },
    {
      "date": "2026-09-10T10:45:00.000+08:00",
      "contractMonth": "202609",
      "open": 46748,
      "high": 46803,
      "low": 46652,
      "close": 46677,
      "volume": 3896,
      "average": 46719.47,
      "transaction": 3192
    },
    {
      "date": "2026-09-10T09:45:00.000+08:00",
      "contractMonth": "202609",
      "open": 46661,
      "high": 46800,
      "low": 46589,
      "close": 46747,
      "volume": 7357,
      "average": 46688.19,
      "transaction": 5398
    },
    {
      "date": "2026-09-10T08:45:00.000+08:00",
      "contractMonth": "202609",
      "open": 46940,
      "high": 46950,
      "low": 46506,
      "close": 46663,
      "volume": 20094,
      "average": 46683.01,
      "transaction": 16071
    }
  ]
}

夜盤範例​

帶 session=afterhours 查詢夜盤 60 分 K。from／to 填夜盤所屬的交易日（2026-09-10），回傳的是 2026-09-09 15:00 起至 2026-09-10 05:00 的夜盤 K 線：

from fubon_neo.sdk import FubonSDK, Order

sdk = FubonSDK()

accounts = sdk.login("Your ID", "Your password", "Your cert path", "Your cert password")  # 需登入後，才能取得行情權限

sdk.init_realtime() # 建立行情連線

restfutopt = sdk.marketdata.rest_client.futopt

## 2.2.4 及以後版本 (使用 Exception 進行例外處理)
from fubon_neo.fugle_marketdata.rest.base_rest import FugleAPIError

try:
  restfutopt.historical.candles(**{"product": "TXF", "contractMonth": "202609", "timeframe": "60", "session": "afterhours", "from": "2026-09-10", "to": "2026-09-10"})
except FugleAPIError as e:
  print(f"Error: {e}")
  print("------------")
  print(f"Status Code: {e.status_code}")  # 例: 429
  print(f"Response Text: {e.response_text}")  # 例: {"statusCode":429,"message":"Rate limit exceeded"}

Response Body（節錄）：

{
  "product": "TXF",
  "contractMonth": "202609",
  "exchange": "TAIFEX",
  "session": "AFTERHOURS",
  "timeframe": "60",
  "sort": "desc",
  "data": [
    {
      "date": "2026-09-10T04:00:00.000+08:00",
      "contractMonth": "202609",
      "open": 46987,
      "high": 47019,
      "low": 46971,
      "close": 46984,
      "volume": 359
    },
    {
      "date": "2026-09-10T03:00:00.000+08:00",
      "contractMonth": "202609",
      "open": 47024,
      "high": 47086,
      "low": 46965,
      "close": 46992,
      "volume": 671
    },
    ...
    {
      "date": "2026-09-09T16:00:00.000+08:00",
      "contractMonth": "202609",
      "open": 47234,
      "high": 47295,
      "low": 47182,
      "close": 47233,
      "volume": 1608
    },
    {
      "date": "2026-09-09T15:00:00.000+08:00",
      "contractMonth": "202609",
      "open": 47214,
      "high": 47267,
      "low": 47136,
      "close": 47232,
      "volume": 2098
    }
  ]
}
info

'*' 表示必揭示欄位。