篩選正股

• Python
• Proto
• C#
• Java
• C++
• JavaScript

get_stock_screen(request)

• 介紹

  條件選股 V2。相比舊接口 get_stock_filter，因子覆蓋更廣（11 類共 244+ 個因子），數值統一傳原始值（OpenD 自動倍率轉換），支持單字段或多字段排序、顯式聲明取回屬性，結果按 value_type 分別填入 sval / ival / aval / dval。

• 參數

  參數	類型	說明
  request	StockScreenRequest	條件選股請求對象，通過 builder 方式構建

  • StockScreenRequest 字段：

    字段	類型	說明
    page_from	int	分頁起始位置 不傳默認為 0
    page_count	int	單頁最大返回數 不傳默認為 200

  • 篩選條件 builder 方法（每次調用追加一條篩選條件，所有數值字段直接傳原始值，OpenD 自動倍率轉換）：

    方法	說明
    add_simple_field(field, values)	市場 / 交易所 / 指數 / 自選股等枚舉字段篩選 field 取自 SimpleField；values 為枚舉值列表（OR 關係）。ScrMarket.MY / JP / SG 後續支持，目前結果為空
    add_plate(plate_ids, parent_plate_id=None)	板塊篩選 plate_ids 形如 ["BK1001"]
    add_simple_property(name, lower=None, upper=None)	簡單行情屬性區間篩選 name 取自 SimpleProperty（最新價、市值、PE、量比等）；lower / upper 直接傳原始值，如最新價 10 元傳 10、市值 ≥ 100 億傳 10_000_000_000
    add_cumulative_property(name, days=1, lower=None, upper=None)	累計行情屬性 name 取自 CumulativeProperty；days 用於 N 日累計。漲跌幅類（如 PRICE_CHANGE_PCT）傳值為小數（5% 傳 0.05，非 5.0）
    add_financial_property(name, term=None, year=None, lower=None, upper=None, ...)	財務屬性 name 取自 FinancialProperty；term 取自 Term 枚舉（Q1=1、年報=100、最新單季=10 等）。Term.SURPRISE_LATEST 系列（200~204）實測 HK/US 均會返回數值，但當前數據通常與 ANNUAL 相同，慎用
    add_indicator_positional(first_indicator_name, period_type, position, second_indicator=None, ...)	技術指標位置關係 如 MA5 上穿 MA20。指標名/週期/位置取自 Indicator / Period / Position
    add_indicator_pattern(name, period_type, ...)	技術指標形態（金叉、死叉、背離等） name 取自 Pattern
    add_featured_property(name, intervals=None, value_set=None, period=None, range_period=None, first_custom_param=None)	特色指標（籌碼、熱度、分析師評級、資金流等）
    add_broker_holdings(name, days=None, param=None, intervals=None)	經紀商持股因子 僅港股。經紀商因子 6101 / 6102 / 6105 / 6106 / 6107 倍率 1000，按百分數傳值（如 20% 傳 20）；days 參數不生效
    add_kline_shape(name, period=None, value_set=None)	K 線形態（雙底、頭肩底等） period 必傳，目前僅支持日 K(11) 與 1 小時 K(21)
    add_option(name, intervals=None, param=None, period=None)	期權指標（正股 IV、HV 等）

  • 取回屬性 builder 方法（聲明返回哪些字段值；不聲明則只返回 stock_id）：

    方法	說明
    add_retrieve_basic(name)	代碼 / 名稱 / 行業 name 取自 BasicProperty：CODE=1101、NAME=1102、INDUSTRY=1103
    add_retrieve_simple(name)	簡單行情屬性 name 取自 SimpleProperty
    add_retrieve_cumulative(name, days=1, period_average=None)	累計屬性 name 取自 CumulativeProperty
    add_retrieve_financial(name, term=None, year=None, ...)	財務屬性 name 取自 FinancialProperty
    add_retrieve_indicator(name, period=None, indicator_params=None)	技術指標
    add_retrieve_featured(name, period=None, range_period=None, first_custom_param=None)	特色屬性
    add_retrieve_broker(name, days=None, param=None)	經紀商
    add_retrieve_option(name, param=None, period=None)	期權屬性
    add_retrieve_kline_shape(name, period=None)	K 線形態 period 必傳，否則不返回結果；目前僅支持日 K(11) 與 1 小時 K(21)

  • 排序 builder 方法：

    方法	說明
    set_sort(direction, property_type, property_params)	單字段排序 direction 取自 ScrSortDir：ASC=1、DESC=2、ABS_ASC=3、ABS_DESC=4。property_type 取 'basic' / 'simple' / 'cumulative' / 'financial' / 'indicator' / 'featured' / 'broker' / 'option' / 'kline_shape'
    add_sort(direction, property_type, property_params)	多字段排序 按調用順序生效；與 set_sort 二選一，sortList 非空時優先

