股票篩選

POST /v1/quote/stock-screen

條件選股：組合 N 個篩選條件對全市場標的過濾、排序、分頁，並按指定取值因子返回每隻命中標的的多個列。窩輪篩選請用 warrant-screen；期權篩選請用 option-screen。

請求參數

參數	類型	位置	必填	說明
screen_queries	object[]	請求體	是	篩選條件數組，每元素是「11 選 1」的 query 對象——simple_field_query（市場/交易所/指數/北向板塊等枚舉字段 IN 列表）/ plate_query（板塊篩選）/ simple_property_query（行情·估值因子區間）/ cumulative_property_query（累計行情區間，需帶週期）/ financial_property_query（財務因子區間，需帶財報期）/ indicator_positional_query（技術指標位置關係）/ indicator_pattern_query（技術形態）/ featured_property_query（特色因子）/ broker_holdings_query（經紀商持股，僅 HK）/ kline_shape_query（K 線形態）/ option_query（期權指標）。區間用 lower={value, includes} / upper={value, includes}，value 已按字段倍率預放大。
retrieve_queries	object[]	請求體	否	取值因子數組，每元素是「9 選 1」的 retrieve 對象——basic_property / simple_property / cumulative_property / financial_property / featured_property / indicator_property / broker_property / kline_shape_property / option_property。返回順序與 retrieve_queries 完全對齊。
sort	object	請求體	否	單字段排序（與 sorts 二選一，sorts 優先）。結構 {direction, simple_property:{name}}（也可換成 cumulative_property / financial_property / featured_property）。direction：1=升序，2=降序，3=按絕對值升序，4=按絕對值降序。
sorts	object[]	請求體	否	多字段排序，按數組順序分主次，每元素同 sort。
next_key	string	請求體	否	翻頁游標，首頁留空；回傳上一頁 pagination.next_key。
limit	int	請求體	否	單頁條數，預設 200，最大 300。
watchlist_stock_ids	int[]	請求體	否	自選股 stock_id 列表，配合 user_stock_list_mode=1 在自選範圍內篩選。
holding_stock_ids	int[]	請求體	否	持倉 stock_id 列表，配合 user_stock_list_mode=2 在持倉範圍內篩選。
user_stock_list_mode	int	請求體	否	用戶股票列表篩選模式：0=不限制（預設）/ 1=僅在自選股範圍內 / 2=僅在持倉範圍內。

請求示例

curl -X POST "$ip/v1/quote/stock-screen" \
  -H "Content-Type: application/json" \
  -d '{"limit":3,"screen_queries":[{"simple_field_query":{"simple_field":1,"screen_value_list":[1]}}],"retrieve_queries":[{"simple_property":{"name":2201}},{"simple_property":{"name":2301}},{"simple_property":{"name":2303}}],"sort":{"direction":2,"simple_property":{"name":2301}}}' | jq

響應字段

字段	類型	說明
pagination.total	int	滿足條件的標的總數。
pagination.has_more	bool	是否還有下一頁。
pagination.next_key	string	下一頁游標；無更多頁為 "-1"。
items	object[]	命中標的列表。
items[].code	string	標的 code（含市場前綴），如 HK.00700。
items[].name	string	標的中文名。
items[].results	object[]	該標的對應每個 retrieve_queries 因子的取值結果，與 retrieve_queries 等長按序對應。每元素為對應類型的 result wrapper，res.ival 是後端原始整數（已乘倍率），res.dval 浮點，res.sval 字符串；result_type：1=double, 2=int, 3=string。

限制範圍

• 支持市場：HK 港股 / US 美股 / CN A 股 / SG 新加坡 / CA 加拿大 / AU 澳大利亞 / JA 日本 / MY 馬來西亞（KR 韓國暫不支持，傳入會返回空結果）。
• 支持品類：正股 / ETF / 指數 / REIT 等可在篩選範圍內的標的；窩輪請用 warrant-screen，期權請用 option-screen。
• broker_holdings_query / kline_shape_query 僅 HK 市場可用；option_query 需標的有期權。
• 單頁 limit 最大 300；next_key 為不透明游標。
• 合法但無命中（過嚴篩選、或傳入不支持的市場如 KR 等）返回 ret_code=0 + items=[] + pagination.total=0，空結果集是成功而非錯誤。

錯誤碼

ret_code	error.code	觸發條件	處理建議
-3	invalid_parameter	缺必填 screen_queries；limit > 300；next_key 非法；user_stock_list_mode 取值不在 {0,1,2} 內；其它字段類型錯誤。	校正請求體後重試。
-5	internal_error	後端拒絕請求（如 simple_field_query 內傳入非法枚舉值、property name 不存在、市場值越界等）。	檢查 query 結構與 property name / market 值的合法性後重試。
-6	internal_error	BFF 出參映射失敗。	聯繫 BFF 維護方排查。

響應示例

{
  "ret_code": 0,
  "ret_msg": "success",
  "data": {
    "items": [
      {
        "code": "HK.05432",
        "name": "...",
        "results": [
          { "simple_property_result": { "property": { "name": 2201 }, "res": { "ival": "25000", "result_type": 2 }, "value": "25000" } },
          { "simple_property_result": { "property": { "name": 2301 }, "res": { "ival": "8055310295350000", "result_type": 2 }, "value": "8055310295350000" } },
          { "simple_property_result": { "property": { "name": 2303 }, "res": { "result_type": 2 }, "value": "0" } }
        ]
      },
      {
        "code": "HK.00700",
        "name": "騰訊控股",
        "results": [
          { "simple_property_result": { "property": { "name": 2201 }, "res": { "ival": "455000", "result_type": 2 }, "value": "455000" } },
          { "simple_property_result": { "property": { "name": 2301 }, "res": { "ival": "4148746188860000", "result_type": 2 }, "value": "4148746188860000" } },
          { "simple_property_result": { "property": { "name": 2303 }, "res": { "ival": "1558005", "result_type": 2 }, "value": "1558005" } }
        ]
      }
    ]
  },
  "pagination": { "has_more": true, "next_key": "3", "total": 2938 }
}