# 財報期權篩選
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_option_earnings_screener(market, sort_type=None, is_asc=None, count=None, page=None, filter_list=None)
介紹
獲取即將發佈財報的期權標的列表，返回標的波動率數據、歷史財報 IV Crush、股價變動及市場預期等信息，幫助用戶在財報季進行期權交易決策。
參數
參數 類型 說明 market OptionMarket 期權市場類型 US_SECURITY=美股股票期權、HK_SECURITY=港股股票期權sort_type EarningsSortType 排序類型 EARNINGS_DATE=財報日期（默認）、VOLUME=期權成交量、IV=隱含波動率、MARKET_CAP=市值、CHANGE_RATIO=漲跌幅、PRICE=最新價、IV_RANK=IV等級、IV_PERCENTILE=IV百分位、HV=歷史波動率、OPEN_INTEREST=持倉量、LAST_REPORT_IV_CRUSH=上次IV Crush、HISTORY_REPORT_IV_CRUSH=歷史IV Crush、LAST_REPORT_CHG_RATIO=上次財報日漲跌幅、HISTORY_REPORT_CHG_RATIO=歷史財報日漲跌幅、ESTIMATE_EPS_YOY=預測EPS同比、ESTIMATE_REVENUE_YOY=預測營收同比、EXPECTED_MOVE_RATIO=預測波動is_asc bool 是否升序 默認 Truecount int 每頁數量 範圍 [1,500]，默認 50page str 分頁遊標 首次傳空或不傳，翻頁傳 next_pagefilter_list list[EarningsFilter] 篩選條件列表 多條件為 AND 關係返回
參數 類型 說明 ret RET_CODE 接口調用結果 data dict 當 ret == RET_OK，返回字典，包含 item_list（DataFrame）、next_page（str）、update_timestamp（float）、all_count（int） str 當 ret != RET_OK，返回錯誤描述 返回 DataFrame 字段：
字段 類型 說明 owner str 標的股票代碼 name str 標的名稱 price float 標的當前價格 change_ratio float 漲跌幅（小數） market_cap float 市值 iv float 隱含波動率（百分比） iv_rank float IV 等級（百分比） iv_percentile float IV 百分位（百分比） hv float 歷史波動率（百分比） volume int 期權成交量 open_interest int 期權持倉量 earnings_timestamp float 財報日期時間戳（Unix 秒） earnings_time str 財報日期字符串（yyyy-MM-dd） earnings_pub_type str 財報發佈類型（BEFORE=盤前/AFTER=盤後） earnings_quarter str 財報季度（如 '2025Q1'） last_report_iv_crush float 上次財報 IV Crush（百分比） history_report_iv_crush float 歷史平均財報 IV Crush（百分比） last_report_chg_ratio float 上次財報後股價變動（小數） history_report_chg_ratio float 歷史平均財報後股價變動（小數） estimate_eps_yoy float 預估 EPS 同比增長（百分比） estimate_revenue_yoy float 預估營收同比增長（百分比） expected_move_ratio float 期權隱含預期變動幅度（百分比）
Example
from futu import *
quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
ret, data = quote_ctx.get_option_earnings_screener(
market=OptionMarket.US_SECURITY,
count=5
)
if ret == RET_OK:
print(data['item_list'])
print('all_count:', data['all_count'])
else:
print('error:', data)
quote_ctx.close()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
- Output
owner name price change_ratio market_cap iv iv_rank iv_percentile hv volume open_interest earnings_timestamp earnings_time earnings_pub_type earnings_quarter last_report_iv_crush history_report_iv_crush last_report_chg_ratio history_report_chg_ratio estimate_eps_yoy estimate_revenue_yoy expected_move_ratio
0 US.CGC Canopy Growth 1.00 -0.990 4.220190e+08 204.207 36.550 88.492 39.545 8131 328382 1.781496e+09 2026-06-15 BEFORE 2026Q4 -21.308 11.782 1.851 12.761 94.055 14.340 12.500
1 US.PLAY Dave & Buster's Entertainment 12.93 -1.896 4.491805e+08 114.030 99.492 99.603 62.390 3052 44247 1.781496e+09 2026-06-15 AFTER 2027Q1 22.640 26.059 16.066 15.892 -3.758 1.881 15.409
2 US.DOMO Domo Inc 3.02 2.027 1.363547e+08 165.563 72.093 96.825 90.389 1970 29748 1.781496e+09 2026-06-15 AFTER 2027Q1 23.532 30.013 13.470 19.203 9.622 -0.451 30.629
3 US.CMTL Comverse 4.83 5.228 1.436158e+08 388.934 81.297 98.412 106.150 218 13434 1.781496e+09 2026-06-15 BEFORE 2026Q3 154.978 51.309 -24.536 16.278 -10.204 -13.078 23.809
4 US.RFIL RF Industries 18.75 0.969 2.027675e+08 100.939 11.123 54.365 83.526 215 2044 1.781496e+09 2026-06-15 AFTER 2026Q2 -14.722 6.537 12.318 12.013 200.000 3.997 15.466
all_count: 292
1
2
3
4
5
6
7
2
3
4
5
6
7
# Qot_GetOptionEarningsScreener.proto
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
uint GetOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req); virtual void OnReply_GetOptionEarningsScreener(FTAPI_Conn client, uint nSerialNo, Qot_GetOptionEarningsScreener.Response rsp);
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
int getOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req) onReply_GetOptionEarningsScreener(FTAPI_Conn client, int nSerialNo, Qot_GetOptionEarningsScreener.Response rsp)
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
Futu::u32_t GetOptionEarningsScreener(const Qot_GetOptionEarningsScreener::Request &stReq);
virtual void OnReply_GetOptionEarningsScreener(Futu::u32_t nSerialNo, const Qot_GetOptionEarningsScreener::Response &stRsp) = 0;
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
Example
class Program : public FTSPI_Qot, public FTSPI_Conn
{
public:
Program() {
m_pQotApi = FTAPI::CreateQotApi();
m_pQotApi->RegisterQotSpi(this);
m_pQotApi->RegisterConnSpi(this);
}
~Program() {
if (m_pQotApi != nullptr) {
m_pQotApi->UnregisterQotSpi();
m_pQotApi->UnregisterConnSpi();
FTAPI::ReleaseQotApi(m_pQotApi);
m_pQotApi = nullptr;
}
}
void Start() {
m_pQotApi->InitConnect("127.0.0.1", 11111, false);
}
virtual void OnInitConnect(FTAPI_Conn* pConn, Futu::i64_t nErrCode, const char* strDesc) {
Qot_GetOptionEarningsScreener::Request req;
Qot_GetOptionEarningsScreener::C2S *c2s = req.mutable_c2s();
// TODO: 按 proto 填充 c2s 字段
m_GetOptionEarningsScreenerSerialNo = m_pQotApi->GetOptionEarningsScreener(req);
}
virtual void OnReply_GetOptionEarningsScreener(Futu::u32_t nSerialNo, const Qot_GetOptionEarningsScreener::Response &stRsp) {
if (nSerialNo != m_GetOptionEarningsScreenerSerialNo) return;
string resp_str;
ProtoBufToBodyData(stRsp, resp_str);
cout << UTF8ToLocal(resp_str) << endl;
}
protected:
FTAPI_Qot *m_pQotApi;
Futu::u32_t m_GetOptionEarningsScreenerSerialNo = 0;
};
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
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
getOptionEarningsScreener(qotGetOptionEarningsScreener)
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
Example
import ftWebsocket from "futu-api";
import { Common, Qot_OptionCommon } from "futu-api/proto";
import beautify from "js-beautify";
function QotGetOptionEarningsScreener(){
const { RetType } = Common
const { OptionMarket } = Qot_OptionCommon
let [addr, port, enable_ssl, key] = ["127.0.0.1", 11112, false, ''];
let websocket = new ftWebsocket();
websocket.onlogin = (ret, msg)=>{
if (ret) {
const req = {
c2s: {
optionMarket: OptionMarket.OptionMarket_US_Security,
count: 5,
},
};
websocket.GetOptionEarningsScreener(req)
.then((res)=>{
let { errCode, retMsg, retType, s2c } = res
console.log("GetOptionEarningsScreener: errCode %d, retMsg %s, retType %d", errCode, retMsg, retType);
if(retType == RetType.RetType_Succeed){
let data = beautify(JSON.stringify(s2c), { indent_size: 2, space_in_empty_paren: true });
console.log(data);
}
})
.catch((error)=>{ console.log("error:", error); });
} else {
console.log("start error", msg);
}
};
websocket.start(addr, port, enable_ssl, key);
setTimeout(()=>{ websocket.stop(); process.exit(); }, 5000);
}
QotGetOptionEarningsScreener()
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
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
- Output
GetOptionEarningsScreener: errCode 0, retMsg , retType 0
{
"itemList": [
{
"owner": { "market": 1, "code": "CGC" },
"name": "Canopy Growth",
"price": 1,
"changeRate": -0.99,
"marketCap": 422019000,
"iv": 204.207,
"ivRank": 36.55,
"ivPercentile": 88.492,
"hv": 39.545,
"volume": 8131,
"openInterest": 328382,
"earningsTimestamp": 1781496000,
"earningsTime": "2026-06-15",
"earningsPubType": 1,
"earningsQuarter": "2026Q4",
"lastReportIvCrush": -21.308,
"historyReportIvCrush": 11.782,
"lastReportChgRate": 1.851,
"historyReportChgRate": 12.761,
"estimateEpsYoy": 94.055,
"estimateRevenueYoy": 14.34,
"expectedMoveRatio": 12.5
},
{
"owner": { "market": 1, "code": "PLAY" },
"name": "Dave & Buster's Entertainment",
"price": 12.93,
"changeRate": -1.896,
"marketCap": 449180500,
"iv": 114.03,
"ivRank": 99.492,
"ivPercentile": 99.603,
"hv": 62.39,
"volume": 3052,
"openInterest": 44247,
"earningsTimestamp": 1781496000,
"earningsTime": "2026-06-15",
"earningsPubType": 2,
"earningsQuarter": "2027Q1",
"lastReportIvCrush": 22.64,
"historyReportIvCrush": 26.059,
"lastReportChgRate": 16.066,
"historyReportChgRate": 15.892,
"estimateEpsYoy": -3.758,
"estimateRevenueYoy": 1.881,
"expectedMoveRatio": 15.409
}
],
"allCount": 292
}
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
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
接口限制
- 30 秒內最多請求 60 次財報期權篩選接口（支持分頁的接口，僅首次調用納入統計）
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_option_earnings_screener(market, sort_type=None, is_asc=None, count=None, page=None, filter_list=None)
介紹
獲取即將發佈財報的期權標的列表，返回標的波動率數據、歷史財報 IV Crush、股價變動及市場預期等信息，幫助用戶在財報季進行期權交易決策。
參數
參數 類型 說明 market OptionMarket 期權市場類型 US_SECURITY=美股股票期權、HK_SECURITY=港股股票期權sort_type EarningsSortType 排序類型 EARNINGS_DATE=財報日期（默認）、VOLUME=期權成交量、IV=隱含波動率、MARKET_CAP=市值、CHANGE_RATIO=漲跌幅、PRICE=最新價、IV_RANK=IV等級、IV_PERCENTILE=IV百分位、HV=歷史波動率、OPEN_INTEREST=持倉量、LAST_REPORT_IV_CRUSH=上次IV Crush、HISTORY_REPORT_IV_CRUSH=歷史IV Crush、LAST_REPORT_CHG_RATIO=上次財報日漲跌幅、HISTORY_REPORT_CHG_RATIO=歷史財報日漲跌幅、ESTIMATE_EPS_YOY=預測EPS同比、ESTIMATE_REVENUE_YOY=預測營收同比、EXPECTED_MOVE_RATIO=預測波動is_asc bool 是否升序 默認 Truecount int 每頁數量 範圍 [1,500]，默認 50page str 分頁遊標 首次傳空或不傳，翻頁傳 next_pagefilter_list list[EarningsFilter] 篩選條件列表 多條件為 AND 關係返回
參數 類型 說明 ret RET_CODE 接口調用結果 data dict 當 ret == RET_OK，返回字典，包含 item_list（DataFrame）、next_page（str）、update_timestamp（float）、all_count（int） str 當 ret != RET_OK，返回錯誤描述 返回 DataFrame 字段：
字段 類型 說明 owner str 標的股票代碼 name str 標的名稱 price float 標的當前價格 change_ratio float 漲跌幅（小數） market_cap float 市值 iv float 隱含波動率（百分比） iv_rank float IV 等級（百分比） iv_percentile float IV 百分位（百分比） hv float 歷史波動率（百分比） volume int 期權成交量 open_interest int 期權持倉量 earnings_timestamp float 財報日期時間戳（Unix 秒） earnings_time str 財報日期字符串（yyyy-MM-dd） earnings_pub_type str 財報發佈類型（BEFORE=盤前/AFTER=盤後） earnings_quarter str 財報季度（如 '2025Q1'） last_report_iv_crush float 上次財報 IV Crush（百分比） history_report_iv_crush float 歷史平均財報 IV Crush（百分比） last_report_chg_ratio float 上次財報後股價變動（小數） history_report_chg_ratio float 歷史平均財報後股價變動（小數） estimate_eps_yoy float 預估 EPS 同比增長（百分比） estimate_revenue_yoy float 預估營收同比增長（百分比） expected_move_ratio float 期權隱含預期變動幅度（百分比）
Example
from moomoo import *
quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
ret, data = quote_ctx.get_option_earnings_screener(
market=OptionMarket.US_SECURITY,
count=5
)
if ret == RET_OK:
print(data['item_list'])
print('all_count:', data['all_count'])
else:
print('error:', data)
quote_ctx.close()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
- Output
owner name price change_ratio market_cap iv iv_rank iv_percentile hv volume open_interest earnings_timestamp earnings_time earnings_pub_type earnings_quarter last_report_iv_crush history_report_iv_crush last_report_chg_ratio history_report_chg_ratio estimate_eps_yoy estimate_revenue_yoy expected_move_ratio
0 US.CGC Canopy Growth 1.00 -0.990 4.220190e+08 204.207 36.550 88.492 39.545 8131 328382 1.781496e+09 2026-06-15 BEFORE 2026Q4 -21.308 11.782 1.851 12.761 94.055 14.340 12.500
1 US.PLAY Dave & Buster's Entertainment 12.93 -1.896 4.491805e+08 114.030 99.492 99.603 62.390 3052 44247 1.781496e+09 2026-06-15 AFTER 2027Q1 22.640 26.059 16.066 15.892 -3.758 1.881 15.409
2 US.DOMO Domo Inc 3.02 2.027 1.363547e+08 165.563 72.093 96.825 90.389 1970 29748 1.781496e+09 2026-06-15 AFTER 2027Q1 23.532 30.013 13.470 19.203 9.622 -0.451 30.629
3 US.CMTL Comverse 4.83 5.228 1.436158e+08 388.934 81.297 98.412 106.150 218 13434 1.781496e+09 2026-06-15 BEFORE 2026Q3 154.978 51.309 -24.536 16.278 -10.204 -13.078 23.809
4 US.RFIL RF Industries 18.75 0.969 2.027675e+08 100.939 11.123 54.365 83.526 215 2044 1.781496e+09 2026-06-15 AFTER 2026Q2 -14.722 6.537 12.318 12.013 200.000 3.997 15.466
all_count: 292
1
2
3
4
5
6
7
2
3
4
5
6
7
# Qot_GetOptionEarningsScreener.proto
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
uint GetOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req); virtual void OnReply_GetOptionEarningsScreener(MMAPI_Conn client, uint nSerialNo, Qot_GetOptionEarningsScreener.Response rsp);
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
int getOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req) onReply_GetOptionEarningsScreener(MMAPI_Conn client, int nSerialNo, Qot_GetOptionEarningsScreener.Response rsp)
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
Moomoo::u32_t GetOptionEarningsScreener(const Qot_GetOptionEarningsScreener::Request &stReq);
virtual void OnReply_GetOptionEarningsScreener(Moomoo::u32_t nSerialNo, const Qot_GetOptionEarningsScreener::Response &stRsp) = 0;
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
Example
class Program : public MMSPI_Qot, public MMSPI_Conn
{
public:
Program() {
m_pQotApi = MMAPI::CreateQotApi();
m_pQotApi->RegisterQotSpi(this);
m_pQotApi->RegisterConnSpi(this);
}
~Program() {
if (m_pQotApi != nullptr) {
m_pQotApi->UnregisterQotSpi();
m_pQotApi->UnregisterConnSpi();
MMAPI::ReleaseQotApi(m_pQotApi);
m_pQotApi = nullptr;
}
}
void Start() {
m_pQotApi->InitConnect("127.0.0.1", 11111, false);
}
virtual void OnInitConnect(MMAPI_Conn* pConn, Moomoo::i64_t nErrCode, const char* strDesc) {
Qot_GetOptionEarningsScreener::Request req;
Qot_GetOptionEarningsScreener::C2S *c2s = req.mutable_c2s();
// TODO: 按 proto 填充 c2s 字段
m_GetOptionEarningsScreenerSerialNo = m_pQotApi->GetOptionEarningsScreener(req);
}
virtual void OnReply_GetOptionEarningsScreener(Moomoo::u32_t nSerialNo, const Qot_GetOptionEarningsScreener::Response &stRsp) {
if (nSerialNo != m_GetOptionEarningsScreenerSerialNo) return;
string resp_str;
ProtoBufToBodyData(stRsp, resp_str);
cout << UTF8ToLocal(resp_str) << endl;
}
protected:
MMAPI_Qot *m_pQotApi;
Moomoo::u32_t m_GetOptionEarningsScreenerSerialNo = 0;
};
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
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
getOptionEarningsScreener(qotGetOptionEarningsScreener)
介紹
獲取即將發佈財報的期權標的列表
參數
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // 默認 true
optional int32 count = 4; // [1,500]（默認50）
optional string page = 5;
repeated Qot_OptionCommon.EarningsIndicator filterList = 6;
}
message Request
{
required C2S c2s = 1;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
- 返回
message EarningsItem {
required Qot_Common.Security owner = 1;
optional string name = 2;
optional double price = 3;
optional double changeRate = 4;
optional double marketCap = 5;
optional double iv = 6; // (%)
optional double ivRank = 7; // (%)
optional double ivPercentile = 8; // (%)
optional double hv = 9; // (%)
optional int64 volume = 10;
optional int64 openInterest = 11;
optional double earningsTimestamp = 12;
optional string earningsTime = 13;
optional int32 earningsPubType = 14; // Qot_OptionCommon.EarningsPubType
optional string earningsQuarter = 15;
optional double lastReportIvCrush = 16; // (%)
optional double historyReportIvCrush = 17; // (%)
optional double lastReportChgRate = 18;
optional double historyReportChgRate = 19;
optional double estimateEpsYoy = 20; // (%)
optional double estimateRevenueYoy = 21; // (%)
optional double expectedMoveRatio = 22; // (%)
}
message S2C {
repeated EarningsItem itemList = 1;
optional string nextPage = 2;
optional double updateTimestamp = 3;
optional int32 allCount = 4;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
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
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
- 接口調用結果，結構參見 RetType
協議 ID
3313
Example
import mmWebsocket from "moomoo-api";
import { Common, Qot_OptionCommon } from "moomoo-api/proto";
import beautify from "js-beautify";
function QotGetOptionEarningsScreener(){
const { RetType } = Common
const { OptionMarket } = Qot_OptionCommon
let [addr, port, enable_ssl, key] = ["127.0.0.1", 11112, false, ''];
let websocket = new mmWebsocket();
websocket.onlogin = (ret, msg)=>{
if (ret) {
const req = {
c2s: {
optionMarket: OptionMarket.OptionMarket_US_Security,
count: 5,
},
};
websocket.GetOptionEarningsScreener(req)
.then((res)=>{
let { errCode, retMsg, retType, s2c } = res
console.log("GetOptionEarningsScreener: errCode %d, retMsg %s, retType %d", errCode, retMsg, retType);
if(retType == RetType.RetType_Succeed){
let data = beautify(JSON.stringify(s2c), { indent_size: 2, space_in_empty_paren: true });
console.log(data);
}
})
.catch((error)=>{ console.log("error:", error); });
} else {
console.log("start error", msg);
}
};
websocket.start(addr, port, enable_ssl, key);
setTimeout(()=>{ websocket.stop(); process.exit(); }, 5000);
}
QotGetOptionEarningsScreener()
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
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
- Output
GetOptionEarningsScreener: errCode 0, retMsg , retType 0
{
"itemList": [
{
"owner": { "market": 1, "code": "CGC" },
"name": "Canopy Growth",
"price": 1,
"changeRate": -0.99,
"marketCap": 422019000,
"iv": 204.207,
"ivRank": 36.55,
"ivPercentile": 88.492,
"hv": 39.545,
"volume": 8131,
"openInterest": 328382,
"earningsTimestamp": 1781496000,
"earningsTime": "2026-06-15",
"earningsPubType": 1,
"earningsQuarter": "2026Q4",
"lastReportIvCrush": -21.308,
"historyReportIvCrush": 11.782,
"lastReportChgRate": 1.851,
"historyReportChgRate": 12.761,
"estimateEpsYoy": 94.055,
"estimateRevenueYoy": 14.34,
"expectedMoveRatio": 12.5
},
{
"owner": { "market": 1, "code": "PLAY" },
"name": "Dave & Buster's Entertainment",
"price": 12.93,
"changeRate": -1.896,
"marketCap": 449180500,
"iv": 114.03,
"ivRank": 99.492,
"ivPercentile": 99.603,
"hv": 62.39,
"volume": 3052,
"openInterest": 44247,
"earningsTimestamp": 1781496000,
"earningsTime": "2026-06-15",
"earningsPubType": 2,
"earningsQuarter": "2027Q1",
"lastReportIvCrush": 22.64,
"historyReportIvCrush": 26.059,
"lastReportChgRate": 16.066,
"historyReportChgRate": 15.892,
"estimateEpsYoy": -3.758,
"estimateRevenueYoy": 1.881,
"expectedMoveRatio": 15.409
}
],
"allCount": 292
}
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
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
接口限制
- 30 秒內最多請求 60 次財報期權篩選接口（支持分頁的接口，僅首次調用納入統計）