獲取自選股

GET /v1/quote/user-security

獲取用戶指定自選分組下的證券（自選股）列表，返回每隻標的的代碼、名稱、每手股數、證券類型及衍生品信息。

請求參數

參數	類型	位置	必填	說明
group_name	string	查詢	是	自選分組名稱（需 URL 編碼），最長 100 字符。分組名可由 user-security-group 獲取。
X-Futu-Client-Nnid	string	請求頭	是	用戶身份（牛牛號）。

請求示例

curl -G "$ip/v1/quote/user-security" \
  --data-urlencode 'group_name=美股期权' \
  -H 'X-Futu-Client-Nnid: 99034182' | jq

響應字段

字段	類型	說明
code	string	證券代碼，如 US.AAPL。
name	string	證券名稱。
lot_size	int	每手股數（期權=合約股數，期貨=合約乘數）。
stock_type	string	證券類型：STOCK / ETF / WARRANT / IDX / DRVT / FUTURE / FOREX / CRYPTO / BOND 等。
stock_child_type	int	證券子類型數值。
stock_owner	string	標的正股代碼；非衍生品為空串。
option_type	string	期權方向：ALL（非期權）/ CALL / PUT。
strike_time	string	期權行權日（yyyy-MM-dd）；非期權為空串。
strike_price	double	期權行權價；非期權為 0。
listing_date	string	上市日期（yyyy-MM-dd）；無則空串。
stock_id	int	證券內部數值 ID。
main_contract	bool	是否期貨主連合約；非期貨恆 false。
last_trade_time	string	期權/期貨最後交易日（yyyy-MM-dd）；不適用為空串。

限制範圍

• 市場：無限制。自選可含 HK / US / 滬深 / JP / SG / AU / KR / MY / CA 等任意市場標的。
• 品類：無限制。正股 / ETF / 窩輪 / 期權 / 期貨 / 指數 / 債券 / 數字貨幣等均可出現。
• 空分組返回 security_list 為空數組（合法，非錯誤）。

錯誤碼

ret_code	error.code	觸發條件	處理建議
0	—	成功（空分組返回空數組）。	正常解析 security_list。
-3	invalid_parameter	缺 group_name / 超長(>100) / 分組名不存在。	校驗入參；用 user-security-group 確認分組名。
-9	permission_denied	缺 X-Futu-Client-Nnid 鑒權頭。	補齊用戶身份後重試。
-5	internal_error	網關編排 / 後端 RPC 異常。	重試；持續失敗聯繫服務方。

響應示例

{
  "ret_code": 0,
  "ret_msg": "success",
  "data": {
    "security_list": [
      {
        "code": "US.SPY260526C735000",
        "name": "SPY 260526 735.00C",
        "lot_size": 100,
        "stock_type": "DRVT",
        "stock_child_type": 8002,
        "stock_owner": "US.SPY",
        "option_type": "CALL",
        "strike_time": "2026-05-26",
        "strike_price": 735.0,
        "listing_date": "",
        "stock_id": 507601755,
        "main_contract": false,
        "last_trade_time": ""
      }
    ]
  }
}