升版至 1.7.0¶

1.7.0 重寫了商品合約的運作方式，帶來全新的 api.contracts 查詢 API，並讓商品合約自動保持最新。您現有的程式碼基本不需修改即可運作，可以在方便時再逐步改用新寫法。

更新焦點¶

1.7.0 的更新集中在商品合約，主要有三個方向：

合約自動保持最新：不必再自己管理更新時機，登入也更快——登入不再下載整份合約，改為查詢時才自動載入。
全新 api.contracts 查詢：以統一入口查詢所有商品，並可反查衍生商品、依條件篩選；合約資訊也更豐富。
指數支援強化：指數改用交易所代碼（如加權指數 IX0001），並可訂閱指數即時行情。

這些更新中，多數不影響您現有的程式；少數需要調整的地方，整理在下方如何遷移至 1.7？

新增什麼功能？¶

1. 全新 `api.contracts` 查詢¶

在 1.5，我們使用 api.Contracts（大寫）查詢商品——需要先知道商品屬於哪一類，再從對應分類逐層存取，例如股票 api.Contracts.Stocks["2330"]、期貨 api.Contracts.Futures.TXF。

在 1.7.0，我們新增了 api.contracts（小寫）查詢入口：用 get() 一個方法就能查任何商品，不必再分類別；並提供 futures_by_underlying() 以標的反查衍生商品、options() 依條件篩選等舊寫法沒有的函數。

查詢能力	`api.Contracts`（舊）	`api.contracts`（新）
統一查詢（不分類別）	需分類別存取，如 `api.Contracts.Stocks["2330"]`	`api.contracts.get("2330")` 查任何商品
以標的反查衍生商品	不支援	`api.contracts.futures_by_underlying(c)` 查標的有哪些期貨
依條件篩選	不支援	`api.contracts.options(root, ...)` 依履約價、到期日篩選
列出某類全部商品	`list(api.Contracts.Stocks)`	`api.contracts.list(sj.SecurityType.Stock)`

建議改用 api.contracts

舊寫法 api.Contracts（大寫）仍可使用，兩種可並存；但後續將不再維護，建議您逐步改用新的 api.contracts（小寫）。

合約物件與合約資訊物件

api.contracts 把查詢結果拆為兩種物件：

合約物件（Contract）：只包含識別商品的欄位（security_type、region、exchange、code、target_code），輕量。以 api.contracts.get(代碼) 取得。下單、訂閱行情只需要這個物件。
合約資訊物件（StockInfo 等）：包含名稱、漲跌停、融資融券餘額等完整欄位。以 api.contracts.info(合約物件) 取得。需要查看商品詳細資料時才使用。

	`api.Contracts`（舊）	`api.contracts`（新）
取得合約物件（識別用）	—（一次回傳完整物件）	`api.contracts.get("2330")`
取得合約資訊物件（完整欄位）	`api.Contracts.Stocks["2330"]`	`api.contracts.info(合約物件)`

流量節省

舊的 api.Contracts 會把完整資料整包下載；而 api.contracts.get() 只下載合約物件的資料量，不會連完整欄位一起抓——要完整欄位時才透過 info() 取得。若您只是要下單、訂閱行情，用 get() 即可，無需負擔完整資料的流量。

2. 指數即時行情¶

1.7.0 可訂閱指數（如加權指數 IX0001）的即時報價。詳見指數即時行情。

如何遷移至 1.7？¶

以下列出 1.5.x 到 1.7.0 需要注意的變更。您現有的下單、訂閱行情、傳入合約等用法都不變；「是否必須改」欄只標出真正需要動手的項目。點擊變更項目可跳至下方對應說明。

