webull-openapi-python-sdk 2.0.4__py3-none-any.whl → 2.0.6__py3-none-any.whl

samples/__init__.py

@@ -1 +1 @@
-__version__ = '2.0.4'
+__version__ = '2.0.6'

samples/data/data_client.py

@@ -112,4 +112,36 @@ if __name__ == '__main__':
 
     res = data_client.instrument.get_futures_instrument_by_code("ES", Category.US_FUTURES.name, ContractType.MONTHLY.name)
     if res.status_code == 200:
-        print('get_futures_instrument_by_code:', res.json())
+        print('get_futures_instrument_by_code:', res.json())
+
+    res = data_client.instrument.get_company_profile("AAPL", Category.US_STOCK.name)
+    if res.status_code == 200:
+        print('get_company_profile:', res.json())
+
+    res = data_client.instrument.get_analyst_target_price("AAPL", Category.US_STOCK.name)
+    if res.status_code == 200:
+        print('get_analyst_target_price:', res.json())
+
+    res = data_client.instrument.get_analyst_rating("AAPL", Category.US_STOCK.name)
+    if res.status_code == 200:
+        print('get_analyst_rating:', res.json())
+
+    # NOII (Net Order Imbalance Indicator) - Opening imbalance bars
+    res = data_client.market_data.get_noii_bars("AAPL", Category.US_STOCK.name, "PRE_OPEN")
+    if res.status_code == 200:
+        print('get_noii_bars (opening):', res.json())
+
+    # NOII - Closing imbalance bars
+    res = data_client.market_data.get_noii_bars("AAPL", Category.US_STOCK.name, "PRE_CLOSE")
+    if res.status_code == 200:
+        print('get_noii_bars (closing):', res.json())
+
+    # NOII Snapshot - Opening imbalance
+    res = data_client.market_data.get_noii_snapshot("AAPL", Category.US_STOCK.name, "PRE_OPEN")
+    if res.status_code == 200:
+        print('get_noii_snapshot (opening):', res.json())
+
+    # NOII Snapshot - Closing imbalance
+    res = data_client.market_data.get_noii_snapshot("AAPL", Category.US_STOCK.name, "PRE_CLOSE")
+    if res.status_code == 200:
+        print('get_noii_snapshot (closing):', res.json())

samples/screener/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2022 Webull
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# coding=utf-8

samples/screener/screener_client.py

@@ -0,0 +1,118 @@
+# Copyright 2022 Webull
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# coding=utf-8
+
+from webull.core.client import ApiClient
+from webull.data.data_client import DataClient
+
+optional_api_endpoint = "<api_endpoint>"
+your_app_key = "<your_app_key>"
+your_app_secret = "<your_app_secret>"
+region_id = "<region_id>"
+
+api_client = ApiClient(your_app_key, your_app_secret, region_id)
+api_client.add_endpoint(region_id, optional_api_endpoint)
+
+
+if __name__ == '__main__':
+    data_client = DataClient(api_client)
+
+    # Get top gainers for today (stocks with highest price increase)
+    res = data_client.screener.get_gainers_losers(
+        rank_type="DAY_1",
+        category="US_STOCK",
+        sort_by="CHANGE_RATIO",
+        direction="DESC",
+        page_size=10
+    )
+    if res.status_code == 200:
+        print('get_gainers (day):', res.json())
+
+    # Get top losers for today (stocks with highest price decrease)
+    res = data_client.screener.get_gainers_losers(
+        rank_type="DAY_1",
+        category="US_STOCK",
+        sort_by="CHANGE_RATIO",
+        direction="ASC",
+        page_size=10
+    )
+    if res.status_code == 200:
+        print('get_losers (day):', res.json())
+
+    # Get pre-market movers
+    res = data_client.screener.get_gainers_losers(
+        rank_type="PRE_MARKET",
+        category="US_STOCK",
+        sort_by="CHANGE_RATIO",
+        direction="DESC",
+        page_size=20
+    )
+    if res.status_code == 200:
+        print('get_pre_market_movers:', res.json())
+
+    # Get 52-week top performers
+    res = data_client.screener.get_gainers_losers(
+        rank_type="WEEK_52",
+        category="US_STOCK",
+        sort_by="CHANGE_RATIO",
+        direction="DESC",
+        page_size=10
+    )
+    if res.status_code == 200:
+        print('get_52_week_top_performers:', res.json())
+
+    # Get most active stocks by volume
+    res = data_client.screener.get_most_active(
+        category="US_STOCK",
+        rank_type="VOLUME",
+        sort_by="VOLUME",
+        direction="DESC",
+        page_size=10
+    )
+    if res.status_code == 200:
+        print('get_most_active_by_volume:', res.json())
+
+    # Get stocks with unusual trading activity (high relative volume)
+    res = data_client.screener.get_most_active(
+        category="US_STOCK",
+        rank_type="RELATIVE_VOLUME_10D",
+        sort_by="RELATIVE_VOLUME_10D",
+        direction="DESC",
+        page_size=10
+    )
+    if res.status_code == 200:
+        print('get_unusual_volume_activity:', res.json())
+
+    # Get most active stocks by turnover amount
+    res = data_client.screener.get_most_active(
+        category="US_STOCK",
+        rank_type="TURNOVER",
+        sort_by="TURNOVER",
+        direction="DESC",
+        page_size=10
+    )
+    if res.status_code == 200:
+        print('get_most_active_by_turnover:', res.json())
+
+    # Get stocks with high price amplitude
+    res = data_client.screener.get_most_active(
+        category="US_STOCK",
+        rank_type="AMPLITUDE",
+        sort_by="AMPLITUDE",
+        direction="DESC",
+        page_size=10
+    )
+    if res.status_code == 200:
+        print('get_high_amplitude_stocks:', res.json())

