# 篩選期權

Python
Proto
C#
Java
C++
JavaScript

get_option_screen(request)

介紹

期權選股。混合使用標的屬性（underlying）與期權屬性（option）進行篩選。同一組內不能同時篩選標的屬性（underlying）與期權屬性（option），SDK 自動按需開新篩選組：默認每條篩選條件 AND 拼接（開新組），同 indicator_type 顯式 or_with_previous=True 時與上一條件 OR（同組）。

參數

參數	類型	說明
request	OptionScreenRequest	期權選股請求對象，構造時必傳 market_categories

OptionScreenRequest 字段：

字段	類型	說明
market_categories	list[int]	期權市場品類列表元素取自 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 後續支持，目前結果為空
page_from	int	分頁起始位置不傳默認為 0
page_count	int	單頁最大返回數不傳默認為 200

篩選條件 builder 方法（默認每次調用自動開新篩選組與之前條件 AND；同 indicator_type 顯式 or_with_previous=True 時與上一條件 OR 同組。同一組內不能同時篩選標的屬性（underlying）與期權屬性（option））：

方法	說明
add_underlying_filter(indicator_type, values=None, lower=None, upper=None, plate_list=None, parent_plate_id=None, or_with_previous=False)	標的屬性篩選 indicator_type 取自 OptUnderlyingIndicator。STOCK_LIST 接受標的 stock_id（int，取自快照/訂閱返回），不能直接傳證券代碼。IV / HV / IV_RANK / IV_PERCENTILE 等百分數指標傳小數（30% 傳 0.3）。PLATE(103) 類型傳入會有報錯，暫不要使用
add_option_filter(indicator_type, values=None, lower=None, upper=None, or_with_previous=False)	期權屬性篩選 indicator_type 取自 OptIndicator。DELTA / GAMMA / VEGA / THETA / RHO / 各類概率（如 ITM_PROBABILITY）傳 0~1 小數。PREMIUM(2021) 僅支持 sort / retrieve，作為 filter 會有報錯；BUY_BREAK_EVEN_POINT(3023) 已廢棄，新代碼請用 BUY_TO_BEP(3011)
new_filter_group()	手動開始新的篩選組組間 AND，組內 OR
add_sort(indicator_type, desc=False)	排序 desc=True 為降序，默認升序
add_option_retrieve(indicator_type)	聲明額外要返回的期權字段不調用則返回默認基礎字段
add_underlying_retrieve(indicator_type)	聲明要返回的標的字段調用後返回結果中的 underlying dict 字段才會被填充

參數	類型	說明
ret	RET_CODE	接口調用結果
data	tuple	當 ret == RET_OK，返回 (last_page, all_count, DataFrame)
data	str	當 ret != RET_OK，返回錯誤描述

返回 DataFrame 字段：

字段	類型	說明
code	str	期權代碼
option_name	str	期權名稱
strike_price	float	行權價
strike_date	str	行權日
option_type	int	認購/認沽 1=CALL，2=PUT
exercise_type	int	行權方式 1=美式，2=歐式
expiration_type	int	到期類型 1=週，2=月，3=季
in_the_money	bool	是否價內
left_day	int	剩餘天數
price	float	期權價格
mid_price	float	中間價
bid_price	float	買價
ask_price	float	賣價
bid_ask_spread	float	買賣價差
bid_volume	int	買量
ask_volume	int	賣量
bid_ask_volume_ratio	float	買賣量比
change_ratio	float	漲跌幅
volume	int	成交量
turnover	float	成交額
open_interest	int	未平倉合約數（持倉量）
open_interest_market_cap	float	持倉市值
vol_oi_ratio	float	成交量/持倉量
premium	float	權利金
implied_volatility	float	隱含波動率
history_volatility	float	歷史波動率
iv_hv_ratio	float	IV/HV
delta	float	希臘字母 Delta
gamma	float	希臘字母 Gamma
vega	float	希臘字母 Vega
theta	float	希臘字母 Theta
rho	float	希臘字母 Rho
leverage_ratio	float	槓桿比率
effective_gearing	float	有效槓桿
itm_probability	float	價內概率
buy_to_bep	float	買入到盈虧平衡點比率
sell_to_bep	float	賣出到盈虧平衡點比率
buy_profit_probability	float	買入盈利概率
sell_profit_probability	float	賣出盈利概率
intrinsic_value_per	float	內在價值百分比
time_value_per	float	時間價值百分比
itm_degree	float	價內程度
otm_degree	float	價外程度
otm_probability	float	價外概率
sell_annualized_return	float	賣出年化收益率
interval_return	float	賣出區間收益率
underlying	dict	標的信息（僅當調用 add_underlying_retrieve 後返回） dict 含 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)