變更項目	1.5.x	1.7.0	是否必須改
登入參數	`login()` 的 `fetch_contract`／`contracts_timeout`／`contracts_cb`	三個參數移除	是，若有使用
合約下載管理	`api.fetch_contracts()`、`api.Contracts.status`	移除，改為查詢時自動載入	是，若有輪詢狀態
合約物件	`api.Contracts.Stocks["2330"]` 回傳 `Stock`／`Future`／`Option`／`Index`	同一寫法改回傳 `StockInfo` 等，欄位有改名／移除／型別變更	是，若讀取已變動的欄位
指數代碼	`api.Contracts.Indexs.TSE["001"]`	`api.Contracts.Indexs.TSE["IX0001"]`	是，若有使用指數
`SecurityType`	`sj.SecurityType.Future`（單數）	`sj.SecurityType.Futures`（複數）	是，若有使用
HTTP 列出商品	`POST` + JSON body	`GET` + query 參數	是，僅 HTTP

login() 不再於登入時下載商品合約，fetch_contract、contracts_timeout、contracts_cb 三個參數已移除，請從您的登入程式中移除這些參數。

1.51.7

api.login(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
    fetch_contract=True,
    contracts_timeout=10000,
    contracts_cb=lambda st: print(f"{st} fetch done."),
)

api.login(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
)

2. 合約下載管理¶

1.7.0 起商品合約改為「查詢時自動載入、自動保持最新」，登入後不需再手動下載。因此 1.5 用來手動下載合約的 api.fetch_contracts()、以及查詢下載狀態的 api.Contracts.status 都不再需要；若您的程式有呼叫這些方法或輪詢下載狀態，請一併移除。

1.51.7

api.login(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
    fetch_contract=False,
)
api.fetch_contracts(contract_download=True)   # 手動下載

api.login(
    api_key="YOUR_API_KEY",
    secret_key="YOUR_SECRET_KEY",
)
# 不需手動下載，查詢時自動載入

3. 合約物件¶

您的舊寫法 api.Contracts.Stocks["2330"]、api.Contracts.Futures.TXF.TXFR1 等照樣能用，但查詢後回傳的物件，已從先前的 Stock、Future、Option、Index 改為 StockInfo、FuturesInfo、OptionInfo、IndexInfo（並新增 WarrantInfo）。各型別的欄位變更與新舊物件對照如下：

證券期貨選擇權指數權證

Stock → StockInfo，欄位變更：

1.5	1.7.0	如何調整
`symbol`	已移除	改用 `code`
`update_date`	字串 `'2026/07/17'` → `datetime.date`	若原本做字串處理（如 `.split("/")`），改為直接使用 `date`

1.51.7.0

Stock(
    exchange=<Exchange.TSE: 'TSE'>,
    code='2330',
    symbol='TSE2330',
    name='台積電',
    category='24',
    unit=1000.0,
    limit_up=2715.0,
    limit_down=2225.0,
    reference=2470.0,
    update_date='2026/07/17',
    margin_trading_balance=15,
    short_selling_balance=98,
    day_trade=<DayTrade.Yes: 'Yes'>,
)

StockInfo(
    Contract(security_type='STK', region='TW', exchange='TSE', code='2330'),
    code='2330',
    name='台積電',
    category='24',
    currency=<Currency.TWD: 'TWD'>,
    unit=1000.0,
    day_trade=<DayTrade.Yes: 'Yes'>,
    reference=2470.0,
    limit_up=2715.0,
    limit_down=2225.0,
    margin_trading_balance=15,
    short_selling_balance=98,
    trading_suspended=False,
    margin_loan_ratio=0.6,
    margin_quota_lots=15,
    short_margin_ratio=0.9,
    short_quota_lots=98,
    short_selling_suspended=False,
    disposition_level=0,
    attention_flag=False,
    short_below_par_eligible=True,
    slb_below_par_eligible=True,
    etf_constituent=True,
    settlement_type='0',
    update_date=datetime.date(2026, 7, 17),
)

Future → FuturesInfo，欄位變更：

1.5	1.7.0	如何調整
`symbol`	已移除	改用 `code`
`category`	改名為 `root`	改用 `root`
`unit`	已移除	—
`delivery_date`、`update_date`	字串 → `datetime.date`	若原本做字串處理，改為直接使用 `date`