• 返回

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

  • 返回 tuple 字段：

    字段	類型	說明
    last_page	bool	是否最後一頁
    all_count	int	滿足條件的總條數
    items	list[dict]	當前頁結果列表，元素結構為 {'stock_id': int, 'results': [result, ...]}

  • 單條 result 結構：

    字段	類型	說明
    type	str	屬性類型 'basic' / 'simple' / 'cumulative' / 'financial' / 'indicator' / 'featured' / 'broker' / 'option' / 'kline_shape'
    property	dict	對應 property 描述（含 name / days / term 等）
    value_type	int	值類型 1=string(sval)、2=int64(ival)、3=int64數組(aval)、4=double(dval)。當 OpenD 無數據時僅下發 value_type（多為 2），sval/ival/aval/dval 均缺失，如港股 Q2/Q3/Q4 財務數據
    sval	str	字符串值（value_type=1 時存在）
    ival	int	整型值（value_type=2 時存在）
    aval	list[int]	整型數組值（value_type=3 時存在）
    dval	float	浮點值（value_type=4 時存在）
    enum_type_name	str	當 ival 為枚舉碼時，對應的枚舉類型名（如 'KlineShapeType'）
    enum_name	str	當 ival 為枚舉碼時，OpenD/SDK 解碼出的枚舉名（如 'DOUBLE_BOTTOMS'、'NONE'）
    end_time	int	財報結束時間戳 僅 financial 類型，且當前 OpenD 版本暫未下發，實際返回結果中通常沒有該字段

• Example

from futu import OpenQuoteContext, RET_OK, StockScreenRequest
from futu.quote.stock_screen_const import (
    ScrMarket, ScrSortDir, SimpleField, SimpleProperty,
    CumulativeProperty, FinancialProperty, Term,
    Indicator, Period, Position, Pattern,
    BasicProperty, KlineShapeProperty, KlineShapeType,
)

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

# 示例 1：港股大市值股 + MACD 金叉
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_simple_property(name=SimpleProperty.PRICE, lower=10.0)                   # 最新價 ≥ 10
req.add_simple_property(name=SimpleProperty.MARKET_CAP, lower=10_000_000_000.0)  # 市值 ≥ 100 億
req.add_simple_property(name=SimpleProperty.PE_TTM, lower=10.0, upper=50.0)      # PE(TTM) 10~50
req.add_indicator_pattern(name=Pattern.MACD_GOLD_CROSS, period_type=Period.DAY)  # MACD 金叉
# 取回字段
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_basic(name=BasicProperty.NAME)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.add_retrieve_simple(name=SimpleProperty.MARKET_CAP)
req.add_retrieve_simple(name=SimpleProperty.PE_TTM)
# 排序
req.set_sort(direction=ScrSortDir.DESC, property_type='simple',
             property_params={'name': int(SimpleProperty.MARKET_CAP)})
req.page_count = 50

ret, data = quote_ctx.get_stock_screen(req)
if ret == RET_OK:
    last_page, all_count, items = data
    print(f"總數 {all_count}, 當前返回 {len(items)} 條")
    for it in items[:3]:
        print(it['stock_id'], it['results'])
else:
    print('error: ', data)

# 示例 2：財務因子 + 累計漲跌幅
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_cumulative_property(name=CumulativeProperty.PRICE_CHANGE_PCT,
                            days=5, lower=-0.05, upper=0.05)                     # 5 日漲跌幅 -5%~5%（百分數傳小數）
