# Option Screening
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=Trueis 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 page_from int Pagination start position page_count int Maximum results per page Filter builder methods (by default each call automatically opens a new filter group AND-joined with previous conditions; with
or_with_previous=Trueand 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 add_option_filter(indicator_type, values=None, lower=None, upper=None, or_with_previous=False) Option property filter new_filter_group() Manually start a new filter group add_sort(indicator_type, desc=False) Sort add_option_retrieve(indicator_type) Declare additional option fields to return add_underlying_retrieve(indicator_type) Declare underlying fields to return
Returns
Parameter Type Description ret RET_CODE API result data tuple When ret == RET_OK, returns (last_page, all_count, DataFrame) 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 exercise_type int Exercise type expiration_type int Expiration type 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)
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
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
2
3
4
5
6