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

webull/data/quotes/screener.py

@@ -0,0 +1,116 @@
+# 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.data.request.screener.get_gainers_losers_request import GetGainersLosersRequest
+from webull.data.request.screener.get_most_active_request import GetMostActiveRequest
+
+
+class Screener:
+    """
+    Screener class provides access to stock screening and ranking APIs.
+    
+    This class includes methods for:
+    - Top gainers/losers ranking by price change over various time periods
+    - Most active stocks ranking by volume, turnover, and other activity metrics
+    """
+    
+    def __init__(self, api_client):
+        self.client = api_client
+
+    def get_gainers_losers(self, rank_type, category, sort_by, page_index=None, page_size=None, direction=None):
+        """
+        Get stock top gainers or losers ranking by price change percentage.
+        
+        This API returns stocks ranked by price change over different time periods.
+        Use direction='DESC' for gainers (top performers) and direction='ASC' for losers.
+        
+        :param rank_type: Time period for ranking. Required.
+            Enum values:
+            - PRE_MARKET: Pre-market session
+            - AFTER_MARKET: After-market session
+            - MIN_3: 3 minutes
+            - MIN_5: 5 minutes
+            - DAY_1: 1 day
+            - DAY_5: 5 days
+            - MONTH_1: 1 month
+            - MONTH_3: 3 months
+            - WEEK_52: 52 weeks
+        :param category: Security market category. Required. (e.g., 'US_STOCK')
+        :param sort_by: Secondary sort field. Required.
+            Enum values: CHANGE_RATIO, RELATIVE_VOLUME_10D, MARKET_VALUE, CLOSE,
+            PRICE, PE_TTM, HIGH, LOW, AMPLITUDE, TURNOVER, VOLUME
+        :param page_index: Page number, starting from 1. Optional.
+        :param page_size: Number of records per page. Optional.
+        :param direction: Sort direction. Optional.
+            - ASC: Ascending (for losers)
+            - DESC: Descending (for gainers)
+        :return: Response containing has_more flag and list of ranked stocks with
+            instrument_id, symbol, name, exchange_code, currency_code, pre_close,
+            open, high, low, close, price, change, change_ratio, volume,
+            turnover, turnover_rate, market_value, amplitude.
+        """
+        request = GetGainersLosersRequest()
+        request.set_rank_type(rank_type)
+        request.set_category(category)
+        request.set_sort_by(sort_by)
+        request.set_page_index(page_index)
+        request.set_page_size(page_size)
+        request.set_direction(direction)
+        response = self.client.get_response(request)
+        return response
+
+    def get_most_active(self, category, rank_type=None, sort_by=None, page_index=None, page_size=None, direction=None):
+        """
+        Get most actively traded stocks ranking.
+        
+        This API returns stocks ranked by trading activity metrics such as volume,
+        relative volume, turnover amount, turnover rate, or amplitude.
+        
+        Default sort: rank_type=VOLUME, sort_by=VOLUME, direction=DESC
+        
+        The relative_volume_10d field is unique to this endpoint compared to
+        the gainers/losers endpoint.
+        
+        :param category: Security market category. Required. (e.g., 'US_STOCK')
+        :param rank_type: Activity metric for ranking. Optional (defaults to VOLUME).
+            Enum values:
+            - VOLUME: Trading volume
+            - RELATIVE_VOLUME_10D: 10-day relative volume
+            - TURNOVER: Turnover amount
+            - TURNOVER_RATE: Turnover rate
+            - AMPLITUDE: Price amplitude
+        :param sort_by: Secondary sort field. Optional.
+            Enum values: CHANGE_RATIO, RELATIVE_VOLUME_10D, MARKET_VALUE, CLOSE,
+            PRICE, PE_TTM, HIGH, LOW, AMPLITUDE, TURNOVER, VOLUME
+        :param page_index: Page number, starting from 1. Optional.
+        :param page_size: Number of records per page. Optional.
+        :param direction: Sort direction. Optional (defaults to DESC).
+            - ASC: Ascending order
+            - DESC: Descending order
+        :return: Response containing has_more flag and list of ranked stocks with
+            instrument_id, symbol, name, exchange_code, currency_code, pre_close,
+            open, high, low, close, price, change, change_ratio, volume,
+            turnover, turnover_rate, market_value, amplitude, relative_volume_10d.
+        """
+        request = GetMostActiveRequest()
+        request.set_category(category)
+        request.set_rank_type(rank_type)
+        request.set_sort_by(sort_by)
+        request.set_page_index(page_index)
+        request.set_page_size(page_size)
+        request.set_direction(direction)
+        response = self.client.get_response(request)
+        return response

