Historical Candles BETA

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

GET /historical/candles/{product}

Parameters

Name	Type	Description
`product`*	string	期貨商品代號，例如 `TXF`、`MXF`、`CDF`（大寫）。週契約亦以商品代號查詢（例：`MXF` 搭配 `contractMonth=202609W2`），`MX4` 這類週契約前綴不是商品代號；契約代碼（例：`TXFI6`）不可作為 `product`，會回傳 404。目前僅支援期貨，選擇權與價差契約尚未提供
`contractMonth`	string	契約月份，未帶時預設為 `1!` 近月。可選：具體月份 `yyyyMM`（例：`202609`）；週契約（例：`202609W2`）；連續合約 `1!` 近月、`2!` 次近月、`3!` 第三近月（`4!` 以上回傳 400，只在月契約之間排序、不含週契約）
`from`	string	開始日期（格式：`yyyy-MM-dd`），未帶時預設為 1 週前
`to`	string	結束日期（格式：`yyyy-MM-dd`），未帶時預設為今日
`timeframe`	string	Ｋ線週期，未帶時預設為 `D` 日Ｋ；可選 `1` 1 分Ｋ；`5` 5 分Ｋ；`10` 10 分Ｋ；`15` 15 分Ｋ；`30` 30 分Ｋ；`60` 60 分Ｋ；`D` 日Ｋ；`W` 週Ｋ；`M` 月Ｋ
`session`	string	交易時段，未帶時預設為 `regular` 日盤；可選 `afterhours` 夜盤（盤後交易時段）
`fields`	string	欄位選擇，未帶時預設為 `open,high,low,close,volume`（不含 `average`、`transaction`、`change`，需要時請明確指定）；可選 `open`、`high`、`low`、`close`、`volume`、`average`、`transaction`、`change`（各欄位適用 timeframe 請見 Response 表格）。不提供成交金額 `turnover`，帶入會回傳 400
`sort`	string	時間排序，未帶時預設為 `desc` 降冪；可選 `asc` 升冪

info

日／週／月Ｋ可回溯至 2010 年；分Ｋ（日盤與夜盤）自 2017-06 起。當日資料於盤後產出，約 17:30 後可查詢。
查詢區間（from ~ to）單次須小於 1 年，恰好或超過 1 年會回傳 400 Bad Request（錯誤訊息：Date range must be less than one year）。
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!）於最後交易日的次一交易日換月，每根Ｋ線以 data.contractMonth 標示實際所屬合約。不做換月價差調整，換月日的Ｋ線會有跳空。
分Ｋ只計單式委託的成交，價差（組合）委託的兩腿與鉅額交易不計入，因此同一合約的日Ｋ成交量可能大於當日分Ｋ加總，日Ｋ有量但當日分Ｋ查無資料屬正常。
查詢區間內查無資料會回傳 404 Resource Not Found，而非空陣列。
手上若是日內行情使用的契約代碼（例：TXFI6），請拆成 product=TXF、contractMonth=202609 再查詢：第 4 碼為月份碼 A～L 對應 1～12 月（I = 9 月），第 5 碼為西元年末碼（6 = 2026）；連續月別名 TXF1! 則對應 product=TXF、contractMonth=1!。

Response

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

info

change 的計算基準：

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

Example

SDK 版本需求

SDK 範例需要 Node.js @fugle/marketdata v1.7.0／Python fugle-marketdata 2.7.0 以上。

日Ｋ範例（連續合約）

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

cURL
Python
Node.js

curl -X 'GET' \
  'https://api.fugle.tw/marketdata/v1.0/futopt/historical/candles/TXF?contractMonth=1!&from=2026-08-17&to=2026-08-21&fields=open,high,low,close,volume,change' \
  -H 'X-API-KEY: <YOUR_API_KEY>'

from fugle_marketdata import RestClient

client = RestClient(api_key = 'YOUR_API_KEY')  # 輸入您的 API key
futopt = client.futopt  # FutOpt REST API client

futopt.historical.candles(**{"product": "TXF", "contractMonth": "1!", "from": "2026-08-17", "to": "2026-08-21", "fields": "open,high,low,close,volume,change"})

const { RestClient } = require('@fugle/marketdata');

const client = new RestClient({ apiKey: 'YOUR_API_KEY' });
client.futopt.historical.candles({ product: 'TXF', contractMonth: '1!', from: '2026-08-17', to: '2026-08-21', fields: 'open,high,low,close,volume,change' })
  .then(data => console.log(data));

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
    }
  ]
}

分Ｋ範例

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

cURL
Python
Node.js

curl -X 'GET' \
  'https://api.fugle.tw/marketdata/v1.0/futopt/historical/candles/TXF?contractMonth=202609&timeframe=60&from=2026-09-10&to=2026-09-10&fields=open,high,low,close,volume,average,transaction' \
  -H 'X-API-KEY: <YOUR_API_KEY>'

from fugle_marketdata import RestClient

client = RestClient(api_key = 'YOUR_API_KEY')  # 輸入您的 API key
futopt = client.futopt  # FutOpt REST API client

futopt.historical.candles(**{"product": "TXF", "contractMonth": "202609", "timeframe": "60", "from": "2026-09-10", "to": "2026-09-10", "fields": "open,high,low,close,volume,average,transaction"})

const { RestClient } = require('@fugle/marketdata');

const client = new RestClient({ apiKey: 'YOUR_API_KEY' });
client.futopt.historical.candles({ product: 'TXF', contractMonth: '202609', timeframe: '60', from: '2026-09-10', to: '2026-09-10', fields: 'open,high,low,close,volume,average,transaction' })
  .then(data => console.log(data));

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 分Ｋ。from／to 填夜盤所屬的交易日（2026-09-10），回傳的是 2026-09-09 15:00 起至 2026-09-10 05:00 的夜盤Ｋ線：

cURL
Python
Node.js

curl -X 'GET' \
  'https://api.fugle.tw/marketdata/v1.0/futopt/historical/candles/TXF?contractMonth=202609&timeframe=60&session=afterhours&from=2026-09-10&to=2026-09-10' \
  -H 'X-API-KEY: <YOUR_API_KEY>'

from fugle_marketdata import RestClient

client = RestClient(api_key = 'YOUR_API_KEY')  # 輸入您的 API key
futopt = client.futopt  # FutOpt REST API client

futopt.historical.candles(**{"product": "TXF", "contractMonth": "202609", "timeframe": "60", "session": "afterhours", "from": "2026-09-10", "to": "2026-09-10"})

const { RestClient } = require('@fugle/marketdata');

const client = new RestClient({ apiKey: 'YOUR_API_KEY' });
client.futopt.historical.candles({ product: 'TXF', contractMonth: '202609', timeframe: '60', session: 'afterhours', from: '2026-09-10', to: '2026-09-10' })
  .then(data => console.log(data));

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
    }
  ]
}

Parameters​

Response​

Example​

日Ｋ範例（連續合約）​

分Ｋ範例​

夜盤範例​