Stock Screening V2

• Python
• Proto
• C#
• Java
• C++
• JavaScript

get_stock_screen(request)

• Description

  Stock screening V2. Compared with the legacy get_stock_filter, this API covers a wider range of factors (11 categories, 244+ factors), accepts raw values for all numeric inputs (OpenD performs magnification conversion automatically), supports single-field or multi-field sorting, requires explicit declaration of retrieve fields, and returns each result through sval / ival / aval / dval according to its value_type.

• Parameters

  Parameter	Type	Description
  request	StockScreenRequest	Stock screening request object, built via builder methods

  • StockScreenRequest fields:

    Field	Type	Description
    page_from	int	Pagination start position Defaults to 0
    page_count	int	Maximum results per page Defaults to 200

  • Filter builder methods (each call appends one filter condition; all numeric fields accept raw values, OpenD performs magnification automatically):

    Method	Description
    add_simple_field(field, values)	Filter by enum field such as market / exchange / index / watchlist field comes from SimpleField; values is a list of enum values (OR-joined). ScrMarket.MY / JP / SG will be supported later; currently the result is empty
    add_plate(plate_ids, parent_plate_id=None)	Plate filter plate_ids like ["BK1001"]
    add_simple_property(name, lower=None, upper=None)	Simple property interval filter name comes from SimpleProperty (price, market cap, PE, volume ratio, etc.); lower / upper are raw values, e.g. price 10 → 10, market cap ≥ 10B → 10_000_000_000
    add_cumulative_property(name, days=1, lower=None, upper=None)	Cumulative property name comes from CumulativeProperty; days is the cumulative window. Percent-style fields (e.g. PRICE_CHANGE_PCT) take a decimal value (5% as 0.05, NOT 5.0)
    add_financial_property(name, term=None, year=None, lower=None, upper=None, ...)	Financial property name comes from FinancialProperty; term comes from the Term enum (Q1=1, Annual=100, latest single quarter=10, etc.). The Term.SURPRISE_LATEST series (200~204) returns values for both HK and US in practice, but the data is typically identical to ANNUAL — use with caution
    add_indicator_positional(first_indicator_name, period_type, position, second_indicator=None, ...)	Indicator position relation e.g. MA5 crosses above MA20. Indicator/Period/Position come from Indicator / Period / Position
    add_indicator_pattern(name, period_type, ...)	Indicator pattern (gold cross, dead cross, divergence, etc.) name comes from Pattern
    add_featured_property(name, intervals=None, value_set=None, period=None, range_period=None, first_custom_param=None)	Featured indicator (chip, hotness, analyst rating, capital flow, etc.)
    add_broker_holdings(name, days=None, param=None, intervals=None)	Broker holding factor HK only. Broker factors 6101 / 6102 / 6105 / 6106 / 6107 use a magnification of 1000 and accept percentage values (e.g. 20% → 20); the days parameter has no effect
    add_kline_shape(name, period=None, value_set=None)	K-line shape (double bottom, head & shoulders, etc.) period is required; only daily K (11) and 1-hour K (21) are supported
    add_option(name, intervals=None, param=None, period=None)	Option indicator (underlying IV, HV, etc.)

  • Retrieve builder methods (declare which fields to return; if not declared, only stock_id is returned):

    Method	Description
    add_retrieve_basic(name)	Code / name / industry name comes from BasicProperty: CODE=1101, NAME=1102, INDUSTRY=1103
    add_retrieve_simple(name)	Simple property name comes from SimpleProperty
    add_retrieve_cumulative(name, days=1, period_average=None)	Cumulative property name comes from CumulativeProperty
    add_retrieve_financial(name, term=None, year=None, ...)	Financial property name comes from FinancialProperty
    add_retrieve_indicator(name, period=None, indicator_params=None)	Indicator
    add_retrieve_featured(name, period=None, range_period=None, first_custom_param=None)	Featured property
    add_retrieve_broker(name, days=None, param=None)	Broker
    add_retrieve_option(name, param=None, period=None)	Option property
    add_retrieve_kline_shape(name, period=None)	K-line shape period is required, otherwise no result is returned; only daily K (11) and 1-hour K (21) are supported

  • Sort builder methods:

    Method	Description
    set_sort(direction, property_type, property_params)	Single-field sort direction comes from ScrSortDir: ASC=1, DESC=2, ABS_ASC=3, ABS_DESC=4. property_type is one of 'basic' / 'simple' / 'cumulative' / 'financial' / 'indicator' / 'featured' / 'broker' / 'option' / 'kline_shape'
    add_sort(direction, property_type, property_params)	Multi-field sort Applied in call order; mutually exclusive with set_sort, sortList wins when non-empty