# 示例 1：美股標的 IV>30% + 平值附近 CALL
req = OptionScreenRequest(market_categories=[OptMarketCategory.US_STOCK])
req.add_underlying_filter(OptUnderlyingIndicator.IV, lower=0.3)              # 標的 IV ≥ 30%（小數）
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 天
req.add_sort(OptIndicator.VOLUME, desc=True)                                 # 成交量降序
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)

# 示例 2：港股按指定標的篩選 + 同時取標的信息
# 注意：STOCK_LIST 接收的是內部 stock_id，需通過 get_market_snapshot/get_static_info 等接口
# 提前取得；下面 54047868453564 即為港股騰訊（00700）的 stock_id
req = OptionScreenRequest(market_categories=[OptMarketCategory.HK_STOCK])
req.add_underlying_filter(OptUnderlyingIndicator.STOCK_LIST,
                          values=[54047868453564])                            # 標的=騰訊
req.add_option_filter(OptIndicator.OPTION_TYPE, values=[1])                   # CALL
req.add_option_filter(OptIndicator.OPTION_TYPE, values=[2],
                      or_with_previous=True)                                  # 與上一條 OR：CALL + PUT
req.add_underlying_retrieve(OptUnderlyingIndicator.IV)
req.add_underlying_retrieve(OptUnderlyingIndicator.MARKET_CAP)
req.add_sort(OptIndicator.OPEN_INTEREST, desc=True)                           # 持倉量降序
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

介紹

期權選股
參數

message Boundary
{
    required double value = 1;
    optional bool includes = 2;     // 是否閉區間，默認 true
}

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

message OptionIndicatorValue
{
    repeated int32 valueList = 1;       // 確切值列表 (用於 OPTION_TYPE 等)
    optional ValueInterval valueInterval = 2;   // 區間篩選
}

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

// 標的屬性篩選條件
message UnderlyingFilter
{
    required int32 indicatorType = 1;           // OptUnderlyingIndicator
    optional OptionIndicatorValue indicatorValue = 2;
    repeated PlateInfo plateList = 3;           // 僅 PLATE(103) 時使用
}

// 期權屬性篩選條件
message OptionFilter
{
    required int32 indicatorType = 1;           // OptIndicator
    optional OptionIndicatorValue indicatorValue = 2;
}

// 一組篩選條件：組內 OR，組間 AND；同一組內不能同時篩選標的屬性（underlying）與期權屬性（option）
message FilterGroup
{
    repeated UnderlyingFilter underlyingList = 1;
    repeated OptionFilter optionList = 2;
}

message Sort
{
    required int32 indicatorType = 1;
    required int32 direction = 2;               // 0=升序, 1=降序
}

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;      // 聲明要返回的期權字段，不傳則返回默認基礎字段
    repeated int32 underlyingRetrieveList = 7;  // 聲明要返回的標的字段
}

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

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

接口調用結果，結構參見 RetType

協議 ID

3253

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

介紹

期權選股
參數

參考 Proto 標籤頁中 Qot_OptionScreen.proto 的請求結構。
返回

參考 Proto 標籤頁中 Qot_OptionScreen.proto 的響應結構。
協議 ID

3253

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

介紹

期權選股
參數

參考 Proto 標籤頁中 Qot_OptionScreen.proto 的請求結構。
返回

參考 Proto 標籤頁中 Qot_OptionScreen.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)

介紹

期權選股
參數

參考 Proto 標籤頁中 Qot_OptionScreen.proto 的請求結構。
返回

參考 Proto 標籤頁中 Qot_OptionScreen.proto 的響應結構。
協議 ID

3253

optionScreen(qotOptionScreen)

介紹

期權選股
參數

參考 Proto 標籤頁中 Qot_OptionScreen.proto 的請求結構。
返回

參考 Proto 標籤頁中 Qot_OptionScreen.proto 的響應結構。
協議 ID

3253

Python
Proto
C#
Java
C++
JavaScript

get_option_screen(request)

介紹

期權選股，參數與返回字段同 nn 標籤頁。
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%（小數）
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

參考 nn 標籤頁 Proto 內容，協議 ID 3253。

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

參考 nn 標籤頁 Proto 內容，協議 ID 3253。

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

參考 nn 標籤頁 Proto 內容，協議 ID 3253。

optionScreen(qotOptionScreen)

參考 nn 標籤頁 Proto 內容，協議 ID 3253。

← 獲取期權行權概率篩選窩輪 →