# Option Screening

Python
Proto
C#
Java
C++
JavaScript

get_option_screen(request)

Description

Option screening. Mixes underlying-property and option-property filters. Underlying-property and option-property filters cannot be applied together within the same group, so the SDK opens new filter groups as needed: by default each filter condition is AND-joined with the previous (a new group is opened); when or_with_previous=True is set explicitly and the indicator_type matches the previous condition, the new condition is OR-joined with it (same group).

Parameters

Parameter	Type	Description
request	OptionScreenRequest	Option screening request object; market_categories must be passed at construction

OptionScreenRequest fields:

Field	Type	Description
market_categories	list[int]	Option market category list Elements come from OptMarketCategory: US_STOCK=0, US_INDEX=1, US_FUTURE=2, HK_STOCK=3, HK_INDEX=4, JP_STOCK=5, JP_INDEX=6. US_FUTURE / JP_STOCK / JP_INDEX will be supported later; currently the result is empty
page_from	int	Pagination start position Defaults to 0
page_count	int	Maximum results per page Defaults to 200

Filter builder methods (by default each call automatically opens a new filter group AND-joined with previous conditions; with or_with_previous=True and a matching indicator_type, the new condition is OR-joined with the previous one in the same group. Underlying-property and option-property filters cannot be applied together within the same group):

Method	Description
add_underlying_filter(indicator_type, values=None, lower=None, upper=None, plate_list=None, parent_plate_id=None, or_with_previous=False)	Underlying property filter indicator_type comes from OptUnderlyingIndicator. STOCK_LIST takes underlying stock_id (int, fetched from snapshot/subscribe APIs); raw security codes are not accepted. IV / HV / IV_RANK / IV_PERCENTILE etc. take decimal values (30% as 0.3). PLATE(103) will return an error; do not use it for now
add_option_filter(indicator_type, values=None, lower=None, upper=None, or_with_previous=False)	Option property filter indicator_type comes from OptIndicator. DELTA / GAMMA / VEGA / THETA / RHO and probability indicators (e.g. ITM_PROBABILITY) take 0~1 decimals. PREMIUM(2021) only supports sort / retrieve, using it as a filter returns an error; BUY_BREAK_EVEN_POINT(3023) is deprecated, new code should use BUY_TO_BEP(3011)
new_filter_group()	Manually start a new filter group Groups are AND-joined; conditions inside a group are OR-joined
add_sort(indicator_type, desc=False)	Sort desc=True for descending; ascending by default
add_option_retrieve(indicator_type)	Declare additional option fields to return If not called, default basic fields are returned
add_underlying_retrieve(indicator_type)	Declare underlying fields to return Only after calling this will the underlying dict in the response be populated

Returns

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

Returned DataFrame fields:

Field	Type	Description
code	str	Option code
option_name	str	Option name
strike_price	float	Strike price
strike_date	str	Strike date
option_type	int	Call / Put 1=CALL, 2=PUT
exercise_type	int	Exercise type 1=American, 2=European
expiration_type	int	Expiration type 1=Weekly, 2=Monthly, 3=Quarterly
in_the_money	bool	Whether in the money
left_day	int	Days remaining
price	float	Option price
mid_price	float	Mid price
bid_price	float	Bid price
ask_price	float	Ask price
bid_ask_spread	float	Bid-ask spread
bid_volume	int	Bid volume
ask_volume	int	Ask volume
bid_ask_volume_ratio	float	Bid-ask volume ratio
change_ratio	float	Change ratio
volume	int	Volume
turnover	float	Turnover
open_interest	int	Open interest
open_interest_market_cap	float	Open interest market cap
vol_oi_ratio	float	Volume / open interest ratio
premium	float	Premium
implied_volatility	float	Implied volatility
history_volatility	float	Historical volatility
iv_hv_ratio	float	IV/HV
delta	float	Greeks Delta
gamma	float	Greeks Gamma
vega	float	Greeks Vega
theta	float	Greeks Theta
rho	float	Greeks Rho
leverage_ratio	float	Leverage ratio
effective_gearing	float	Effective leverage
itm_probability	float	In-the-money probability
buy_to_bep	float	Buy-to-break-even ratio
sell_to_bep	float	Sell-to-break-even ratio
buy_profit_probability	float	Buy profit probability
sell_profit_probability	float	Sell profit probability
intrinsic_value_per	float	Intrinsic value percentage
time_value_per	float	Time value percentage
itm_degree	float	In-the-money degree
otm_degree	float	Out-of-the-money degree
otm_probability	float	Out-of-the-money probability
sell_annualized_return	float	Sell annualized return
interval_return	float	Sell interval return
underlying	dict	Underlying info (returned only when add_underlying_retrieve is called) dict contains stock_id / iv / hv / iv_rank / iv_percentile / market_cap / price / change_ratio

Example