req.add_financial_property(name=FinancialProperty.NET_PROFIT,
                           term=Term.ANNUAL, lower=0.0)                          # 年報淨利潤 > 0
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.page_count = 200
ret, data = quote_ctx.get_stock_screen(req)

# 示例 3：K 線形態（W 型底 + 頭肩底）
req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_kline_shape(name=KlineShapeProperty.SHAPE_TYPE, period=Period.DAY,
                    value_set=[KlineShapeType.DOUBLE_BOTTOMS,
                               KlineShapeType.HEAD_SHOULDERS_BOTTOM])
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_kline_shape(name=KlineShapeProperty.SHAPE_TYPE, period=Period.DAY)
ret, data = quote_ctx.get_stock_screen(req)

quote_ctx.close()

• Output

總數 1, 當前返回 1 條
54047868453564 [{'type': 'basic', 'property': {'name': 1101}, 'value_type': 1, 'sval': '00700'},
                {'type': 'basic', 'property': {'name': 1102}, 'value_type': 1, 'sval': '騰訊控股'},
                {'type': 'simple', 'property': {'name': 2201}, 'value_type': 4, 'dval': 460.0},
                {'type': 'simple', 'property': {'name': 2301}, 'value_type': 4, 'dval': 4194280264040.0},
                {'type': 'simple', 'property': {'name': 2303}, 'value_type': 4, 'dval': 15.75126}]

Qot_StockScreen.proto

• 介紹

  條件選股 V2

• 參數

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

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

// ===== 各類 PropertyXxx =====
message PropertyBasic         { required int32 name = 1; }
message PropertySimple        { required int32 name = 1; optional int32 unit = 2; }
message PropertyCumulative    {
    required int32 name = 1;
    required int32 days = 2;
    optional int32 periodAverage = 3;
    optional int32 unit = 4;
}
message PropertyFinancial     {
    required int32 name = 1;
    optional int32 term = 2;
    optional int32 year = 3;
    optional int32 duration = 4;
    optional int32 periodAverage = 5;
    optional int32 futureDuration = 6;
    optional int32 unit = 7;
}
message PropertyIndicator     {
    required int32 name = 1;
    optional int32 period = 2;
    repeated int32 indicatorParams = 3;
}
message PropertyFeatured      {
    required int32 name = 1;
    optional int32 period = 2;
    optional int32 rangePeriod = 3;
    optional int32 firstCustomParam = 4;
}
message PropertyBroker        {
    required int32 name = 1;
    optional int32 days = 2;
    optional string param = 3;
}
message PropertyOption        {
    required int32 name = 1;
    optional int32 period = 2;
    optional string param = 3;
}
message PropertyKlineShape    {
    required int32 name = 1;
    optional int32 period = 2;
}

// ===== 各類 QueryXxx =====
message SimpleFieldQuery
{
    required int32 simpleField = 1;
    repeated int32 screenValueList = 2;
}

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

message PlateQuery       { repeated PlateInfo plateList = 1; }

message SimplePropertyQuery
{
    required PropertySimple property = 1;
    optional Boundary filterMin = 2;
    optional Boundary filterMax = 3;
}

message CumulativePropertyQuery
{
    required PropertyCumulative property = 1;
    optional Boundary filterMin = 2;
    optional Boundary filterMax = 3;
    optional int32 continuousPeriod = 4;
}

message FinancialPropertyQuery
{
    required PropertyFinancial property = 1;
    optional Boundary filterMin = 2;
    optional Boundary filterMax = 3;
    optional int32 continuousPeriod = 4;
}

message IndicatorPositionalQuery
{
    required int32 firstIndicatorName = 1;
    required int32 periodType = 2;
    required int32 position = 3;
    optional int32 secondIndicator = 4;
    optional int32 secondValue = 5;
    repeated int32 firstIndicatorParams = 6;
    repeated int32 secondIndicatorParams = 7;
    optional int32 continuousPeriod = 8;
    repeated Interval intervals = 9;
}

message IndicatorPatternQuery
{
    required int32 name = 1;
    required int32 periodType = 2;
    optional int32 continuousPeriod = 3;
    optional bool isMatching = 4;
    repeated int32 subPatterns = 5;
}