1.51.7.0

Future(
    code='TXFR1',
    symbol='TXFR1',
    name='臺股期貨近月',
    category='TXF',
    delivery_month='202608',
    delivery_date='2026/08/19',
    underlying_kind='I',
    unit=1.0,
    limit_up=46864.0,
    limit_down=38344.0,
    reference=42604.0,
    update_date='2026/07/17',
    target_code='TXFH6',
)

FuturesInfo(
    Contract(security_type='FUT', region='TW', exchange='TAIFEX', code='TXFR1', target_code='TXFH6'),
    code='TXFR1',
    name='臺股期貨 近月',
    root='TXF',
    delivery_month='202608',
    delivery_date=datetime.date(2026, 8, 19),
    last_trading_date=datetime.date(2026, 8, 19),
    begin_date=datetime.date(2026, 5, 21),
    underlying_kind='I',
    underlying_code='IX0001',
    multiplier=200.0,
    contract_size=200.0,
    size_unit='pt',
    quote_ccy='TWD',
    tick_basis='fixed',
    tick=1.0,
    tick_value=200.0,
    spec_kind='index_fut',
    decimal_locator=2,
    dynamic_banding=True,
    flow_group='10',
    reference=42604.0,
    limit_up=46864.0,
    limit_down=38344.0,
    update_date=datetime.date(2026, 7, 17),
)

Option → OptionInfo，欄位變更：

1.5	1.7.0	如何調整
`symbol`	已移除	改用 `code`
`category`	改名為 `root`	改用 `root`
`unit`	已移除	—
`delivery_date`、`update_date`	字串 → `datetime.date`	若原本做字串處理，改為直接使用 `date`

1.51.7.0

Option(
    code='TXO34000H6',
    symbol='TXO20260834000C',
    name='臺指選擇權F508月 34000C',
    category='TXO',
    delivery_month='202608',
    delivery_date='2026/08/19',
    strike_price=34000.0,
    option_right=<OptionRight.Call: 'C'>,
    underlying_kind='I',
    unit=1.0,
    limit_up=16270.0,
    limit_down=7150.0,
    reference=11710.0,
    update_date='2026/07/17',
)

OptionInfo(
    Contract(security_type='OPT', region='TW', exchange='TAIFEX', code='TXO34000H6'),
    code='TXO34000H6',
    name='臺指選擇權 202608 C 34000',
    root='TXO',
    delivery_month='202608',
    delivery_date=datetime.date(2026, 8, 19),
    last_trading_date=datetime.date(2026, 8, 19),
    begin_date=datetime.date(2026, 5, 21),
    strike_price=34000.0,
    option_right=<OptionRight.Call: 'C'>,
    expiry_weekday='Wed',
    week_of_month=3,
    underlying_kind='I',
    underlying_code='IX0001',
    multiplier=50.0,
    contract_size=50.0,
    size_unit='pt',
    quote_ccy='TWD',
    tick_basis='premium',
    tick_rule='tw_txo_premium_band',
    tick=10.0,
    tick_value=500.0,
    spec_kind='index_opt',
    decimal_locator=3,
    strike_decimal_locator=0,
    dynamic_banding=True,
    flow_group='1',
    reference=11710.0,
    limit_up=16270.0,
    limit_down=7150.0,
    update_date=datetime.date(2026, 7, 17),
)

Index → IndexInfo，欄位變更：

1.5	1.7.0	如何調整
`symbol`	已移除	改用 `code`
`code`	`'001'` → `'IX0001'`	指數改用交易所代碼，詳見指數代碼

1.51.7.0

Index(
    exchange=<Exchange.TSE: 'TSE'>,
    code='001',
    symbol='TSE001',
    name='加權指數',
)

IndexInfo(
    Contract(security_type='IND', region='TW', exchange='TSE', code='IX0001'),
    code='IX0001',
    name='發行量加權股價指數',
    reference=45624.98,
    open_time='09:00',
    close_time='13:30',
    update_date=datetime.date(2026, 7, 17),
)

