# Option Earnings Screener
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_option_earnings_screener(market, sort_type=None, is_asc=None, count=None, page=None, filter_list=None)
Description
Get the list of option underlyings with upcoming earnings releases, returning volatility data, historical earnings IV crush, stock price movement, and market expectations to help users make option trading decisions during earnings season.
Parameters
Parameter Type Description market OptionMarket Option market type US_SECURITY=US equity options, HK_SECURITY=HK equity optionssort_type EarningsSortType Sort type EARNINGS_DATE=earnings date (default), VOLUME=option volume, IV=implied volatility, MARKET_CAP=market cap, CHANGE_RATIO=price change, PRICE=latest price, IV_RANK=IV rank, IV_PERCENTILE=IV percentile, HV=historical volatility, OPEN_INTEREST=open interest, LAST_REPORT_IV_CRUSH=last IV crush, HISTORY_REPORT_IV_CRUSH=historical IV crush, LAST_REPORT_CHG_RATIO=last earnings price change, HISTORY_REPORT_CHG_RATIO=historical earnings price change, ESTIMATE_EPS_YOY=estimated EPS YoY, ESTIMATE_REVENUE_YOY=estimated revenue YoY, EXPECTED_MOVE_RATIO=expected moveis_asc bool Ascending order Default Truecount int Items per page Range [1,500], default 50page str Pagination cursor Leave empty or omit for first call, pass next_page for subsequent pagesfilter_list list[EarningsFilter] Filter conditions list Multiple conditions use AND logicReturns
Parameter Type Description ret RET_CODE Interface call result data dict When ret == RET_OK, returns a dict containing item_list (DataFrame), next_page (str), update_timestamp (float), all_count (int) str When ret != RET_OK, returns error description Return DataFrame fields:
Field Type Description owner str Underlying stock code name str Underlying name price float Underlying current price change_ratio float Price change ratio (decimal) market_cap float Market capitalization iv float Implied volatility (percentage) iv_rank float IV rank (percentage) iv_percentile float IV percentile (percentage) hv float Historical volatility (percentage) volume int Option volume open_interest int Option open interest earnings_timestamp float Earnings date timestamp (Unix seconds) earnings_time str Earnings date string (yyyy-MM-dd) earnings_pub_type str Earnings release type (BEFORE=pre-market/AFTER=post-market) earnings_quarter str Earnings quarter (e.g. '2025Q1') last_report_iv_crush float Last earnings IV crush (percentage) history_report_iv_crush float Historical average earnings IV crush (percentage) last_report_chg_ratio float Last post-earnings stock price change (decimal) history_report_chg_ratio float Historical average post-earnings stock price change (decimal) estimate_eps_yoy float Estimated EPS year-over-year growth (percentage) estimate_revenue_yoy float Estimated revenue year-over-year growth (percentage) expected_move_ratio float Option implied expected move (percentage)
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
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol ID
3313
uint GetOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req); virtual void OnReply_GetOptionEarningsScreener(FTAPI_Conn client, uint nSerialNo, Qot_GetOptionEarningsScreener.Response rsp);
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol ID
3313
int getOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req) onReply_GetOptionEarningsScreener(FTAPI_Conn client, int nSerialNo, Qot_GetOptionEarningsScreener.Response rsp)
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol 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;
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol 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: populate c2s fields per proto
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)
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol 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
Rate Limit
- Maximum 60 requests per 30 seconds (for paginated interfaces, only the first call counts)
- Python
- Proto
- C#
- Java
- C++
- JavaScript
get_option_earnings_screener(market, sort_type=None, is_asc=None, count=None, page=None, filter_list=None)
Description
Get the list of option underlyings with upcoming earnings releases, returning volatility data, historical earnings IV crush, stock price movement, and market expectations to help users make option trading decisions during earnings season.
Parameters
Parameter Type Description market OptionMarket Option market type US_SECURITY=US equity options, HK_SECURITY=HK equity optionssort_type EarningsSortType Sort type EARNINGS_DATE=earnings date (default), VOLUME=option volume, IV=implied volatility, MARKET_CAP=market cap, CHANGE_RATIO=price change, PRICE=latest price, IV_RANK=IV rank, IV_PERCENTILE=IV percentile, HV=historical volatility, OPEN_INTEREST=open interest, LAST_REPORT_IV_CRUSH=last IV crush, HISTORY_REPORT_IV_CRUSH=historical IV crush, LAST_REPORT_CHG_RATIO=last earnings price change, HISTORY_REPORT_CHG_RATIO=historical earnings price change, ESTIMATE_EPS_YOY=estimated EPS YoY, ESTIMATE_REVENUE_YOY=estimated revenue YoY, EXPECTED_MOVE_RATIO=expected moveis_asc bool Ascending order Default Truecount int Items per page Range [1,500], default 50page str Pagination cursor Leave empty or omit for first call, pass next_page for subsequent pagesfilter_list list[EarningsFilter] Filter conditions list Multiple conditions use AND logicReturns
Parameter Type Description ret RET_CODE Interface call result data dict When ret == RET_OK, returns a dict containing item_list (DataFrame), next_page (str), update_timestamp (float), all_count (int) str When ret != RET_OK, returns error description Return DataFrame fields:
Field Type Description owner str Underlying stock code name str Underlying name price float Underlying current price change_ratio float Price change ratio (decimal) market_cap float Market capitalization iv float Implied volatility (percentage) iv_rank float IV rank (percentage) iv_percentile float IV percentile (percentage) hv float Historical volatility (percentage) volume int Option volume open_interest int Option open interest earnings_timestamp float Earnings date timestamp (Unix seconds) earnings_time str Earnings date string (yyyy-MM-dd) earnings_pub_type str Earnings release type (BEFORE=pre-market/AFTER=post-market) earnings_quarter str Earnings quarter (e.g. '2025Q1') last_report_iv_crush float Last earnings IV crush (percentage) history_report_iv_crush float Historical average earnings IV crush (percentage) last_report_chg_ratio float Last post-earnings stock price change (decimal) history_report_chg_ratio float Historical average post-earnings stock price change (decimal) estimate_eps_yoy float Estimated EPS year-over-year growth (percentage) estimate_revenue_yoy float Estimated revenue year-over-year growth (percentage) expected_move_ratio float Option implied expected move (percentage)
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
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol ID
3313
uint GetOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req); virtual void OnReply_GetOptionEarningsScreener(MMAPI_Conn client, uint nSerialNo, Qot_GetOptionEarningsScreener.Response rsp);
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol ID
3313
int getOptionEarningsScreener(Qot_GetOptionEarningsScreener.Request req) onReply_GetOptionEarningsScreener(MMAPI_Conn client, int nSerialNo, Qot_GetOptionEarningsScreener.Response rsp)
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol 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;
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol 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: populate c2s fields per proto
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)
Description
Get the list of option underlyings with upcoming earnings releases
Parameters
message C2S {
required int32 optionMarket = 1; // Qot_OptionCommon.OptionMarket
optional int32 sortType = 2; // Qot_OptionCommon.EarningsSortType
optional bool isAsc = 3; // Default true
optional int32 count = 4; // [1,500] (default 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
- Returns
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, return result
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
- Interface call result, structure refer to RetType
Protocol 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
Rate Limit
- Maximum 60 requests per 30 seconds (for paginated interfaces, only the first call counts)