Historical Candles

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

historical/candles/{product}

版本資訊

v2.4.0 起新增功能；v2.5.0 起支援選擇權（strikePrice、callPut）

Parameters

Name	Type	Description
`product`*	string	商品代號（大寫），期貨例如 `TXF`、`MXF`、`CDF`，選擇權例如 `TXO`。契約月份請用 `contractMonth` 指定；週契約亦以商品代號查詢（例：`MXF` 搭配 `contractMonth=202609W2`），`MX4` 這類週契約前綴不是商品代號。契約代碼（例：`TXFI6`、`TXO48000J6`）不可作為 `product`，會回傳 400，換算方式見下方日內契約代碼換算。價差契約尚未提供
`contractMonth`	string	契約月份。期貨：未帶時預設為 `1!` 近月；可填具體月份 `yyyyMM`（例：`202609`）、週契約 `yyyyMMWn`（例：`202609W2`），或連續合約 `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	K 線週期，未帶時預設為 `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
`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

資料範圍：日／週／月 K 自 2010 年起；分 K 自 2017-06 起。當日資料約 17:30 後可查詢。
查詢區間單次須小於 1 年，否則回傳 400。
from／to 以交易日計，夜盤歸屬次一交易日：例如 session=afterhours&from=2026-09-10&to=2026-09-10 回傳 2026-09-09 15:00 至 2026-09-10 05:00 的夜盤。
查無資料時回傳 404，而非空陣列。
連續合約（1!／2!／3!）於到期合約的次一交易日換月，不做換月價差調整，換月日的 K 線會有跳空；只在月契約之間排序，不含週契約。
分 K 只計單式委託成交（不含價差委託的兩腿與鉅額交易），因此日 K 成交量可能大於當日分 K 加總。

日內契約代碼換算

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

日內代碼	查詢參數
`TXFI6`	`product=TXF`、`contractMonth=202609`
`TXF1!`	`product=TXF`、`contractMonth=1!`
`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	K 線週期	—
`sort`*	string	排序方向（`desc` 或 `asc`）	—
`strikePrice`	number	選擇權專用。查詢時帶入的履約價	—
`callPut`	string	選擇權專用。查詢時帶入的買賣權，`CALL` 或 `PUT`	—
`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.open`	number	K 線開盤價；無成交的 K 線為 `null`	全部
`data.high`	number	K 線最高價；無成交的 K 線，或期交所未提供時為 `null`	全部
`data.low`	number	K 線最低價；無成交的 K 線，或期交所未提供時為 `null`	全部
`data.close`	number	K 線收盤價；無成交的 K 線為 `null`	全部
`data.volume`	number	K 線成交量（口數），無成交為 `0`	全部
`data.average`	number	該根 K 線期間的成交量加權平均價（VWAP）	僅分 K
`data.transaction`	number	該根 K 線的成交筆數	僅分 K
`data.change`	number	K 線漲跌；無成交的 K 線為 `null`	僅日／週／月 K

info

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

Examples

日 K 範例（連續合約）

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

Python
Node.js
C#

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

const { FubonSDK } = require('fubon-neo');

const sdk = new FubonSDK();

const accounts = sdk.login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.initRealtime(); // 建立行情連線

const client = sdk.marketdata.restClient
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));

using FubonNeo.Sdk;
using FugleMarketData.QueryModels.FuOpt.Historical;   //引入 HistoricalTimeFrame、HistoricalFieldsType

var sdk = new FubonSDK();
var result = sdk.Login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.InitRealtime(); // 建立行情連線

var rest = sdk.MarketData.RestClient.FutureOption;

var candles = await rest.Historical.Candles("TXF", new(new DateTime(2026,8,17), new DateTime(2026,8,21), HistoricalTimeFrame.Day, HistoricalFieldsType.Open|HistoricalFieldsType.High|HistoricalFieldsType.Low|HistoricalFieldsType.Close|HistoricalFieldsType.Volume|HistoricalFieldsType.Change, "1!"));

var candles_cont = candles.Content.ReadAsStringAsync().Result;

Console.WriteLine(candles_cont);

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）：

Python
Node.js
C#

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

const { FubonSDK } = require('fubon-neo');

const sdk = new FubonSDK();

