Merge branch 'main_merge_261017' into 'main'

[API-1816]: add market data api and start_time and end_time for bars/list

See merge request webull/webull-openapi-python-sdk!48

Author: 方佳

samples/__init__.py

@@ -1 +1 @@
-__version__ = '3.0.3'
+__version__ = '3.0.4'

samples/data/data_client.py

@@ -59,6 +59,13 @@
     if res.status_code == 200:
         print('get_crypto_history_bar:', res.json())
 
+    # Crypto historical bars within a time range using start_time and end_time (timestamps in milliseconds).
+    res = data_client.crypto_market_data.get_crypto_history_bar(
+        "BTCUSD", Category.US_CRYPTO.name, Timespan.M1.name,
+        start_time=1711262998500, end_time=1711349398500)
+    if res.status_code == 200:
+        print('get_crypto_history_bar with time range:', res.json())
+
     res = data_client.market_data.get_snapshot('AAPL', Category.US_STOCK.name, extend_hour_required=True, overnight_required=True)
     if res.status_code == 200:
         print('get_snapshot:', res.json())
@@ -94,6 +101,13 @@
     if res.status_code == 200:
         print('get_futures_history_bars:', res.json())
 
+    # Futures historical bars within a time range using start_time and end_time (timestamps in milliseconds).
+    res = data_client.futures_market_data.get_futures_history_bars(
+        'SILZ5,6BM6', Category.US_FUTURES.name, Timespan.M1.name,
+        start_time=1711262998500, end_time=1711349398500)
+    if res.status_code == 200:
+        print('get_futures_history_bars with time range:', res.json())
+
     res = data_client.futures_market_data.get_futures_tick("SILZ5", Category.US_FUTURES.name, count=10)
     if res.status_code == 200:
         print('get_futures_tick:', res.json())
@@ -156,6 +170,13 @@
     if res.status_code == 200:
         print('get_option_history_bars:', res.json())
 
+    # Option historical bars within a time range using start_time and end_time (timestamps in milliseconds).
+    res = data_client.option_market_data.get_option_history_bars(
+        'AAPL260522C00300000', Category.US_OPTION.name, Timespan.M1.name,
+        start_time=1711262998500, end_time=1711349398500)
+    if res.status_code == 200:
+        print('get_option_history_bars with time range:', res.json())
+
     # Option market data - Tick
     # Rate limit: 60 requests per minute
     res = data_client.option_market_data.get_option_tick("AAPL260522C00300000", Category.US_OPTION.name, count=30)
@@ -292,3 +313,61 @@
     res = data_client.screener.get_52whl(Category.US_STOCK.name, rank_type="NEW_HIGH")
     if res.status_code == 200:
         print('get_52whl:', res.json())
+
+    # ==================== Screeners ====================
+    # Market sentiment (fear & greed) index
+    sentiment_res = data_client.screener.get_fear_and_greed_index(Category.US_STOCK.name)
+    if sentiment_res.status_code == 200:
+        print('get_fear_and_greed_index:', sentiment_res.json())
+
+    # Stock unusual activities
+    unusual_res = data_client.screener.get_stock_unusual_activities("NVDA", Category.US_STOCK.name, count=10)
+    if unusual_res.status_code == 200:
+        print('get_stock_unusual_activities:', unusual_res.json())
+
+    # ==================== Fundamentals ====================
+    # Macro economic calendar
+    calendar_res = data_client.fundamentals.get_economic_calendars("US", "2026-09-01", "2026-09-08")
+    if calendar_res.status_code == 200:
+        print('get_economic_calendars:', calendar_res.json())
+
+    # Institution search -> 13F holdings -> holding changes
+    institutions_res = data_client.fundamentals.get_institution_search("Bridgewater")
+    if institutions_res.status_code == 200:
+        print('get_institution_search:', institutions_res.json())
+
+    holdings_res = data_client.fundamentals.get_institution_holdings("0001738828")
+    if holdings_res.status_code == 200:
+        print('get_institution_holdings:', holdings_res.json())
+
+    holding_changes_res = data_client.fundamentals.get_institution_holding_changes("0001738828", "OPEN", count=10)
+    if holding_changes_res.status_code == 200:
+        print('get_institution_holding_changes:', holding_changes_res.json())
+
+    # Insider transactions and holdings overview
+    insider_tx_res = data_client.fundamentals.get_insider_transactions("NVDA", Category.US_STOCK.name)
+    if insider_tx_res.status_code == 200:
+        print('get_insider_transactions:', insider_tx_res.json())
+
+    insider_overview_res = data_client.fundamentals.get_insider_holdings(
+        "NVDA", Category.US_STOCK.name, compare_months=1)
+    if insider_overview_res.status_code == 200:
+        print('get_insider_holdings:', insider_overview_res.json())
+
+    # ==================== News ====================
+    # Search news by keyword
+    search_news_res = data_client.news.get_news_search("Starlink")
+    if search_news_res.status_code == 200:
+        print('get_news_search:', search_news_res.json())
+
+    # Stock news list
+    stock_news_res = data_client.news.get_stock_news("TSLA", Category.US_STOCK.name)
+    if stock_news_res.status_code == 200:
+        print('get_stock_news:', stock_news_res.json())
+
+    # News detail (use a news_id returned by the list/search APIs)
+    news_items = (stock_news_res.json().get('data') or []) if stock_news_res.status_code == 200 else []
+    if news_items:
+        news_detail_res = data_client.news.get_news_detail(news_items[0].get('news_id'))
+        if news_detail_res.status_code == 200:
+            print('get_news_detail:', news_detail_res.json())