samples/watchlist/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2022 Webull
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

samples/watchlist/watchlist_client.py

@@ -0,0 +1,87 @@
+# Copyright 2022 Webull
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# coding=utf-8
+
+from webull.core.client import ApiClient
+from webull.data.data_client import DataClient
+
+optional_api_endpoint = "<api_endpoint>"
+your_app_key = "<your_app_key>"
+your_app_secret = "<your_app_secret>"
+region_id = "<region_id>"
+
+api_client = ApiClient(your_app_key, your_app_secret, region_id)
+api_client.add_endpoint(region_id, optional_api_endpoint)
+
+
+if __name__ == '__main__':
+    data_client = DataClient(api_client)
+
+    # Get all watchlists
+    res = data_client.watchlist.get_watchlist()
+    if res.status_code == 200:
+        print('get_watchlist:', res.json())
+
+    # Create a new watchlist (max 20 watchlists, shared with retail)
+    res = data_client.watchlist.create_watchlist(name="Tech Stocks", sort=1)
+    if res.status_code == 200:
+        print('create_watchlist:', res.json())
+        watchlist_id = res.json().get("watchlist_id")
+
+        # Update the watchlist
+        res = data_client.watchlist.update_watchlist(
+            watchlist_id=watchlist_id,
+            name="My Favorites",
+            sort=2
+        )
+        if res.status_code == 200:
+            print('update_watchlist:', res.json())
+
+        # Add instruments to the watchlist (max 1000 instruments total)
+        instruments = [
+            {"symbol": "AAPL", "category": "US_STOCK", "sort": 1},
+            {"symbol": "TSLA", "category": "US_STOCK", "sort": 2}
+        ]
+        res = data_client.watchlist.add_instruments(watchlist_id, instruments)
+        if res.status_code == 200:
+            print('add_instruments:', res.json())
+
+        # Get instruments in the watchlist
+        res = data_client.watchlist.get_instruments(watchlist_id)
+        if res.status_code == 200:
+            print('get_instruments:', res.json())
+
+        # Update instruments sort order
+        instruments = [
+            {"symbol": "AAPL", "category": "US_STOCK", "sort": 3},
+            {"symbol": "TSLA", "category": "US_STOCK", "sort": 1}
+        ]
+        res = data_client.watchlist.update_instruments(watchlist_id, instruments)
+        if res.status_code == 200:
+            print('update_instruments:', res.json())
+
+        # Remove instruments from the watchlist
+        instruments = [
+            {"symbol": "AAPL", "category": "US_STOCK"},
+            {"symbol": "TSLA", "category": "US_STOCK"}
+        ]
+        res = data_client.watchlist.remove_instruments(watchlist_id, instruments)
+        if res.status_code == 200:
+            print('remove_instruments:', res.json())
+
+        # Delete the watchlist (irreversible)
+        res = data_client.watchlist.delete_watchlist(watchlist_id)
+        if res.status_code == 200:
+            print('delete_watchlist:', res.json())

webull/__init__.py

@@ -1 +1 @@
-__version__ = '2.0.4'
+__version__ = '2.0.6'

webull/core/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '2.0.4'
+__version__ = '2.0.6'
 
 import logging
 

webull/core/utils/common.py

