Stock Screen

POST /api/v1.0/quote/stock-screen

Conditional stock screening: combine N filter conditions to filter, sort, and paginate across the entire market, returning multiple columns for each matched security based on specified retrieval factors. For warrant screening use warrant-screen; for option screening use option-screen.

Parameters

Name	Type	In	Required	Description
screen_queries	object[]	body	yes	Filter condition array. Each element is a "1-of-11" query object -- simple_field_query (market/exchange/index/northbound sector enum field IN list) / plate_query (plate filter) / simple_property_query (quote/valuation factor range) / cumulative_property_query (cumulative quote range, requires period) / financial_property_query (financial factor range, requires fiscal period) / indicator_positional_query (technical indicator positional relationship) / indicator_pattern_query (technical pattern) / featured_property_query (featured factor) / broker_holdings_query (broker holdings, HK only) / kline_shape_query (K-line pattern) / option_query (option indicator). Ranges use lower={value, includes} / upper={value, includes}, where value is pre-multiplied by the field's multiplier.
retrieve_queries	object[]	body	no	Retrieval factor array. Each element is a "1-of-9" retrieve object -- basic_property / simple_property / cumulative_property / financial_property / featured_property / indicator_property / broker_property / kline_shape_property / option_property. Return order aligns exactly with retrieve_queries.
sort	object	body	no	Single-field sort (mutually exclusive with sorts; sorts takes priority). Structure: {direction, simple_property:{name}} (can also use cumulative_property / financial_property / featured_property). direction: 1=ASC, 2=DESC, 3=ASC by absolute value, 4=DESC by absolute value.
sorts	object[]	body	no	Multi-field sort, priority by array order. Each element has the same structure as sort.
next_key	string	body	no	Pagination cursor. Leave empty for the first page; pass back the previous page's pagination.next_key.
limit	int	body	no	Page size. Default 200, max 300.
watchlist_stock_ids	int[]	body	no	Watchlist stock_id list. Used with user_stock_list_mode=1 to screen within watchlist scope.
holding_stock_ids	int[]	body	no	Holdings stock_id list. Used with user_stock_list_mode=2 to screen within holdings scope.
user_stock_list_mode	int	body	no	User stock list filter mode: 0=unrestricted (default) / 1=watchlist only / 2=holdings only.

Request Example

curl -X POST "https://webapi.moomoo.com/api/v1.0/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

Response Fields

Field	Type	Description
pagination.total	int	Total number of securities matching the criteria.
pagination.has_more	bool	Whether there is a next page.
pagination.next_key	string	Next page cursor; "-1" when no more pages.
items	object[]	List of matching securities.
items[].code	string	Security code (with market prefix), e.g. HK.00700.
items[].name	string	Symbol English name.
items[].sc_name	string	Symbol Simplified Chinese name.
items[].tc_name	string	Symbol Traditional Chinese name.
items[].results	object[]	Retrieval results for each retrieve_queries factor, aligned in order with retrieve_queries. Each element is a result wrapper of the corresponding type. res.ival is the raw backend integer (multiplied), res.dval is float, res.sval is string; result_type: 1=double, 2=int, 3=string.

Scope & Limits

• Supported markets: HK (Hong Kong) / US (United States) / CN (A-shares) / SG (Singapore) / CA (Canada) / AU (Australia) / JA (Japan) / MY (Malaysia).
• Supported categories: Stocks / ETF / Index / REIT and other securities within screening scope; use warrant-screen for warrants, option-screen for options.
• broker_holdings_query / kline_shape_query only available for HK market; option_query requires the security to have options.
• Single page limit max 300; next_key is an opaque cursor.
• Valid but no-hit queries (overly strict filters, or unsupported markets) return ret_code=0 + items=[] + pagination.total=0. Empty results are a success, not an error.

Error Codes

ret_code	error.code	Trigger Condition	Handling
-3	invalid_parameter	Missing required screen_queries; limit > 300; invalid next_key; user_stock_list_mode value not in {0,1,2}; other field type errors.	Correct the request body and retry.
-5	internal_error	Backend rejected request (e.g. invalid enum in simple_field_query, non-existent property name, market value out of range).	Check query structure and property name / market value validity, then retry.
-6	internal_error	BFF output mapping failure.	Contact BFF maintainer for investigation.

Response Example

{
  "ret_code": 0,
  "ret_msg": "success",
  "data": {
    "items": [
      {
        "code": "HK.05432",
        "name": "...",
        "sc_name": "...",
        "tc_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": "TENCENT",
        "sc_name": "腾讯控股",
        "tc_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 }
}