关联期货

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

获取指定标的关联的期货合约清单。典型用法是传入期货主连合约代码（如 HK.HSImain），拿到该品种下全部相关合约（主连 / 当月 / 下月 / 各到期月份合约等）。非期货标的或无关联期货时返回空 reference_list。

请求参数

参数	类型	位置	必填	说明
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"
      }
    ]
  }
}