關聯期貨

GET /v1/quote/{symbol}/reference-future

獲取標的的關聯期貨合約資訊。

請求參數

參數	類型	位置	必填	說明
symbol	string	路徑	是	標的代碼，通常為期貨主連合約（如 HK.HSImain、US.CLmain、SG.NKmain）。非期貨標的合法但返回空列表。

請求示例

curl '$ip/v1/quote/HK.HSImain/reference-future' | jq

響應字段

返回 data.reference_list[]，每元素一個關聯期貨合約：

字段	類型	說明
code	string	合約代碼，例 HK.HSImain / HK.HSI2606。
stock_name	string	合約名稱，例 恒指期货主连 (2606)。
stock_type	string	證券類型，本接口固定 FUTURE。
lot_size	int	每手股數（合約乘數），例 50。
future_valid	bool	期貨標識位，本接口固定 true。
future_main_contract	bool	是否主連合約。true=主連；false=普通到期合約。
future_last_trade_time	string	最後交易日，格式 YYYY-MM-DD；主連 / 連續合約為空字符串 ""。
list_time	int	上市時間（毫秒時間戳）；無上市時間記錄的合約為 0。

限制範圍

• 支持的市場：HK / US / SG / JP。
• 支持的品類：僅期貨主連合約。
• 其他市場（AU / CA / SH / SZ / KR / MY 等）通常無期貨品種，返回空列表。

錯誤碼

ret_code	error.code	觸發場景	處理建議
0	—	成功；非期貨標的或無關聯期貨時 reference_list 為空 []	視空列表為「該標的無關聯期貨」
-3	invalid_parameter	symbol 缺失、超長（>32）或格式不合法	校正 symbol 格式後重試
-7	invalid_symbol	symbol 在證券緩存中不存在（未知代碼 / 退市等）	確認代碼是否真實存在

響應示例

{
  "ret_code": 0,
  "ret_msg": "success",
  "data": {
    "reference_list": [
      {
        "code": "HK.HSImain",
        "future_last_trade_time": "",
        "future_main_contract": true,
        "future_valid": true,
        "list_time": 0,
        "lot_size": 50,
        "stock_name": "恒指期货主连 (2606)",
        "stock_type": "FUTURE"
      },
      {
        "code": "HK.HSI2605",
        "future_last_trade_time": "2026-05-28",
        "future_main_contract": false,
        "future_valid": true,
        "list_time": 0,
        "lot_size": 50,
        "stock_name": "恒指期货2605",
        "stock_type": "FUTURE"
      }
    ]
  }
}