webull/data/quotes/watchlist.py

@@ -0,0 +1,148 @@
+# 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.data.request.watchlist.create_watchlist_request import CreateWatchlistRequest
+from webull.data.request.watchlist.delete_watchlist_request import DeleteWatchlistRequest
+from webull.data.request.watchlist.update_watchlist_request import UpdateWatchlistRequest
+from webull.data.request.watchlist.get_watchlist_request import GetWatchlistRequest
+from webull.data.request.watchlist.add_watchlist_instruments_request import AddWatchlistInstrumentsRequest
+from webull.data.request.watchlist.remove_watchlist_instruments_request import RemoveWatchlistInstrumentsRequest
+from webull.data.request.watchlist.update_watchlist_instruments_request import UpdateWatchlistInstrumentsRequest
+from webull.data.request.watchlist.get_watchlist_instruments_request import GetWatchlistInstrumentsRequest
+
+
+class Watchlist:
+    def __init__(self, api_client):
+        self.client = api_client
+
+    def create_watchlist(self, name, sort=None):
+        """
+        Create a new watchlist.
+        Maximum 20 watchlists can be created (shared with retail).
+
+        :param name: Watchlist name. Maximum 20 watchlists can be created.
+        :param sort: Sort order number (optional).
+        :return: Response containing the new watchlist_id.
+        """
+        request = CreateWatchlistRequest()
+        request.set_name(name)
+        request.set_sort(sort)
+        response = self.client.get_response(request)
+        return response
+
+    def delete_watchlist(self, watchlist_id):
+        """
+        Delete a watchlist and all instruments in it. This operation is irreversible.
+
+        :param watchlist_id: Watchlist unique identifier.
+        :return: Response containing success status.
+        """
+        request = DeleteWatchlistRequest()
+        request.set_watchlist_id(watchlist_id)
+        response = self.client.get_response(request)
+        return response
+
+    def update_watchlist(self, watchlist_id, name=None, sort=None):
+        """
+        Update an existing watchlist's properties such as name or sort order.
+        Only provided fields will be updated; unprovided fields remain unchanged.
+
+        :param watchlist_id: Watchlist unique identifier.
+        :param name: New watchlist name (optional).
+        :param sort: New sort order number (optional).
+        :return: Response containing success status.
+        """
+        request = UpdateWatchlistRequest()
+        request.set_watchlist_id(watchlist_id)
+        request.set_name(name)
+        request.set_sort(sort)
+        response = self.client.get_response(request)
+        return response
+
+    def get_watchlist(self):
+        """
+        Get all watchlists for the current user, sorted by sort order in descending order.
+
+        :return: List of watchlists containing watchlist_id, name, sort, create_time, update_time.
+        """
+        request = GetWatchlistRequest()
+        response = self.client.get_response(request)
+        return response
+
+    def add_instruments(self, watchlist_id, instruments):
+        """
+        Add one or more instruments to an existing watchlist.
+        Currently does not support EC contracts, futures, or options.
+        Maximum 1000 instruments total across all watchlists.
+
+        :param watchlist_id: Watchlist unique identifier.
+        :param instruments: List of instruments to add. Each instrument should contain:
+            - symbol: Instrument symbol (e.g., AAPL)
+            - category: Instrument category (e.g., US_STOCK, US_CRYPTO)
+            - sort: Sort order number
+        :return: Response containing success status.
+        """
+        request = AddWatchlistInstrumentsRequest()
+        request.set_watchlist_id(watchlist_id)
+        request.set_instruments(instruments)
+        response = self.client.get_response(request)
+        return response
+
+    def remove_instruments(self, watchlist_id, instruments):
+        """
+        Remove one or more instruments from a watchlist by symbol and category.
+
+        :param watchlist_id: Watchlist unique identifier.
+        :param instruments: List of instruments to remove. Each instrument should contain:
+            - symbol: Instrument symbol (e.g., AAPL)
+            - category: Instrument category (e.g., US_STOCK)
+        :return: Response containing success status.
+        """
+        request = RemoveWatchlistInstrumentsRequest()
+        request.set_watchlist_id(watchlist_id)
+        request.set_instruments(instruments)
+        response = self.client.get_response(request)
+        return response
+
+    def update_instruments(self, watchlist_id, instruments):
+        """
+        Update the sort order of instruments in a watchlist.
+
+        :param watchlist_id: Watchlist unique identifier.
+        :param instruments: List of instruments to update. Each instrument should contain:
+            - symbol: Instrument symbol (for locating)
+            - category: Instrument category (for locating)
+            - sort: New sort order number
+        :return: Response containing success status.
+        """
+        request = UpdateWatchlistInstrumentsRequest()
+        request.set_watchlist_id(watchlist_id)
+        request.set_instruments(instruments)
+        response = self.client.get_response(request)
+        return response
+
+    def get_instruments(self, watchlist_id):
+        """
+        Get all instruments in a watchlist, sorted by sort_order in descending order.
+
+        :param watchlist_id: Watchlist unique identifier.
+        :return: Response containing watchlist_id and list of instruments with
+            instrument_id, symbol, name, exchange_code, sort, added_time.
+        """
+        request = GetWatchlistInstrumentsRequest()
+        request.set_watchlist_id(watchlist_id)
+        response = self.client.get_response(request)
+        return response