samples/data/data_client_event.py

@@ -64,6 +64,13 @@
     if res.status_code == 200:
         print('get_event_bars:', res.json())
 
+    # Query bars within a time range using start_time and end_time (timestamps in milliseconds).
+    res = data_client.event_market_data.get_event_bars(
+        "KXRATECUTCOUNT-25DEC31-T10", Timespan.M1, Category.US_EVENT.name, 200, False,
+        start_time=1711262998500, end_time=1711349398500)
+    if res.status_code == 200:
+        print('get_event_bars with time range:', res.json())
+
     res = data_client.event_market_data.get_event_tick("KXRATECUTCOUNT-25DEC31-T10", Category.US_EVENT.name, 30)
     if res.status_code == 200:
         print('get_event_tick:', res.json())

webull/__init__.py

@@ -1 +1 @@
-__version__ = '3.0.3'
+__version__ = '3.0.4'

webull/core/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '3.0.3'
+__version__ = '3.0.4'
 
 import logging
 

webull/data/__init__.py

@@ -1,3 +1,3 @@
 # coding=utf-8
 
-__version__ = '3.0.3'
+__version__ = '3.0.4'

webull/data/data_client.py

@@ -27,6 +27,7 @@
 from webull.data.quotes.fundamentals import Fundamentals
 from webull.data.quotes.screener import Screener
 from webull.data.quotes.watchlist import Watchlist
+from webull.data.quotes.news import News
 from webull.data.quotes.community import Community
 
 
@@ -44,6 +45,7 @@ def __init__(self, api_client):
         self.screener = Screener(api_client)
         self.watchlist = Watchlist(api_client)
         self.community = Community(api_client)
+        self.news = News(api_client)
 
     def _init_logger(self, api_client):
         # No logger configured, using default console and local file logging.

webull/data/quotes/crypto_market_data.py

@@ -20,7 +20,8 @@ class CryptoMarketData:
     def __init__(self, api_client):
         self.client = api_client
 
