股票筛选

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 }
}