webull/data/request/get_analyst_rating_request.py

@@ -0,0 +1,38 @@
+# 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.request import ApiRequest
+
+
+class GetAnalystRatingRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/instrument/analyst/rating", version="v2", method="GET", query_params={})
+
+    def set_symbol(self, symbol):
+        """
+        Set the security symbol.
+
+        :param symbol: Security symbol, e.g., AAPL
+        """
+        self.add_query_param("symbol", symbol)
+
+    def set_category(self, category):
+        """
+        Set the security type.
+
+        :param category: Security type. Possible values: US_STOCK
+        """
+        self.add_query_param("category", category)

webull/data/request/get_analyst_target_price_request.py

@@ -0,0 +1,38 @@
+# 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.request import ApiRequest
+
+
+class GetAnalystTargetPriceRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/instrument/analyst/target-price", version="v2", method="GET", query_params={})
+
+    def set_symbol(self, symbol):
+        """
+        Set the security symbol.
+
+        :param symbol: Security symbol, e.g., AAPL
+        """
+        self.add_query_param("symbol", symbol)
+
+    def set_category(self, category):
+        """
+        Set the security type.
+
+        :param category: Security type. Possible values: US_STOCK
+        """
+        self.add_query_param("category", category)

webull/data/request/get_batch_historical_bars_request.py

@@ -40,4 +40,22 @@ class BatchHistoricalBarsRequest(ApiRequest):
             if isinstance(trading_sessions, list):
                 self.add_body_params("trading_sessions", ','.join(trading_sessions))
             else:
-                self.add_body_params("trading_sessions", trading_sessions)
+                self.add_body_params("trading_sessions", trading_sessions)
+
+    def set_start_time(self, start_time):
+        """
+        Set the start time for querying bars.
+
+        :param start_time: Timestamp in milliseconds (Long).
+        """
+        if start_time is not None:
+            self.add_body_params("start_time", start_time)
+
+    def set_end_time(self, end_time):
+        """
+        Set the end time for querying bars. Delayed permission will auto-offset time.
+
+        :param end_time: Timestamp in milliseconds (Long).
+        """
+        if end_time is not None:
+            self.add_body_params("end_time", end_time)

webull/data/request/get_company_profile_request.py

@@ -0,0 +1,38 @@
+# 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.request import ApiRequest
+
+
+class GetCompanyProfileRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/instrument/company/profile", version="v2", method="GET", query_params={})
+
+    def set_symbol(self, symbol):
+        """
+        Set the security symbol.
+
+        :param symbol: Security symbol, e.g., AAPL
+        """
+        self.add_query_param("symbol", symbol)
+
+    def set_category(self, category):
+        """
+        Set the security type.
+
+        :param category: Security type. Possible values: US_STOCK
+        """
+        self.add_query_param("category", category)

webull/data/request/get_futures_instruments_request.py