• Returns

  Parameter	Type	Description
  ret	RET_CODE	API result
  data	tuple	When ret == RET_OK, returns (last_page, all_count, items)
  	str	When ret != RET_OK, an error description is returned

  • Returned tuple fields:

    Field	Type	Description
    last_page	bool	Whether this is the last page
    all_count	int	Total number of records matching the conditions
    items	list[dict]	Result list for the current page; each element has the structure {'stock_id': int, 'results': [result, ...]}

  • Single result structure:

    Field	Type	Description
    type	str	Property type 'basic' / 'simple' / 'cumulative' / 'financial' / 'indicator' / 'featured' / 'broker' / 'option' / 'kline_shape'
    property	dict	Corresponding property descriptor (contains name / days / term, etc.)
    value_type	int	Value type 1=string(sval), 2=int64(ival), 3=int64 array(aval), 4=double(dval). When OpenD has no data, only value_type is sent (typically 2) and sval/ival/aval/dval are all absent, e.g. HK Q2/Q3/Q4 financial data
    sval	str	String value (present when value_type=1)
    ival	int	Integer value (present when value_type=2)
    aval	list[int]	Integer array value (present when value_type=3)
    dval	float	Floating-point value (present when value_type=4)
    enum_type_name	str	When ival is an enum code, the corresponding enum type name (e.g. 'KlineShapeType')
    enum_name	str	When ival is an enum code, the decoded enum name returned by OpenD/SDK (e.g. 'DOUBLE_BOTTOMS', 'NONE')
    end_time	int	Financial report end timestamp Only for financial type. Current OpenD versions do not populate this field — typically absent from actual results

• Example

from futu import OpenQuoteContext, RET_OK, StockScreenRequest
from futu.quote.stock_screen_const import (
    ScrMarket, ScrSortDir, SimpleField, SimpleProperty,
    CumulativeProperty, FinancialProperty, Term,
    Indicator, Period, Position, Pattern,
    BasicProperty, KlineShapeProperty, KlineShapeType,
)

quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)

# Example 1: HK large-cap stocks + MACD golden cross
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_simple_property(name=SimpleProperty.PRICE, lower=10.0)                   # Last price >= 10
req.add_simple_property(name=SimpleProperty.MARKET_CAP, lower=10_000_000_000.0)  # Market cap >= 10 billion
req.add_simple_property(name=SimpleProperty.PE_TTM, lower=10.0, upper=50.0)      # PE(TTM) 10~50
req.add_indicator_pattern(name=Pattern.MACD_GOLD_CROSS, period_type=Period.DAY)  # MACD golden cross
# Retrieve fields
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_basic(name=BasicProperty.NAME)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.add_retrieve_simple(name=SimpleProperty.MARKET_CAP)
req.add_retrieve_simple(name=SimpleProperty.PE_TTM)
# Sort
req.set_sort(direction=ScrSortDir.DESC, property_type='simple',
             property_params={'name': int(SimpleProperty.MARKET_CAP)})
req.page_count = 50

ret, data = quote_ctx.get_stock_screen(req)
if ret == RET_OK:
    last_page, all_count, items = data
    print(f"Total {all_count}, returned {len(items)} this page")
    for it in items[:3]:
        print(it['stock_id'], it['results'])
else:
    print('error: ', data)

# Example 2: Financial factor + cumulative change ratio
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_cumulative_property(name=CumulativeProperty.PRICE_CHANGE_PCT,
                            days=5, lower=-0.05, upper=0.05)                     # 5-day change ratio -5%~5% (decimal)
req.add_financial_property(name=FinancialProperty.NET_PROFIT,
                           term=Term.ANNUAL, lower=0.0)                          # Annual net profit > 0
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.page_count = 200
ret, data = quote_ctx.get_stock_screen(req)