@@ -72,6 +72,8 @@ def is_not_upgrade_api_host(host):
         "pre-openapi-us-alb.webullbroker.com","pre-openapi-us-events.webullbroker.com",
         "pre-openapi-alb.webullbroker.com","pre-openapi-events.webullbroker.com",
         "us-openapi-alb.uat.webullbroker.com","us-openapi-events.uat.webullbroker.com",
-        "hk-openapi.uat.webullbroker.com", "hk-openapi-events-api.uat.webullbroker.com"
+        "hk-openapi.uat.webullbroker.com", "hk-openapi-events-api.uat.webullbroker.com",
+        "api.sandbox.webull.hk", "events-api.sandbox.webull.hk"
+
     }
     return host not in upgrade_hosts

webull/data/__init__.py

@@ -1,3 +1,3 @@
 # coding=utf-8
 
-__version__ = '2.0.4'
+__version__ = '2.0.6'

webull/data/data_client.py

@@ -23,6 +23,8 @@ from webull.data.quotes.event_market_data import EventMarketData
 from webull.data.quotes.futures_market_data import FuturesMarketData
 from webull.data.quotes.instrument import Instrument
 from webull.data.quotes.market_data import MarketData
+from webull.data.quotes.screener import Screener
+from webull.data.quotes.watchlist import Watchlist
 
 
 class DataClient:
@@ -34,6 +36,8 @@ class DataClient:
         self.crypto_market_data = CryptoMarketData(api_client)
         self.futures_market_data = FuturesMarketData(api_client)
         self.event_market_data = EventMarketData(api_client)
+        self.screener = Screener(api_client)
+        self.watchlist = Watchlist(api_client)
 
     def _init_logger(self, api_client):
         # No logger configured, using default console and local file logging.

webull/data/quotes/instrument.py

@@ -12,6 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from webull.data.common.category import Category
+from webull.data.request.get_analyst_rating_request import GetAnalystRatingRequest
+from webull.data.request.get_analyst_target_price_request import GetAnalystTargetPriceRequest
+from webull.data.request.get_company_profile_request import GetCompanyProfileRequest
 from webull.data.request.get_event_events_request import GetEventEventsRequest
 from webull.data.request.get_event_instrument_request import GetEventInstrumentRequest
 from webull.data.request.get_event_series_categories import GetEventCategoriesRequest
@@ -21,6 +24,7 @@ from webull.data.request.get_crypto_instruments_request import GetCryptoInstrume
 from webull.data.request.get_futures_instruments_request import GetFuturesInstrumentsRequest
 from webull.data.request.get_futures_products_request import GetFuturesProductsRequest
 from webull.data.request.get_futures_instruments_by_code_request import GetFuturesInstrumentsByCodeRequest
+from webull.data.request.get_futures_product_class import GetFuturesProductClassRequest
 
 
 class Instrument:
@@ -68,32 +72,45 @@ class Instrument:
         response = self.client.get_response(crypto_instruments_request)
         return response
 
-    def get_futures_instrument(self, symbols, category):
+    def get_futures_instrument(self, symbols=None, category=Category.US_STOCK.name, code=None, status=None):
         """
          Query the futures instrument information based on the futures contract symbol.
 
-        :param symbols: Futures contract symbol, such as: ESmain,ESM5.
         :param category: Security type, enumeration.
+        :param symbols: Futures contract symbol, such as: ESmain,ESM5.
+        :param code: Futures contract code, such as: ES.
+        :param status: Tradable status.
         """
 
         futures_instrument_request = GetFuturesInstrumentsRequest()
-        futures_instrument_request.set_symbols(symbols)
         futures_instrument_request.set_category(category)
+        if symbols:
+            futures_instrument_request.set_symbols(symbols)
+        if code:
+            futures_instrument_request.set_code(code)
+        if status:
+            futures_instrument_request.set_status(status)
         response = self.client.get_response(futures_instrument_request)
         return response
 
-    def get_futures_products(self, category):
+    def get_futures_products(self, category, product_class_id=None):
         """
         Query futures contract codes in batches based on security types.
 
         :param category: Security type, enumeration.
+        :param product_class_id: Asset classification code, used to filter products of specific categories
         """
 
         batch_futures_products_request = GetFuturesProductsRequest()
         batch_futures_products_request.set_category(category)
+        if product_class_id:
+            batch_futures_products_request.set_product_class_id(product_class_id)
         response = self.client.get_response(batch_futures_products_request)
         return response
 
