# 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

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)
data	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()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

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

1
2
3
4
5
6

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

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()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29