跳至主要内容

核心概念

交易日與時段​

交易日是該商品所屬交易所的營業日，寫成 YYYY-MM-DD。它不一定等於每一筆 資料的日曆日期：晚上開始的時段可能屬於下一個交易日。這取決於交易所與商品， 不是全產品統一的規則。

GET /v2/catalog/calendar 以 UTC 回傳時段，kind 是交易所的標籤，例如 night、day、auction、pre、regular 或 post。標籤是開放集合；不認得 的值就當成一般時段。

不要假設：

  • 每個交易所都有夜盤；
  • 夜盤一定屬於下一個交易日；
  • 同一交易所的兩個商品共用時段樣板。

請讀你所用交易所與商品的日曆。

時間戳與資料順序​

每筆資料列都有：

  • ts：交易所事件時間，RFC 3339 UTC，奈秒精度；
  • trading_day：這筆資料所屬的交易日；
  • seq：同一商品、同一交易日、同一時間戳內的順序。

資料依商品、再依 (ts, seq) 排序。跨商品查詢時，會先回完一個商品的時間序列， 再接下一個商品。

請求用交易日（trading_day，或 from_day 與 to_day）或時間點（start 含、end 不含）。時間點必須帶時區或 Z。

代號​

公開代號是 VENUE.code，例如 SHFE.rb2701、SSE.600000 或 SHFE.rb.main。code 的形狀由交易所決定：

  • 期貨交易所的商品加交割月（SHFE.rb2701）；
  • 證券交易所的交易所代碼（SSE.600000）；
  • 選擇權序列（SHFE.rb2701-C-3000）；
  • veinmesh 連續合約（SHFE.rb.main、SHFE.rb.c1）。

代號依日期解析。同一天同一個拼法對到兩個商品時，API 回 ambiguous_symbol；請改用完整代號或 instrument_id。instrument_id 永不 變更、永不重用。

精確小數​

價格、數量、乘數與最小跳動都是精確小數。JSON 預設以字串回傳，例如 "3061" 或 "0.01"，避免浮點誤差。加 numbers=float 可改收 JSON 數字。

Python SDK 的 to_pandas() 預設把小數轉成 float；傳 exact=True 可保留 Decimal。

分頁與目錄版本​

資料端點一次回一頁。把回應的 next_cursor 當成 cursor 傳回即可取下一頁； 最後一頁的 next_cursor 是 null。cursor 只屬於產生它的查詢與金鑰。

每個回應都帶 catalog_version，代表解析代號與分區所用的目錄快照。把它傳回 可固定可重現的結果。服務只保留有限版本的目錄；太舊的版本回 version_unavailable（410）。K 線回應另外帶 calc_version，代表計算規則的 版本。

API 的相容承諾​

/v2 只做加法變更：新路由、新選填參數、新回應欄位與新列舉值。用戶端必須忽略 不認得的欄位，並把不認得的列舉值視為「其他」。不會默默改變既有請求的語意。

錯誤一律是 application/problem+json（RFC 9457）。請依 code 分支，不要依 detail；detail 是給人看的，可能改寫。見錯誤。

哪些規則不能跨市場套用​

以下是交易所或資料集決定的，不是 veinmesh 的產品規則：

  • 是否有夜盤，以及夜盤屬於哪個交易日；
  • 代號形狀，包括交割月的寫法；
  • 主力合約的定義與換月規則；
  • 成交量是否為累計值，以及何時重置；
  • K 線 anchor=session 使用的時段邊界。

請從目錄、資料集 schema 與日曆讀取。本手冊描述目前服務市場的行為，不是所有 交易所的規則書。