from futu import (
    OpenQuoteContext, RET_OK, OptionScreenRequest,
    OptMarketCategory, OptIndicator, OptUnderlyingIndicator,
)

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

# Example 1: US underlyings with IV>30% + near-the-money CALL
req = OptionScreenRequest(market_categories=[OptMarketCategory.US_STOCK])
req.add_underlying_filter(OptUnderlyingIndicator.IV, lower=0.3)              # Underlying IV >= 30% (decimal)
req.add_option_filter(OptIndicator.OPTION_TYPE, values=[1])                  # CALL
req.add_option_filter(OptIndicator.DELTA, lower=0.3, upper=0.7)              # Delta 0.3~0.7
req.add_option_filter(OptIndicator.LEFT_DAY, lower=7, upper=60)              # 7~60 days remaining
req.add_sort(OptIndicator.VOLUME, desc=True)                                 # Volume descending
req.add_option_retrieve(OptIndicator.DELTA)
req.add_option_retrieve(OptIndicator.VOLUME)
req.page_count = 30

ret, data = quote_ctx.get_option_screen(req)
if ret == RET_OK:
    last_page, all_count, df = data
    print(df[['code', 'option_name', 'delta', 'volume']].head(10))
else:
    print('error: ', data)

# Example 2: HK options for a specific underlying + return underlying info
# Note: STOCK_LIST takes the internal stock_id; obtain it via get_market_snapshot /
# get_static_info etc. The value 54047868453564 below is the stock_id of HK Tencent (00700).
req = OptionScreenRequest(market_categories=[OptMarketCategory.HK_STOCK])
req.add_underlying_filter(OptUnderlyingIndicator.STOCK_LIST,
                          values=[54047868453564])                            # Underlying = Tencent
req.add_option_filter(OptIndicator.OPTION_TYPE, values=[1])                   # CALL
req.add_option_filter(OptIndicator.OPTION_TYPE, values=[2],
                      or_with_previous=True)                                  # OR with previous: CALL + PUT
req.add_underlying_retrieve(OptUnderlyingIndicator.IV)
req.add_underlying_retrieve(OptUnderlyingIndicator.MARKET_CAP)
req.add_sort(OptIndicator.OPEN_INTEREST, desc=True)                           # Open interest descending
req.page_count = 50

ret, data = quote_ctx.get_option_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

Output

                 code        option_name    delta  volume
0  US.SLV260529C70000  SLV 260529 70.00C  0.52937   45838
1   US.TZA260612C5500   TZA 260612 5.50C  0.37815   40777
2  US.HIVE260717C5000  HIVE 260717 5.00C  0.36626   31104
3  US.NKE260618C45000  NKE 260618 45.00C  0.32579   24046
4    US.SG260618C9500    SG 260618 9.50C  0.39444   19020

1
2
3
4
5
6

# Qot_OptionScreen.proto

Description

Option screening
Parameters

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

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

message OptionIndicatorValue
{
    repeated int32 valueList = 1;       // Exact value list (used for OPTION_TYPE etc.)
    optional ValueInterval valueInterval = 2;   // Interval filter
}

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

// Underlying property filter condition
message UnderlyingFilter
{
    required int32 indicatorType = 1;           // OptUnderlyingIndicator
    optional OptionIndicatorValue indicatorValue = 2;
    repeated PlateInfo plateList = 3;           // Used only when indicatorType is PLATE(103)
}

// Option property filter condition
message OptionFilter
{
    required int32 indicatorType = 1;           // OptIndicator
    optional OptionIndicatorValue indicatorValue = 2;
}

// One filter group: OR within the group, AND between groups; underlying and option filters cannot be applied together within the same group
message FilterGroup
{
    repeated UnderlyingFilter underlyingList = 1;
    repeated OptionFilter optionList = 2;
}

message Sort
{
    required int32 indicatorType = 1;
    required int32 direction = 2;               // 0=ascending, 1=descending
}

message C2S
{
    repeated int32 marketCategoryList = 1;      // OptMarketCategory: US_STOCK=0, US_INDEX=1, US_FUTURE=2, HK_STOCK=3, HK_INDEX=4, JP_STOCK=5, JP_INDEX=6
    repeated FilterGroup filterList = 2;
    repeated Sort sortList = 3;
    optional int32 pageFrom = 4;
    optional int32 pageCount = 5;
    repeated int32 optionRetrieveList = 6;      // Declare option fields to return; if not passed, default basic fields are returned
    repeated int32 underlyingRetrieveList = 7;  // Declare underlying fields to return
}

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

Returns

message Security
{
    required int32 market = 1;
    required string code = 2;
}

message UnderlyingInfo
{
    optional int64 stockID = 1;
    optional double iv = 2;
    optional double hv = 3;
    optional double ivRank = 4;
    optional double ivPercentile = 5;
    optional double marketCap = 6;
    optional double price = 7;
    optional double changeRatio = 8;
}