@@ -29,3 +29,9 @@ class GetFuturesInstrumentsRequest(ApiRequest):
 
     def set_category(self, category):
         self.add_query_param("category", category)
+
+    def set_code(self, code):
+        self.add_query_param("code", code)
+
+    def set_status(self, status):
+        self.add_query_param("status", status)

webull/data/request/get_futures_product_class.py

@@ -0,0 +1,24 @@
+# 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.request import ApiRequest
+
+class GetFuturesProductClassRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/instrument/futures/product-classes", version='v2', method="GET", query_params={})
+
+    def set_category(self, category):
+        self.add_query_param("category", category)

webull/data/request/get_futures_products_request.py

@@ -23,3 +23,6 @@ class GetFuturesProductsRequest(ApiRequest):
 
     def set_category(self, category):
         self.add_query_param("category", category)
+
+    def set_product_class_id(self, product_class_id):
+        self.add_query_param("product_class_id", product_class_id)

webull/data/request/get_historical_bars_request.py

@@ -41,3 +41,21 @@ class GetHistoricalBarsRequest(ApiRequest):
                 self.add_query_param("trading_sessions", ','.join(trading_sessions))
             else:
                 self.add_query_param("trading_sessions", trading_sessions)
+
+    def set_start_time(self, start_time):
+        """
+        Set the start time for querying bars.
+
+        :param start_time: Timestamp in milliseconds (Long).
+        """
+        if start_time is not None:
+            self.add_query_param("start_time", start_time)
+
+    def set_end_time(self, end_time):
+        """
+        Set the end time for querying bars. Delayed permission will auto-offset time.
+
+        :param end_time: Timestamp in milliseconds (Long).
+        """
+        if end_time is not None:
+            self.add_query_param("end_time", end_time)

webull/data/request/get_noii_bars_request.py

@@ -0,0 +1,55 @@
+# 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.request import ApiRequest
+
+
+class GetNoiiBarsRequest(ApiRequest):
+    """
+    Request class for Stock NOII Bars API.
+    
+    NOII (Net Order Imbalance Indicator) data provides insight into market supply
+    and demand during NASDAQ opening and closing auctions.
+    """
+
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/market-data/stock/noii/bars", version="v2", method="GET", query_params={})
+
+    def set_symbol(self, symbol):
+        """
+        Set the security symbol. Only single symbol query is supported.
+
+        :param symbol: Security symbol, e.g., AAPL
+        """
+        self.add_query_param("symbol", symbol)
+
+    def set_category(self, category):
+        """
+        Set the security category. Currently only US_STOCK is supported.
+
+        :param category: Security category, e.g., US_STOCK
+        """
+        self.add_query_param("category", category)
+
+    def set_imbalance_action_type(self, imbalance_action_type):
+        """
+        Set the imbalance action type.
+
+        :param imbalance_action_type: Imbalance action type.
+            - PRE_OPEN: Opening imbalance
+            - PRE_CLOSE: Closing imbalance
+        """
+        self.add_query_param("imbalance_action_type", imbalance_action_type)

webull/data/request/get_noii_snapshot_request.py

@@ -0,0 +1,59 @@
+# 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.request import ApiRequest
+
+
+class GetNoiiSnapshotRequest(ApiRequest):
+    """
+    Request class for Stock NOII Snapshot API.
+    
+    Provides the latest NOII snapshot during US stock auction phases (opening/closing).
+    NOII data is published only during call auction periods and updates 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.
+    """
+
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/market-data/stock/noii/snapshot", version="v2", method="GET", query_params={})
+
+    def set_symbol(self, symbol):
+        """
+        Set the security symbol. Only single symbol query is supported.
+
+        :param symbol: Security symbol, e.g., AAPL
+        """
+        self.add_query_param("symbol", symbol)
+
+    def set_category(self, category):
+        """
+        Set the security category. Currently only US_STOCK is supported.
+
+        :param category: Security category, e.g., US_STOCK
+        """
+        self.add_query_param("category", category)
+
+    def set_imbalance_action_type(self, imbalance_action_type):
+        """
+        Set the imbalance action type.
+
+        :param imbalance_action_type: Imbalance action type.
+            - PRE_OPEN: Opening imbalance
+            - PRE_CLOSE: Closing imbalance
+        """
+        self.add_query_param("imbalance_action_type", imbalance_action_type)

webull/data/request/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