message FeaturedPropertyQuery
{
    required PropertyFeatured property = 1;
    repeated Interval intervals = 2;
    repeated int32 valueSet = 3;
}

message BrokerHoldingsQuery
{
    required PropertyBroker property = 1;
    repeated Interval intervals = 2;
}

message KlineShapeQuery
{
    required PropertyKlineShape property = 1;
    repeated int32 valueSet = 2;
}

message OptionQuery
{
    required PropertyOption property = 1;
    repeated Interval intervals = 2;
}

// ===== 一條篩選條件 (oneof 多選一) =====
message ScreenQuery
{
    optional SimpleFieldQuery simpleFieldQuery = 1;
    optional PlateQuery plateQuery = 2;
    optional SimplePropertyQuery simplePropertyQuery = 3;
    optional CumulativePropertyQuery cumulativePropertyQuery = 4;
    optional FinancialPropertyQuery financialPropertyQuery = 5;
    optional IndicatorPositionalQuery indicatorPositionalQuery = 6;
    optional IndicatorPatternQuery indicatorPatternQuery = 7;
    optional FeaturedPropertyQuery featuredPropertyQuery = 8;
    optional BrokerHoldingsQuery brokerHoldingsQuery = 9;
    optional KlineShapeQuery klineShapeQuery = 10;
    optional OptionQuery optionQuery = 11;
}

// ===== 取回字段 =====
message RetrieveQuery
{
    optional PropertyBasic basicProperty = 1;
    optional PropertySimple simpleProperty = 2;
    optional PropertyCumulative cumulativeProperty = 3;
    optional PropertyFinancial financialProperty = 4;
    optional PropertyIndicator indicatorProperty = 5;
    optional PropertyFeatured featuredProperty = 6;
    optional PropertyBroker brokerProperty = 7;
    optional PropertyOption optionProperty = 8;
    optional PropertyKlineShape klineShapeProperty = 9;
}

// ===== 排序定義 =====
message Sort
{
    required int32 direction = 1;   // 1=ASC, 2=DESC, 3=ABS_ASC, 4=ABS_DESC
    optional PropertyBasic basicProperty = 2;
    optional PropertySimple simpleProperty = 3;
    optional PropertyCumulative cumulativeProperty = 4;
    optional PropertyFinancial financialProperty = 5;
    optional PropertyIndicator indicatorProperty = 6;
    optional PropertyFeatured featuredProperty = 7;
    optional PropertyBroker brokerProperty = 8;
    optional PropertyOption optionProperty = 9;
    optional PropertyKlineShape klineShapeProperty = 10;
}

message C2S
{
    repeated ScreenQuery filterList = 1;
    repeated RetrieveQuery retrieveList = 2;
    repeated int64 watchlistStockIds = 3;
    optional Sort sort = 4;             // 單字段排序
    optional int32 pageFrom = 5;
    optional int32 pageCount = 6;
    repeated Sort sortList = 7;         // 多字段排序，非空時優先於 sort
}

message Request
{
    required C2S c2s = 1;
}

• 返回

// 單條結果值: valueType=1 時取 sval, =2 取 ival, =3 取 aval, =4 取 dval
message ResultPropertyBasic
{
    required PropertyBasic property = 1;
    optional int32 valueType = 2;
    optional string sval = 3;
    optional int64 ival = 4;
    repeated int64 aval = 5;
    optional double dval = 6;
    optional string enumTypeName = 7;
    optional string enumName = 8;
}
// 其餘 ResultPropertySimple / Cumulative / Financial / Indicator / Featured / Broker / Option / KlineShape
// 結構與 ResultPropertyBasic 相同，僅 property 類型不同。Financial 額外包含 endTime。

message RspItemResult
{
    optional ResultPropertyBasic basicPropertyResult = 1;
    optional ResultPropertySimple simplePropertyResult = 2;
    optional ResultPropertyCumulative cumulativePropertyResult = 3;
    optional ResultPropertyFinancial financialPropertyResult = 4;
    optional ResultPropertyIndicator indicatorPropertyResult = 5;
    optional ResultPropertyFeatured featuredPropertyResult = 6;
    optional ResultPropertyBroker brokerPropertyResult = 7;
    optional ResultPropertyOption optionPropertyResult = 8;
    optional ResultPropertyKlineShape klineShapePropertyResult = 9;
}

