Historical Candles BETA

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

GET /historical/candles/{product}

Parameters

Name	Type	Description
`product`*	string	商品代號（大寫），期貨例如 `TXF`、`MXF`、`CDF`，選擇權例如 `TXO`。契約月份請用 `contractMonth` 指定；週契約亦以商品代號查詢（例：`MXF` 搭配 `contractMonth=202609W2`），`MX4` 這類週契約前綴不是商品代號。契約代碼（例：`TXFI6`、`TXO48000J6`）不可作為 `product`，會回傳 400，價差代碼（例：`TXFJ6/K6`）會回傳 404；換算方式見下方日內契約代碼換算
`contractMonth`	string	契約月份。期貨：未帶時預設為 `1!` 近月；可填具體月份 `yyyyMM`（例：`202609`）、週契約 `yyyyMMWn`（例：`202609W2`）、價差 `{近腳}/{遠腳}`（例：`202610/202611`、`202610W1/202610`），或連續合約 `1!` 近月、`2!` 次近月、`3!` 第三近月（`4!` 以上回傳 400，只在月契約之間排序、不含週契約）。選擇權：必填；可填 `yyyyMM`、週契約 `yyyyMMWn`（週三到期）、`yyyyMMFn`（週五到期），不支援連續合約
`strikePrice`	number	選擇權專用，必填。履約價，例如 `48000`，須與 `callPut` 一起帶入
`callPut`	string	選擇權專用，必填。`CALL` 買權、`PUT` 賣權，須與 `strikePrice` 一起帶入
`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 標示實際所屬合約。不做換月價差調整，換月日的Ｋ線會有跳空。
分Ｋ只計單式委託的成交，價差（組合）委託的兩腿與鉅額交易不計入，因此同一合約的日Ｋ成交量可能大於當日分Ｋ加總，日Ｋ有量但當日分Ｋ查無資料屬正常。
價差合約的Ｋ線價格為價差（兩腳價格之差），成交量只計價差委託之間的成交；change 為 null。
查詢區間內查無資料會回傳 404 Resource Not Found，而非空陣列。

日內契約代碼換算

日內行情使用的契約代碼不可直接作為 product，請依下表換算為查詢參數：

日內代碼	查詢參數
`TXFI6`	`product=TXF`、`contractMonth=202609`
`TXF1!`	`product=TXF`、`contractMonth=1!`
`TXFJ6/K6`	`product=TXF`、`contractMonth=202610/202611`
`TXO48000J6`	`product=TXO`、`contractMonth=202610`、`strikePrice=48000`、`callPut=CALL`

月份碼期貨與買權為 A～L、賣權為 M～X，依序對應 1～12 月；最後一碼為西元年末碼。

Response

Name	Type	Description	適用 timeframe
`product`*	string	商品代號	—
`contractMonth`*	string	查詢時帶入的契約月份（連續合約查詢時為 `1!`／`2!`／`3!`）	—
`exchange`*	string	交易所	—
`session`*	string	盤別，`REGULAR` 日盤、`AFTERHOURS` 夜盤	—
`timeframe`*	string	Ｋ線週期	—
`sort`*	string	排序方向（`desc` 或 `asc`）	—
`strikePrice`	number	選擇權專用。查詢時帶入的履約價	—
`callPut`	string	選擇權專用。查詢時帶入的買賣權，`CALL` 或 `PUT`	—
`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	Ｋ線開盤價；無成交的Ｋ線為 `null`	全部
`data.high`	number	Ｋ線最高價；無成交的Ｋ線，或期交所未提供時為 `null`	全部
`data.low`	number	Ｋ線最低價；無成交的Ｋ線，或期交所未提供時為 `null`	全部
`data.close`	number	Ｋ線收盤價；無成交的Ｋ線為 `null`	全部
`data.volume`	number	Ｋ線成交量（口數），無成交為 `0`	全部
`data.average`	number	該根Ｋ線期間的成交量加權平均價（VWAP）	僅分Ｋ
`data.transaction`	number	該根Ｋ線的成交筆數	僅分Ｋ
`data.change`	number	Ｋ線漲跌；無成交的Ｋ線為 `null`	僅日／週／月Ｋ

info

日Ｋ的 change 為當日收盤價減前一交易日結算價（同期交所每日行情的漲跌價），連續合約的換月日以新合約自身的結算價計算；週／月Ｋ為區間內各日漲跌的加總。

Example

SDK 版本需求

SDK 範例需要 Node.js @fugle/marketdata v1.7.0／Python fugle-marketdata 2.7.0 以上；以 TypeScript 查詢選擇權時，strikePrice、callPut 的型別定義需要 v1.8.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

print(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

print(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

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

選擇權日Ｋ範例

查詢臺指選擇權 2026 年 10 月契約、履約價 48000 買權的日Ｋ：

cURL
Python
Node.js

curl -X 'GET' \
  'https://api.fugle.tw/marketdata/v1.0/futopt/historical/candles/TXO?contractMonth=202610&strikePrice=48000&callPut=CALL&from=2026-10-01&to=2026-10-07&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

print(futopt.historical.candles(**{"product": "TXO", "contractMonth": "202610", "strikePrice": 48000, "callPut": "CALL", "from": "2026-10-01", "to": "2026-10-07", "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: 'TXO', contractMonth: '202610', strikePrice: 48000, callPut: 'CALL', from: '2026-10-01', to: '2026-10-07', fields: 'open,high,low,close,volume,change' })
  .then(data => console.log(data));

Response Body：

{
  "product": "TXO",
  "contractMonth": "202610",
  "exchange": "TAIFEX",
  "session": "REGULAR",
  "timeframe": "D",
  "sort": "desc",
  "strikePrice": 48000,
  "callPut": "CALL",
  "data": [
    {
      "date": "2026-10-07",
      "contractMonth": "202610",
      "open": 2100,
      "high": 2250,
      "low": 2100,
      "close": 2150,
      "volume": 23,
      "change": -100
    },
    {
      "date": "2026-10-06",
      "contractMonth": "202610",
      "open": 2300,
      "high": 2300,
      "low": 2250,
      "close": 2250,
      "volume": 3,
      "change": 60
    },
    {
      "date": "2026-10-05",
      "contractMonth": "202610",
      "open": 1850,
      "high": 2320,
      "low": 1800,
      "close": 2140,
      "volume": 154,
      "change": 920
    },
    {
      "date": "2026-10-02",
      "contractMonth": "202610",
      "open": 1170,
      "high": 1320,
      "low": 1150,
      "close": 1220,
      "volume": 95,
      "change": -60
    },
    {
      "date": "2026-10-01",
      "contractMonth": "202610",
      "open": 1150,
      "high": 1280,
      "low": 990,
      "close": 1280,
      "volume": 105,
      "change": 160
    }
  ]
}

Parameters​

日內契約代碼換算​

Response​

Example​

日Ｋ範例（連續合約）​

分Ｋ範例​

夜盤範例​

選擇權日Ｋ範例​

Parameters

日內契約代碼換算

Response

Example

日Ｋ範例（連續合約）

分Ｋ範例

夜盤範例

選擇權日Ｋ範例