const accounts = sdk.login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.initRealtime(); // 建立行情連線

const client = sdk.marketdata.restClient
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));

using FubonNeo.Sdk;
using FugleMarketData.QueryModels.FuOpt.Historical;   //引入 HistoricalTimeFrame、HistoricalFieldsType

var sdk = new FubonSDK();
var result = sdk.Login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.InitRealtime(); // 建立行情連線

var rest = sdk.MarketData.RestClient.FutureOption;

var candles = await rest.Historical.Candles("TXF", new(new DateTime(2026,9,10), new DateTime(2026,9,10), HistoricalTimeFrame.SixtyMin, HistoricalFieldsType.Open|HistoricalFieldsType.High|HistoricalFieldsType.Low|HistoricalFieldsType.Close|HistoricalFieldsType.Volume|HistoricalFieldsType.Average|HistoricalFieldsType.Transaction, "202609"));

var candles_cont = candles.Content.ReadAsStringAsync().Result;

Console.WriteLine(candles_cont);

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 線：

Python
Node.js
C#

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

const { FubonSDK } = require('fubon-neo');

const sdk = new FubonSDK();

const accounts = sdk.login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.initRealtime(); // 建立行情連線

const client = sdk.marketdata.restClient
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));

using FubonNeo.Sdk;
using FugleMarketData.QueryModels.FuOpt;              //引入 TradeSession
using FugleMarketData.QueryModels.FuOpt.Historical;   //引入 HistoricalTimeFrame

var sdk = new FubonSDK();
var result = sdk.Login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.InitRealtime(); // 建立行情連線

var rest = sdk.MarketData.RestClient.FutureOption;

var candles = await rest.Historical.Candles("TXF", new(new DateTime(2026,9,10), new DateTime(2026,9,10), HistoricalTimeFrame.SixtyMin, contractMonth: "202609", session: TradeSession.AfterHours));

var candles_cont = candles.Content.ReadAsStringAsync().Result;

Console.WriteLine(candles_cont);

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

'*' 表示必揭示欄位。

選擇權日 K 範例

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

Python
Node.js
C#

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": "TXO", "contractMonth": "202610", "strikePrice": 48000, "callPut": "CALL", "from": "2026-10-01", "to": "2026-10-07", "fields": "open,high,low,close,volume,change"})
except FugleAPIError as e:
  print(f"Error: {e}")
  print("------------")
  print(f"Status Code: {e.status_code}")  # 例: 400
  print(f"Response Text: {e.response_text}")  # 例: {"message":"strikePrice and callPut must be given together","error":"Bad Request","statusCode":400}

const { FubonSDK } = require('fubon-neo');

const sdk = new FubonSDK();

const accounts = sdk.login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.initRealtime(); // 建立行情連線

const client = sdk.marketdata.restClient
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));

using FubonNeo.Sdk;
using FugleMarketData.QueryModels.FuOpt;              //引入 FutOptCallPut
using FugleMarketData.QueryModels.FuOpt.Historical;   //引入 HistoricalTimeFrame、HistoricalFieldsType

var sdk = new FubonSDK();
var result = sdk.Login("Your ID", "Your Password", "Your Cert Path", "Your Cert Password");

sdk.InitRealtime(); // 建立行情連線

var rest = sdk.MarketData.RestClient.FutureOption;

var candles = await rest.Historical.Candles("TXO", new HistoricalCandlesRequest(
    from: new DateTime(2026,10,1),
    to: new DateTime(2026,10,7),
    timeFrame: HistoricalTimeFrame.Day,
    fields: HistoricalFieldsType.Open|HistoricalFieldsType.High|HistoricalFieldsType.Low|HistoricalFieldsType.Close|HistoricalFieldsType.Volume|HistoricalFieldsType.Change,
    contractMonth: "202610",
    strikePrice: 48000m,
    callPut: FutOptCallPut.Call));

var candles_cont = candles.Content.ReadAsStringAsync().Result;

Console.WriteLine(candles_cont);

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​

Examples​

日 K 範例（連續合約）​

分 K 範例​

夜盤範例​

選擇權日 K 範例​

Parameters

日內契約代碼換算

Response

Examples

日 K 範例（連續合約）

分 K 範例

夜盤範例

選擇權日 K 範例