+    """
+    Deprecated: This endpoint is deprecated, please use the get_futures_instrument endpoint 
+    """
     def get_futures_instrument_by_code(self, code, category, contract_type=None):
         """
         Query futures instrument information based on futures contract code.
@@ -113,6 +130,18 @@ class Instrument:
         response = self.client.get_response(futures_instrument_request)
         return response
 
+    def get_futures_product_class(self, category):
+        """
+        Query futures product classes based on security types.
+
+        :param category: Security type, enumeration.
+        """
+
+        futures_product_class_request = GetFuturesProductClassRequest()
+        futures_product_class_request.set_category(category)
+        response = self.client.get_response(futures_product_class_request)
+        return response
+
     def get_event_categories(self):
         """
         Query event contract categories
@@ -187,4 +216,48 @@ class Instrument:
             event_instrument_request.set_last_instrument_id(last_instrument_id)
         event_instrument_request.set_page_size(page_size)
         response = self.client.get_response(event_instrument_request)
+        return response
+
+    def get_company_profile(self, symbol, category=Category.US_STOCK.name):
+        """
+        Get company profile for one instrument.
+
+        :param symbol: Security symbol, e.g., AAPL
+        :param category: Security type. Possible values: US_STOCK. Default is US_STOCK.
+        :return: Company profile including company name, establish date, CEO, employees,
+                 address, profile description, industries, etc.
+        """
+        request = GetCompanyProfileRequest()
+        request.set_symbol(symbol)
+        request.set_category(category)
+        response = self.client.get_response(request)
+        return response
+
+    def get_analyst_target_price(self, symbol, category=Category.US_STOCK.name):
+        """
+        Get analyst target price for one instrument.
+
+        :param symbol: Security symbol, e.g., AAPL
+        :param category: Security type. Possible values: US_STOCK. Default is US_STOCK.
+        :return: Analyst target price including mean, low, high, median price and currency.
+        """
+        request = GetAnalystTargetPriceRequest()
+        request.set_symbol(symbol)
+        request.set_category(category)
+        response = self.client.get_response(request)
+        return response
+
+    def get_analyst_rating(self, symbol, category=Category.US_STOCK.name):
+        """
+        Get analyst rating for one instrument.
+
+        :param symbol: Security symbol, e.g., AAPL
+        :param category: Security type. Possible values: US_STOCK. Default is US_STOCK.
+        :return: Analyst rating including total number of analysts, buy/sell/hold counts,
+                 strong buy count, under perform count, etc.
+        """
+        request = GetAnalystRatingRequest()
+        request.set_symbol(symbol)
+        request.set_category(category)
+        response = self.client.get_response(request)
         return response

webull/data/quotes/market_data.py

@@ -11,12 +11,13 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-from webull.data.common.category import Category
 from webull.data.request.get_batch_historical_bars_request import BatchHistoricalBarsRequest
 from webull.data.request.get_corp_action_request import GetCorpActionRequest
 from webull.data.request.get_eod_bars_request import GetEodBarsRequest
 from webull.data.request.get_footprint_request import GetFootprintRequest
 from webull.data.request.get_historical_bars_request import GetHistoricalBarsRequest
+from webull.data.request.get_noii_bars_request import GetNoiiBarsRequest
+from webull.data.request.get_noii_snapshot_request import GetNoiiSnapshotRequest
 from webull.data.request.get_quotes_request import GetQuotesRequest
 from webull.data.request.get_snapshot_request import GetSnapshotRequest
 from webull.data.request.get_tick_request import GetTickRequest
@@ -26,7 +27,7 @@ class MarketData:
     def __init__(self, api_client):
         self.client = api_client
 
-    def get_history_bar(self, symbol, category, timespan, count='200', real_time_required=None, trading_sessions=None):
+    def get_history_bar(self, symbol, category, timespan, count='200', real_time_required=None, trading_sessions=None, start_time=None, end_time=None):
         """
         Returns to Instrument in the window aggregated data.
         According to the last N K-lines of the stock code, it supports various granularity K-lines such as m1 and m5.
@@ -40,6 +41,8 @@ class MarketData:
         :param real_time_required: Returns the latest trade quote data. By default, the most recent market data is returned.
         :param trading_sessions: Specify trading session, multiple selections are allowed
         By default, only intraday candlestick data is returned.
+        :param start_time: Start timestamp in milliseconds (Long). Optional.
+        :param end_time: End timestamp in milliseconds (Long). Delayed permission will auto-offset time. Optional.
         """
         history_bar_request = GetHistoricalBarsRequest()
         history_bar_request.set_symbol(symbol)