message RspItem
{
    required int64 stockId = 1;
    repeated RspItemResult results = 2;
}

message S2C
{
    required bool lastPage = 1;
    required int32 allCount = 2;
    repeated RspItem dataList = 3;
}

message Response
{
    required int32 retType = 1 [default = -400];
    optional string retMsg = 2;
    optional int32 errCode = 3;
    optional S2C s2c = 4;
}

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

• 協議 ID

  3252

uint StockScreen(QotStockScreen.Request req); virtual void OnReply_StockScreen(FTAPI_Conn client, uint nSerialNo, QotStockScreen.Response rsp);

• 介紹

  條件選股 V2

• 參數

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。

• 返回

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。

• 協議 ID

  3252

int stockScreen(QotStockScreen.Request req) onReply_StockScreen(FTAPI_Conn client, int nSerialNo, QotStockScreen.Response rsp)

• 介紹

  條件選股 V2

• 參數

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。

• 返回

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。

• 協議 ID

  3252

bool StockScreen(uint32_t & nSerialNo, const Qot_StockScreen::Request & stReq); virtual void OnReply_StockScreen(FTAPI_Conn* pConn, uint32_t nSerialNo, const Qot_StockScreen::Response & stRsp)

• 介紹

  條件選股 V2

• 參數

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。

• 返回

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。

• 協議 ID

  3252

stockScreen(qotStockScreen)

• 介紹

  條件選股 V2

• 參數

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的請求結構。

• 返回

  參考 Proto 標籤頁中 Qot_StockScreen.proto 的響應結構。

• 協議 ID

  3252

• Python
• Proto
• C#
• Java
• C++
• JavaScript

get_stock_screen(request)

• 介紹

  條件選股 V2，參數與返回字段同 nn 標籤頁。

• Example

from moomoo import OpenQuoteContext, RET_OK, StockScreenRequest
from moomoo.quote.stock_screen_const import (
    ScrMarket, ScrSortDir, SimpleField, SimpleProperty,
    Indicator, Period, Pattern, BasicProperty,
)

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

req = StockScreenRequest()
req.add_simple_field(field=SimpleField.MARKET, values=[ScrMarket.HK])
req.add_simple_property(name=SimpleProperty.PRICE, lower=10.0)
req.add_simple_property(name=SimpleProperty.MARKET_CAP, lower=10_000_000_000.0)
req.add_indicator_pattern(name=Pattern.MACD_GOLD_CROSS, period_type=Period.DAY)
req.add_retrieve_basic(name=BasicProperty.CODE)
req.add_retrieve_basic(name=BasicProperty.NAME)
req.add_retrieve_simple(name=SimpleProperty.PRICE)
req.add_retrieve_simple(name=SimpleProperty.MARKET_CAP)
req.set_sort(direction=ScrSortDir.DESC, property_type='simple',
             property_params={'name': int(SimpleProperty.MARKET_CAP)})
req.page_count = 50

ret, data = quote_ctx.get_stock_screen(req)
if ret == RET_OK:
    last_page, all_count, items = data
    print(f"總數 {all_count}, 當前返回 {len(items)} 條")
else:
    print('error: ', data)

quote_ctx.close()

Qot_StockScreen.proto

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

uint StockScreen(QotStockScreen.Request req); virtual void OnReply_StockScreen(FTAPI_Conn client, uint nSerialNo, QotStockScreen.Response rsp);

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

int stockScreen(QotStockScreen.Request req) onReply_StockScreen(FTAPI_Conn client, int nSerialNo, QotStockScreen.Response rsp)

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

bool StockScreen(uint32_t & nSerialNo, const Qot_StockScreen::Request & stReq); virtual void OnReply_StockScreen(FTAPI_Conn* pConn, uint32_t nSerialNo, const Qot_StockScreen::Response & stRsp)

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

stockScreen(qotStockScreen)

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