# Example 3: K-line shape (double bottom + head-and-shoulders bottom)
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_kline_shape(name=KlineShapeProperty.SHAPE_TYPE, period=Period.DAY,
                    value_set=[KlineShapeType.DOUBLE_BOTTOMS,
                               KlineShapeType.HEAD_SHOULDERS_BOTTOM])
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_kline_shape(name=KlineShapeProperty.SHAPE_TYPE, period=Period.DAY)
ret, data = quote_ctx.get_stock_screen(req)

quote_ctx.close()

• Output

Total 1, returned 1
54047868453564 [{'type': 'basic', 'property': {'name': 1101}, 'value_type': 1, 'sval': '00700'},
                {'type': 'basic', 'property': {'name': 1102}, 'value_type': 1, 'sval': 'Tencent Holdings'},
                {'type': 'simple', 'property': {'name': 2201}, 'value_type': 4, 'dval': 460.0},
                {'type': 'simple', 'property': {'name': 2301}, 'value_type': 4, 'dval': 4194280264040.0},
                {'type': 'simple', 'property': {'name': 2303}, 'value_type': 4, 'dval': 15.75126}]

Qot_StockScreen.proto

• Description

  Stock screening V2

• Parameters

message Boundary
{
    required double value = 1;
    optional bool includes = 2;     // Closed interval, defaults to true
}

message Interval
{
    optional Boundary filterMin = 1;
    optional Boundary filterMax = 2;
}

// ===== PropertyXxx =====
message PropertyBasic         { required int32 name = 1; }
message PropertySimple        { required int32 name = 1; optional int32 unit = 2; }
message PropertyCumulative    {
    required int32 name = 1;
    required int32 days = 2;
    optional int32 periodAverage = 3;
    optional int32 unit = 4;
}
message PropertyFinancial     {
    required int32 name = 1;
    optional int32 term = 2;
    optional int32 year = 3;
    optional int32 duration = 4;
    optional int32 periodAverage = 5;
    optional int32 futureDuration = 6;
    optional int32 unit = 7;
}
message PropertyIndicator     {
    required int32 name = 1;
    optional int32 period = 2;
    repeated int32 indicatorParams = 3;
}
message PropertyFeatured      {
    required int32 name = 1;
    optional int32 period = 2;
    optional int32 rangePeriod = 3;
    optional int32 firstCustomParam = 4;
}
message PropertyBroker        {
    required int32 name = 1;
    optional int32 days = 2;
    optional string param = 3;
}
message PropertyOption        {
    required int32 name = 1;
    optional int32 period = 2;
    optional string param = 3;
}
message PropertyKlineShape    {
    required int32 name = 1;
    optional int32 period = 2;
}

// ===== QueryXxx =====
message SimpleFieldQuery
{
    required int32 simpleField = 1;
    repeated int32 screenValueList = 2;
}

message PlateInfo
{
    repeated string plateIdList = 1;
    optional string parentPlateId = 2;
}

message PlateQuery       { repeated PlateInfo plateList = 1; }

message SimplePropertyQuery
{
    required PropertySimple property = 1;
    optional Boundary filterMin = 2;
    optional Boundary filterMax = 3;
}

message CumulativePropertyQuery
{
    required PropertyCumulative property = 1;
    optional Boundary filterMin = 2;
    optional Boundary filterMax = 3;
    optional int32 continuousPeriod = 4;
}

message FinancialPropertyQuery
{
    required PropertyFinancial property = 1;
    optional Boundary filterMin = 2;
    optional Boundary filterMax = 3;
    optional int32 continuousPeriod = 4;
}

message IndicatorPositionalQuery
{
    required int32 firstIndicatorName = 1;
    required int32 periodType = 2;
    required int32 position = 3;
    optional int32 secondIndicator = 4;
    optional int32 secondValue = 5;
    repeated int32 firstIndicatorParams = 6;
    repeated int32 secondIndicatorParams = 7;
    optional int32 continuousPeriod = 8;
    repeated Interval intervals = 9;
}

message IndicatorPatternQuery
{
    required int32 name = 1;
    required int32 periodType = 2;
    optional int32 continuousPeriod = 3;
    optional bool isMatching = 4;
    repeated int32 subPatterns = 5;
}