message OptionScreenItem
{
    optional Security security = 1;
    optional string optionName = 2;
    optional double strikePrice = 3;
    optional string strikeDate = 4;
    optional int32 optionType = 5;
    optional int32 exerciseType = 6;
    optional int32 expirationType = 7;
    optional bool inTheMoney = 8;
    optional int32 leftDay = 9;
    optional double price = 20;
    optional double midPrice = 21;
    optional double bidPrice = 22;
    optional double askPrice = 23;
    optional double bidAskSpread = 24;
    optional int64 bidVolume = 25;
    optional int64 askVolume = 26;
    optional double bidAskVolumeRatio = 27;
    optional double changeRatio = 28;
    optional int64 volume = 29;
    optional double turnover = 30;
    optional int64 openInterest = 31;
    optional double openInterestMarketCap = 32;
    optional double volOIRatio = 33;
    optional double premium = 34;
    optional double impliedVolatility = 40;
    optional double historyVolatility = 41;
    optional double ivHvRatio = 42;
    optional double delta = 43;
    optional double gamma = 44;
    optional double vega = 45;
    optional double theta = 46;
    optional double rho = 47;
    optional double leverageRatio = 48;
    optional double effectiveGearing = 49;
    optional UnderlyingInfo underlyingInfo = 50;
    optional double itmProbability = 51;
    optional double buyToBep = 52;
    optional double sellToBep = 53;
    optional double buyProfitProbability = 54;
    optional double sellProfitProbability = 55;
    optional double intrinsicValuePer = 56;
    optional double timeValuePer = 57;
    optional double itmDegree = 58;
    optional double otmDegree = 59;
    optional double otmProbability = 60;
    optional double sellAnnualizedReturn = 61;
    optional double intervalReturn = 62;
}

message S2C
{
    required bool lastPage = 1;
    required int32 allCount = 2;
    repeated OptionScreenItem 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
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

API result; structure see RetType

Proto ID

3253

uint OptionScreen(QotOptionScreen.Request req); virtual void OnReply_OptionScreen(FTAPI_Conn client, uint nSerialNo, QotOptionScreen.Response rsp);

Description

Option screening
Parameters

See the request structure of Qot_OptionScreen.proto in the Proto tab.
Returns

See the response structure of Qot_OptionScreen.proto in the Proto tab.
Proto ID

3253

int optionScreen(QotOptionScreen.Request req) onReply_OptionScreen(FTAPI_Conn client, int nSerialNo, QotOptionScreen.Response rsp)

Description

Option screening
Parameters

See the request structure of Qot_OptionScreen.proto in the Proto tab.
Returns

See the response structure of Qot_OptionScreen.proto in the Proto tab.
Proto ID

3253

bool OptionScreen(uint32_t & nSerialNo, const Qot_OptionScreen::Request & stReq); virtual void OnReply_OptionScreen(FTAPI_Conn* pConn, uint32_t nSerialNo, const Qot_OptionScreen::Response & stRsp)

Description

Option screening
Parameters

See the request structure of Qot_OptionScreen.proto in the Proto tab.
Returns

See the response structure of Qot_OptionScreen.proto in the Proto tab.
Proto ID

3253

optionScreen(qotOptionScreen)

Description

Option screening
Parameters

See the request structure of Qot_OptionScreen.proto in the Proto tab.
Returns

See the response structure of Qot_OptionScreen.proto in the Proto tab.
Proto ID

3253

Python
Proto
C#
Java
C++
JavaScript

get_option_screen(request)

Description

Option screening. Parameters and return fields are identical to the nn tab.
Example

from moomoo import (
    OpenQuoteContext, RET_OK, OptionScreenRequest,
    OptMarketCategory, OptIndicator, OptUnderlyingIndicator,
)

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

req = OptionScreenRequest(market_categories=[OptMarketCategory.US_STOCK])
req.add_underlying_filter(OptUnderlyingIndicator.IV, lower=0.3)  # 30% (decimal)
req.add_option_filter(OptIndicator.OPTION_TYPE, values=[1])
req.add_option_filter(OptIndicator.DELTA, lower=0.3, upper=0.7)
req.add_sort(OptIndicator.VOLUME, desc=True)
req.page_count = 30

ret, data = quote_ctx.get_option_screen(req)
if ret == RET_OK:
    last_page, all_count, df = data
    print(df[['code', 'option_name', 'delta', 'volume']].head(10))
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

# Qot_OptionScreen.proto

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

uint OptionScreen(QotOptionScreen.Request req); virtual void OnReply_OptionScreen(FTAPI_Conn client, uint nSerialNo, QotOptionScreen.Response rsp);

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

int optionScreen(QotOptionScreen.Request req) onReply_OptionScreen(FTAPI_Conn client, int nSerialNo, QotOptionScreen.Response rsp)

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

optionScreen(qotOptionScreen)

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

← Get Option Exercise Probability Get Filtered Warrant →