1.5 權證歸類在股票，以 api.Contracts.Stocks[...] 查詢並回傳 Stock（僅有股票通用欄位）。1.7.0 權證獨立為 WarrantInfo，改以 api.contracts.warrants(標的) 從標的反查，並提供履約價、認購／售、行使比例等權證專屬欄位。

1.5	1.7.0	如何調整
`api.Contracts.Stocks["03011T"]`	`api.contracts.warrants(標的)`	改由標的反查權證
`Stock` 物件	`WarrantInfo` 物件	欄位大幅不同，詳見下方對照

1.51.7.0

Stock(
    exchange=<Exchange.TSE: 'TSE'>,
    code='03011T',
    symbol='TSE03011T',
    name='台積電凱基67售14',
    category='00',
    unit=1000.0,
    limit_up=3.7,
    limit_down=0.01,
    reference=1.25,
    update_date='2026/07/17',
)

WarrantInfo(
    Contract(security_type='WRT', region='TW', exchange='TSE', code='03011T'),
    code='03011T',
    underlying_code='2330',
    underlying_type='1',
    call_put='P',
    financial='W4',
    strike_price=1745.34,
    expiry_date=datetime.date(2027, 7, 19),
    last_trading_date=datetime.date(2027, 7, 15),
    exercise_ratio=0.01,
    exercise_style='European',
    listing_date=datetime.date(2026, 4, 20),
    exercise_start_date=datetime.date(2027, 7, 19),
    exercise_end_date=datetime.date(2027, 7, 19),
    barrier_upper=0.0,
    barrier_lower=0.0,
    residual_value=0.0,
    settlement_method='1',
    investor_restriction=' ',
    issue_size=1200,
    name='台積電凱基67售14',
    reference=1.25,
    limit_up=3.7,
    limit_down=0.01,
    update_date=datetime.date(2026, 7, 17),
    exchange='TSE',
    security_type='WRT',
    region='TW',
)

4. 指數代碼改用交易所代碼¶

指數改用交易所代碼（如加權指數為 IX0001），先前版本的指數代碼（如 001）已不適用。若您的程式使用舊的指數代碼，請改用交易所代碼。

1.51.7

api.Contracts.Indexs.TSE["001"]

api.Contracts.Indexs.TSE["IX0001"]

5. `SecurityType.Future` 更名為 `Futures`¶

SecurityType.Future（單數）已更名為 SecurityType.Futures（複數），請改用新名稱。

1.51.7

sj.SecurityType.Future

sj.SecurityType.Futures

6. HTTP 列出商品改為 GET¶

此變更僅影響透過 HTTP 查詢商品的使用者（Python 使用者不受影響）。1.5 以 POST /api/v1/data/contracts + JSON body 列出某一類商品，1.7.0 改為 GET + query 參數：

1.51.7

curl -X POST http://localhost:8080/api/v1/data/contracts \
  -H "Content-Type: application/json" \
  -d '{"security_type":"STK","page":1,"page_size":3}'

curl "http://localhost:8080/api/v1/data/contracts?security_type=STK&page=1&page_size=3"

查詢單一商品的 GET /api/v1/data/contracts/{code} 維持不變。此外，1.7.0 新增了期貨、選擇權、權證等多個查詢端點，用法請見商品合約。

準備好了嗎？¶

舊寫法仍可運作，您可以在方便時逐步改用 api.contracts。從商品合約開始了解新的查詢方式。

升版至 1.7.0¶

更新焦點¶

新增什麼功能？¶

1. 全新 api.contracts 查詢¶

2. 指數即時行情¶

如何遷移至 1.7？¶

1. 登入參數¶

2. 合約下載管理¶

3. 合約物件¶

4. 指數代碼改用交易所代碼¶

5. SecurityType.Future 更名為 Futures¶

6. HTTP 列出商品改為 GET¶

準備好了嗎？¶

1. 全新 `api.contracts` 查詢¶

5. `SecurityType.Future` 更名為 `Futures`¶