message FeaturedPropertyQuery
{
    required PropertyFeatured property = 1;
    repeated Interval intervals = 2;
    repeated int32 valueSet = 3;
}

message BrokerHoldingsQuery
{
    required PropertyBroker property = 1;
    repeated Interval intervals = 2;
}

message KlineShapeQuery
{
    required PropertyKlineShape property = 1;
    repeated int32 valueSet = 2;
}

message OptionQuery
{
    required PropertyOption property = 1;
    repeated Interval intervals = 2;
}

// ===== One filter condition (oneof) =====
message ScreenQuery
{
    optional SimpleFieldQuery simpleFieldQuery = 1;
    optional PlateQuery plateQuery = 2;
    optional SimplePropertyQuery simplePropertyQuery = 3;
    optional CumulativePropertyQuery cumulativePropertyQuery = 4;
    optional FinancialPropertyQuery financialPropertyQuery = 5;
    optional IndicatorPositionalQuery indicatorPositionalQuery = 6;
    optional IndicatorPatternQuery indicatorPatternQuery = 7;
    optional FeaturedPropertyQuery featuredPropertyQuery = 8;
    optional BrokerHoldingsQuery brokerHoldingsQuery = 9;
    optional KlineShapeQuery klineShapeQuery = 10;
    optional OptionQuery optionQuery = 11;
}

// ===== Retrieve fields =====
message RetrieveQuery
{
    optional PropertyBasic basicProperty = 1;
    optional PropertySimple simpleProperty = 2;
    optional PropertyCumulative cumulativeProperty = 3;
    optional PropertyFinancial financialProperty = 4;
    optional PropertyIndicator indicatorProperty = 5;
    optional PropertyFeatured featuredProperty = 6;
    optional PropertyBroker brokerProperty = 7;
    optional PropertyOption optionProperty = 8;
    optional PropertyKlineShape klineShapeProperty = 9;
}

// ===== Sort definition =====
message Sort
{
    required int32 direction = 1;   // 1=ASC, 2=DESC, 3=ABS_ASC, 4=ABS_DESC
    optional PropertyBasic basicProperty = 2;
    optional PropertySimple simpleProperty = 3;
    optional PropertyCumulative cumulativeProperty = 4;
    optional PropertyFinancial financialProperty = 5;
    optional PropertyIndicator indicatorProperty = 6;
    optional PropertyFeatured featuredProperty = 7;
    optional PropertyBroker brokerProperty = 8;
    optional PropertyOption optionProperty = 9;
    optional PropertyKlineShape klineShapeProperty = 10;
}

message C2S
{
    repeated ScreenQuery filterList = 1;
    repeated RetrieveQuery retrieveList = 2;
    repeated int64 watchlistStockIds = 3;
    optional Sort sort = 4;             // Single-field sort
    optional int32 pageFrom = 5;
    optional int32 pageCount = 6;
    repeated Sort sortList = 7;         // Multi-field sort; takes precedence over sort when non-empty
}

message Request
{
    required C2S c2s = 1;
}

• Returns

// Single result value: when valueType=1 use sval, =2 use ival, =3 use aval, =4 use dval
message ResultPropertyBasic
{
    required PropertyBasic property = 1;
    optional int32 valueType = 2;
    optional string sval = 3;
    optional int64 ival = 4;
    repeated int64 aval = 5;
    optional double dval = 6;
    optional string enumTypeName = 7;
    optional string enumName = 8;
}
// Other ResultPropertySimple / Cumulative / Financial / Indicator / Featured / Broker / Option / KlineShape
// share the same structure as ResultPropertyBasic, only the property type differs. Financial additionally contains endTime.

message RspItemResult
{
    optional ResultPropertyBasic basicPropertyResult = 1;
    optional ResultPropertySimple simplePropertyResult = 2;
    optional ResultPropertyCumulative cumulativePropertyResult = 3;
    optional ResultPropertyFinancial financialPropertyResult = 4;
    optional ResultPropertyIndicator indicatorPropertyResult = 5;
    optional ResultPropertyFeatured featuredPropertyResult = 6;
    optional ResultPropertyBroker brokerPropertyResult = 7;
    optional ResultPropertyOption optionPropertyResult = 8;
    optional ResultPropertyKlineShape klineShapePropertyResult = 9;
}