-    def get_crypto_history_bar(self, symbols, category, timespan, count='200', real_time_required=None):
+    def get_crypto_history_bar(self, symbols, category, timespan, count='200', real_time_required=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.
@@ -33,13 +34,17 @@ def get_crypto_history_bar(self, symbols, category, timespan, count='200', real_
         :param count: The number of lines: the default is 200, and the maximum limit is 1200
         :param real_time_required: Returns the latest trade quote data. By default, the most recent market data is returned.
         By default, only intraday candlestick data is returned.
+        :param start_time: Optional start time as a timestamp in milliseconds, used to specify the beginning of the time range for bar data.
+        :param end_time: Optional end time as a timestamp in milliseconds, used to specify the end of the time range for bar data.
         """
         crypto_history_bar_request = GetCryptoHistoricalBarsRequest()
         crypto_history_bar_request.set_symbols(symbols)
         crypto_history_bar_request.set_category(category)
         crypto_history_bar_request.set_timespan(timespan)
         crypto_history_bar_request.set_count(count)
         crypto_history_bar_request.set_real_time_required(real_time_required)
+        crypto_history_bar_request.set_start_time(start_time)
+        crypto_history_bar_request.set_end_time(end_time)
         response = self.client.get_response(crypto_history_bar_request)
         return response
 

webull/data/quotes/event_market_data.py

@@ -52,7 +52,8 @@ def get_event_depth(self, symbol, category=Category.US_EVENT.name, depth=10):
         response = self.client.get_response(quote_request)
         return response
 
-    def get_event_bars(self, symbols, timespan, category=Category.US_EVENT.name, count=200, real_time_required=False):
+    def get_event_bars(self, symbols, timespan, category=Category.US_EVENT.name, count=200, real_time_required=False,
+                       start_time=None, end_time=None):
         """
         Get the current order book for a specific event instrument.
         The order book shows all active bid orders for both yes and no sides of a binary market.
@@ -63,13 +64,17 @@ def get_event_bars(self, symbols, timespan, category=Category.US_EVENT.name, cou
         :param category: default is US_EVENT, currently only US_EVENT is supported.
         :param count: Number of entries, default 200 entries, maximum 1200 entries.
         :param real_time_required: Does it include the latest data? The k-line that has not been finalized is not included by default. It is false and only used for minutes.
+        :param start_time: Optional start time as a timestamp in milliseconds, used to specify the beginning of the time range for bar data.
+        :param end_time: Optional end time as a timestamp in milliseconds, used to specify the end of the time range for bar data.
         """
         quote_request = GetEventBarsRequest()
         quote_request.set_symbols(symbols)
         quote_request.set_category(category)
         quote_request.set_timespan(timespan)
         quote_request.set_count(count)
         quote_request.set_real_time_required(real_time_required)
+        quote_request.set_start_time(start_time)
+        quote_request.set_end_time(end_time)
         response = self.client.get_response(quote_request)
         return response
 

webull/data/quotes/fundamentals.py

@@ -36,6 +36,12 @@
 from webull.data.request.get_financials_balance_sheet_request import GetFinancialsBalanceSheetRequest
 from webull.data.request.get_financials_alert_request import GetFinancialsAlertRequest
 from webull.data.request.get_forecast_eps_request import GetForecastEpsRequest
+from webull.data.request.get_institution_search_request import GetInstitutionSearchRequest
+from webull.data.request.get_institution_holdings_request import GetInstitutionHoldingsRequest
+from webull.data.request.get_institution_holding_changes_request import GetInstitutionHoldingChangesRequest
+from webull.data.request.get_insider_transactions_request import GetInsiderTransactionsRequest
+from webull.data.request.get_insider_holdings_request import GetInsiderHoldingsRequest
+from webull.data.request.get_economic_calendar_request import GetEconomicCalendarRequest
 
 
 class Fundamentals:
@@ -352,3 +358,96 @@ def get_forecast_eps(self, symbol, category=Category.US_STOCK.name):
         request.set_category(category)
         response = self.client.get_response(request)
         return response
+
+    def get_institution_search(self, keyword, pagination_key=None):
+        """
+        Search US institutional investors by name or SEC CIK number. US only.
+
+        :param keyword: Search keyword (institution name or CIK), required.
+        :param pagination_key: Pagination key from the previous page response; not returned on the last page.
+        """
+        request = GetInstitutionSearchRequest()
+        request.set_keyword(keyword)
+        request.set_pagination_key(pagination_key)
+        response = self.client.get_response(request)
+        return response
+
+    def get_institution_holdings(self, cik, pagination_key=None):
+        """
+        Query a US institution's 13F holdings. US only.
+
+        :param cik: Institution CIK number, required.
+        :param pagination_key: Pagination key from the previous page response; not returned on the last page.
+        """
+        request = GetInstitutionHoldingsRequest()
+        request.set_cik(cik)
+        request.set_pagination_key(pagination_key)
+        response = self.client.get_response(request)
+        return response
+
+    def get_institution_holding_changes(self, cik, position, count=None, pagination_key=None):
+        """
+        Query US institutional holding changes filtered by position type. US only.
+
+        :param cik: Fund CIK number, required.
+        :param position: Position type: OPEN, CLOSE, or CHANGE, required.
+        :param count: Page size, optional, default 10, max 50.
+        :param pagination_key: Pagination key from the previous page response; not returned on the last page.
+        """
+        request = GetInstitutionHoldingChangesRequest()
+        request.set_cik(cik)
+        request.set_position(position)
+        request.set_count(count)
+        request.set_pagination_key(pagination_key)
+        response = self.client.get_response(request)
+        return response
+
+    def get_insider_transactions(self, symbol, category=Category.US_STOCK.name, side=None, pagination_key=None):
+        """
+        Query insider transaction records for a stock.
+
+        :param symbol: Stock symbol, e.g. NVDA, required.
+        :param category: Market category. Supported: US_STOCK (default), HK_STOCK.
+        :param side: Transaction side filter: BUY or SELL, None to return all.
+        :param pagination_key: Pagination key from the previous page response; not returned on the last page.
+        """
+        request = GetInsiderTransactionsRequest()
+        request.set_symbol(symbol)
+        request.set_category(category)
+        request.set_side(side)
+        request.set_pagination_key(pagination_key)
+        response = self.client.get_response(request)
+        return response
+
+    def get_insider_holdings(self, symbol, category=Category.US_STOCK.name, compare_months=None):
+        """
+        Query the insider ownership statistics overview for a stock.
+
+        :param symbol: Stock symbol, e.g. NVDA, required.
+        :param category: Market category. Supported: US_STOCK (default), HK_STOCK.
+        :param compare_months: Comparison period in months: 1 (default) or 3.
+        """
+        request = GetInsiderHoldingsRequest()
+        request.set_symbol(symbol)
+        request.set_category(category)
+        request.set_compare_months(compare_months)
+        response = self.client.get_response(request)
+        return response
+
+    def get_economic_calendars(self, region=None, start_date=None, end_date=None, pagination_key=None):
+        """
+        Query the macroeconomic event calendar for an optional region and date range.
+        Results are cursor-paginated, up to 30 events per page.
+
+        :param region: Region code: US (default), CN, EU, JP, GB.
+        :param start_date: Start date in yyyy-MM-dd format, None defaults to today.
+        :param end_date: End date in yyyy-MM-dd format, None defaults to start date + 7 days.
+        :param pagination_key: Pagination key from the previous page response; not returned on the last page.
+        """
+        request = GetEconomicCalendarRequest()
+        request.set_region(region)
+        request.set_start_date(start_date)
+        request.set_end_date(end_date)
+        request.set_pagination_key(pagination_key)
+        response = self.client.get_response(request)
+        return response