@@ -48,10 +51,12 @@ class MarketData:
         history_bar_request.set_count(count)
         history_bar_request.set_real_time_required(real_time_required)
         history_bar_request.set_trading_sessions(trading_sessions)
+        history_bar_request.set_start_time(start_time)
+        history_bar_request.set_end_time(end_time)
         response = self.client.get_response(history_bar_request)
         return response
 
-    def get_batch_history_bar(self, symbols, category, timespan, count='200', real_time_required=None, trading_sessions=None):
+    def get_batch_history_bar(self, symbols, category, timespan, count='200', real_time_required=None, trading_sessions=None, start_time=None, end_time=None):
         """
         Batch query K-line data for multiple symbols, returning aggregated data within the window.
         According to the last N K-lines of the stock code, it supports various granularity K-lines such as m1 and m5.
@@ -65,6 +70,8 @@ class MarketData:
         :param real_time_required: Returns the latest trade quote data. By default, the most recent market data is returned.
         :param trading_sessions: Specify trading session, multiple selections are allowed
         By default, only intraday candlestick data is returned.
+        :param start_time: Start timestamp in milliseconds (Long). Optional.
+        :param end_time: End timestamp in milliseconds (Long). Delayed permission will auto-offset time. Optional.
         """
         history_bar_request = BatchHistoricalBarsRequest()
         history_bar_request.set_symbols(symbols)
@@ -73,6 +80,8 @@ class MarketData:
         history_bar_request.set_count(count)
         history_bar_request.set_real_time_required(real_time_required)
         history_bar_request.set_trading_sessions(trading_sessions)
+        history_bar_request.set_start_time(start_time)
+        history_bar_request.set_end_time(end_time)
         response = self.client.get_response(history_bar_request)
         return response
 
@@ -207,3 +216,56 @@ class MarketData:
         footprint_request.set_trading_sessions(trading_sessions)
         response = self.client.get_response(footprint_request)
         return response
+
+    def get_noii_bars(self, symbol, category, imbalance_action_type):
+        """
+        Query NOII (Net Order Imbalance Indicator) K-line data for a stock.
+
+        NOII data provides insight into market supply and demand during NASDAQ
+        opening and closing auctions, acting as a leading indicator for potential
+        price movements at key trading moments.
+
+        :param symbol: Security symbol, e.g., AAPL. Only single symbol query is supported.
+        :param category: Security category. Currently only US_STOCK is supported.
+        :param imbalance_action_type: Imbalance action type.
+            - PRE_OPEN: Opening imbalance
+            - PRE_CLOSE: Closing imbalance
+        :return: Response containing a list of NOII bar data with:
+            instrument_id, symbol, imbalance_time, imbalance_ref_price,
+            imbalance_near_price, imbalance_far_price, imbalance_action_type.
+        """
+        request = GetNoiiBarsRequest()
+        request.set_symbol(symbol)
+        request.set_category(category)
+        request.set_imbalance_action_type(imbalance_action_type)
+        response = self.client.get_response(request)
+        return response
+
+    def get_noii_snapshot(self, symbol, category, imbalance_action_type):
+        """
+        Query the latest NOII (Net Order Imbalance Indicator) snapshot for a stock.
+
+        Provides real-time NOII snapshot during US stock call auction phases to
+        determine market supply-demand relationship and expected match price.
+
+        NOII data is published only during call auction periods, updating every 5 seconds:
+        - Opening auction: 9:28 - 9:30 AM ET (2 minutes)
+        - Closing auction: 3:50 - 4:00 PM ET (10 minutes)
+        Outside these periods, historical data is returned.
+
+        :param symbol: Security symbol, e.g., AAPL. Only single symbol query is supported.
+        :param category: Security category. Currently only US_STOCK is supported.
+        :param imbalance_action_type: Imbalance action type.
+            - PRE_OPEN: Opening imbalance
+            - PRE_CLOSE: Closing imbalance
+        :return: Response containing NOII snapshot data with:
+            instrument_id, symbol, paired_shares, imbalance_shares, imbalance_side,
+            imbalance_ref_price, imbalance_near_price, imbalance_far_price,
+            imbalance_act_tp, imbalance_time, imbalance_var_indicator.
+        """
+        request = GetNoiiSnapshotRequest()
+        request.set_symbol(symbol)
+        request.set_category(category)
+        request.set_imbalance_action_type(imbalance_action_type)
+        response = self.client.get_response(request)
+        return response