message RspItem
{
    required int64 stockId = 1;
    repeated RspItemResult results = 2;
}

message S2C
{
    required bool lastPage = 1;
    required int32 allCount = 2;
    repeated RspItem dataList = 3;
}

message Response
{
    required int32 retType = 1 [default = -400];
    optional string retMsg = 2;
    optional int32 errCode = 3;
    optional S2C s2c = 4;
}

• API result; structure see RetType

• Proto ID

  3252

uint StockScreen(QotStockScreen.Request req); virtual void OnReply_StockScreen(FTAPI_Conn client, uint nSerialNo, QotStockScreen.Response rsp);

• Description

  Stock screening V2

• Parameters

  See the request structure of Qot_StockScreen.proto in the Proto tab.

• Returns

  See the response structure of Qot_StockScreen.proto in the Proto tab.

• Proto ID

  3252

int stockScreen(QotStockScreen.Request req) onReply_StockScreen(FTAPI_Conn client, int nSerialNo, QotStockScreen.Response rsp)

• Description

  Stock screening V2

• Parameters

  See the request structure of Qot_StockScreen.proto in the Proto tab.

• Returns

  See the response structure of Qot_StockScreen.proto in the Proto tab.

• Proto ID

  3252

bool StockScreen(uint32_t & nSerialNo, const Qot_StockScreen::Request & stReq); virtual void OnReply_StockScreen(FTAPI_Conn* pConn, uint32_t nSerialNo, const Qot_StockScreen::Response & stRsp)

• Description

  Stock screening V2

• Parameters

  See the request structure of Qot_StockScreen.proto in the Proto tab.

• Returns

  See the response structure of Qot_StockScreen.proto in the Proto tab.

• Proto ID

  3252

stockScreen(qotStockScreen)

• Description

  Stock screening V2

• Parameters

  See the request structure of Qot_StockScreen.proto in the Proto tab.

• Returns

  See the response structure of Qot_StockScreen.proto in the Proto tab.

• Proto ID

  3252

• Python
• Proto
• C#
• Java
• C++
• JavaScript

get_stock_screen(request)

• Description

  Stock screening V2. Parameters and return fields are identical to the nn tab.

• Example

from moomoo import OpenQuoteContext, RET_OK, StockScreenRequest
from moomoo.quote.stock_screen_const import (
    ScrMarket, ScrSortDir, SimpleField, SimpleProperty,
    Indicator, Period, Pattern, BasicProperty,
)

quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)

req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_simple_property(name=SimpleProperty.PRICE, lower=10.0)
req.add_simple_property(name=SimpleProperty.MARKET_CAP, lower=10_000_000_000.0)
req.add_indicator_pattern(name=Pattern.MACD_GOLD_CROSS, period_type=Period.DAY)
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_basic(name=BasicProperty.NAME)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.add_retrieve_simple(name=SimpleProperty.MARKET_CAP)
req.set_sort(direction=ScrSortDir.DESC, property_type='simple',
             property_params={'name': int(SimpleProperty.MARKET_CAP)})
req.page_count = 50

ret, data = quote_ctx.get_stock_screen(req)
if ret == RET_OK:
    last_page, all_count, items = data
    print(f"Total {all_count}, returned {len(items)} this page")
else:
    print('error: ', data)

quote_ctx.close()

Qot_StockScreen.proto

See the Proto content in the nn tab. Proto ID 3252.

uint StockScreen(QotStockScreen.Request req); virtual void OnReply_StockScreen(FTAPI_Conn client, uint nSerialNo, QotStockScreen.Response rsp);

See the Proto content in the nn tab. Proto ID 3252.

int stockScreen(QotStockScreen.Request req) onReply_StockScreen(FTAPI_Conn client, int nSerialNo, QotStockScreen.Response rsp)

See the Proto content in the nn tab. Proto ID 3252.

bool StockScreen(uint32_t & nSerialNo, const Qot_StockScreen::Request & stReq); virtual void OnReply_StockScreen(FTAPI_Conn* pConn, uint32_t nSerialNo, const Qot_StockScreen::Response & stRsp)

See the Proto content in the nn tab. Proto ID 3252.

stockScreen(qotStockScreen)

See the Proto content in the nn tab. Proto ID 3252.