Skip to content

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 ​

NameTypeInRequiredDescription
screen_queriesobject[]bodyyesFilter 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. Min items 1; Max items 10000
retrieve_queriesobject[]bodynoRetrieval 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. Max items 10000
sortobjectbodynoSingle-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.
sortsobject[]bodynoSort fields, in priority order. Max items 10000
next_keystringbodynoPagination cursor. Leave empty for the first page. Max length 1000; Pattern ^$|^(-?[0-9]+)?$
limitintbodynoPage size. ≤ 300; Default 200
watchlist_stock_idsint[]bodynoWatchlist stock IDs. Pass only when screening within the watchlist. Max items 10000
holding_stock_idsint[]bodynoHolding stock IDs. Pass only when screening within holdings. Max items 10000
user_stock_list_modeintbodynoScope: 0 any, 1 watchlist only, 2 holdings only. Values 0, 1, 2

Request Example ​

bash
curl -X POST "https://webapi.futunn.com/api/v1.0/quote/stock-screen" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <AccessToken>" \
  -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 ​

NameTypeDescription
dataobject
data.itemsobject[]
data.items[].codestringStock symbol with market prefix, e.g. HK.00700
data.items[].namestringStock English name , e.g. TENCENT
data.items[].sc_namestringStock Simplified Chinese name, e.g. 腾讯控股
data.items[].tc_namestringStock Traditional Chinese name, e.g. 騰訊控股
data.items[].resultsobject[]Retrieve-factor results for this symbol corresponding to each retrieve_queries entry , containing basic_property_result / simple_property_result / financial_property_result, etc. res.ival is the raw integer value (including multiplier); result_type=2 means int. Multiplier rule: multiples (PE/PB/PS/PCF/volume ratio/BETA) x1e5; price/change amount x1000; market cap/turnover x1000; percentage factors (change rate/amplitude/turnover rate/dividend yield/all growth·margin·return·holding-ratio etc.) are ALWAYS x1e3 (returned value = percentage x 1000; divide by 1e3 to restore the percentage). e.g. [{simple_property_result:{property:{name:2201}, res:{ival:"505000", result_type:2}, value:"505000"}}]
paginationobject
pagination.totalint
pagination.has_morebool
pagination.next_keystring

Scope & Limits ​

  • Supported markets: HK (Hong Kong) / US (United States) / CN (A-shares) / SG (Singapore) / CA (Canada) / AU (Australia) / JA (Japan) / MY (Malaysia) / KR (Korea).
  • 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 + data.items=[] + pagination.total=0. Empty results are a success, not an error.

Error Codes ​

ret_codeerror.codeTrigger ConditionHandling
-3invalid_parameterMissing 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.
-5internal_errorService errorCheck query structure and property name / market value validity, then retry.
-6internal_errorService errorContact support for investigation.

Response Example ​

json
{
  "ret_code": 0,
  "ret_msg": "success",
  "data": {
    "items": [
      {
        "code": "HK.05432",
        "name": "...",
        "sc_name": "...",
        "tc_name": "...",
        "results": []
      },
      {
        "code": "HK.00700",
        "name": "TENCENT",
        "sc_name": "腾讯控股",
        "tc_name": "騰訊控股",
        "results": []
      }
    ]
  },
  "pagination": {
    "has_more": true,
    "next_key": "3",
    "total": 2938
  }
}