跳转至

升版至 1.7.0

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

新增什麼功能？

1. 體驗升級

  • 不用再自己管理商品合約更新：以前您得記住商品合約的更新時間、並挑在更新後才登入才能拿到最新商品，期貨夜盤的交易者尤其困擾。1.7.0 起，商品合約會在有更新時自動保持最新，您不必再關心更新時機。
  • 登入更快：登入不再下載整份商品合約，改為第一次查詢某類商品時才自動載入，可立即開始操作。

2. 全新 api.contracts 查詢 API

用單一個 api.contracts 入口查詢所有商品，並提供舊寫法沒有的查詢能力：

  • 統一查詢：以 get() 查詢任何商品（股票、期貨、指數…），不必再區分商品類別。
  • 以標的反查衍生商品：查詢某檔股票有哪些期貨、權證。
  • 依條件篩選：選擇權、權證可依履約價、到期日等條件篩選。
  • 更豐富的商品資訊：新的資訊物件提供更完整的欄位，例如證券的融資融券餘額、當沖資格、處置與注意狀態等，詳見商品合約。

3. 指數支援強化

  • 指數代碼標準化：指數改用交易所代碼（如加權指數為 IX0001），與交易所一致。
  • 指數即時行情：可訂閱指數（如加權指數 IX0001）的即時報價，詳見指數即時行情。

如何遷移至 1.7？

1. 不需改動的部分

大部分寫法都不變，包含：

  • 舊寫法 api.Contracts.Stocks["2330"]、api.Contracts.Futures.TXF.TXFR1 等仍可使用。
  • 下單、訂閱行情、查詢歷史資料的用法不變。
  • 將查到的商品傳入 api.subscribe、api.kbars、下單等操作，用法與先前相同。

2. 登入參數移除

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

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

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

3. 指數代碼改用交易所代碼

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

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

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

4. SecurityType.Future 更名為 Futures

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

sj.SecurityType.Future

sj.SecurityType.Futures

5. 查詢商品回傳的物件已改名

查詢商品所回傳的物件，已從先前的 Stock、Future、Option、Index 改為 StockInfo、FuturesInfo、OptionInfo、IndexInfo（新增 WarrantInfo）。不論使用 api.Contracts（舊寫法）或 api.contracts（新寫法）查詢，回傳的都是這些新的資訊物件。

新舊物件的欄位有部分差異，若您的程式引用到只存在於舊物件的欄位（如 symbol），請一併調整。

6. HTTP 列出商品改為 GET

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

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。從商品合約開始了解新的查詢方式。