Merge branch 'main_260314_merge' into 'main'

feat: Support GTD ordering, add market interface to event contracts

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

Author: 方佳

samples/__init__.py

@@ -1 +1 @@
-__version__ = '2.0.0'
+__version__ = '2.0.1'

samples/data/data_client_event.py

@@ -11,6 +11,7 @@
 # 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.timespan import Timespan
 
 # coding=utf-8
 
@@ -35,11 +36,19 @@
 if __name__ == '__main__':
     data_client = DataClient(api_client)
 
+    res = data_client.instrument.get_event_categories()
+    if res.status_code == 200:
+        print('get_event_categories:', res.json())
+
     res = data_client.instrument.get_event_series("ECONOMICS")
     if res.status_code == 200:
         print('get_event_series:', res.json())
 
-    res = data_client.instrument.get_event_instrument("KXGDP")
+    res = data_client.instrument.get_event_events("KXRATECUTCOUNT")
+    if res.status_code == 200:
+        print('get_event_events:', res.json())
+
+    res = data_client.instrument.get_event_instrument("KXRATECUTCOUNT")
     if res.status_code == 200:
         print('get_event_instrument:', res.json())
 
@@ -49,4 +58,12 @@
 
     res = data_client.event_market_data.get_event_depth("KXRATECUTCOUNT-25DEC31-T10", Category.US_EVENT.name)
     if res.status_code == 200:
-        print('get_event_depth:', res.json())
+        print('get_event_depth:', res.json())
+
+    res = data_client.event_market_data.get_event_bars("KXRATECUTCOUNT-25DEC31-T10", Timespan.M1, Category.US_EVENT.name, 200, False)
+    if res.status_code == 200:
+        print('get_event_bars:', 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__ = '2.0.0'
+__version__ = '2.0.1'

webull/core/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '2.0.0'
+__version__ = '2.0.1'
 
 import logging
 

webull/data/__init__.py

@@ -1,3 +1,3 @@
 # coding=utf-8
 
-__version__ = '2.0.0'
+__version__ = '2.0.1'

webull/data/quotes/event_market_data.py

@@ -12,8 +12,11 @@
 # 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_event_bars_request import GetEventBarsRequest
 from webull.data.request.get_event_depth_request import GetEventDepthRequest
 from webull.data.request.get_event_snapshot_request import GetEventSnapshotRequest
+from webull.data.request.get_event_tick_request import GetEventTickRequest
+
 
 class EventMarketData:
     def __init__(self, api_client):
@@ -47,4 +50,43 @@ def get_event_depth(self, symbol, category=Category.US_EVENT.name, depth=10):
         quote_request.set_category(category)
         quote_request.set_depth(depth)
         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):
+        """
+        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.
+        It returns yes bids and no bids only (no asks are returned). Price unit is based on usd_cent.
+
+        :param symbols: Symbol of the event market, supports JSON array format, multiple symbols separated by commas; maximum 100 symbols per query.
+        :param timespan:K-line time granularity.
+        :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.
+        """
+        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)
+        response = self.client.get_response(quote_request)
+        return response
+
+
+    def get_event_tick(self, symbol, category=Category.US_EVENT.name, count=30):
+        """
+        Detailed transaction records, including transaction time, price, quantity,
+        and transaction direction. Data is sorted in reverse chronological order,
+        with the most recent transaction record first.
+
+        :param symbol:Symbol of the event market.
+        :param category: default is US_EVENT, currently only US_EVENT is supported.
+        :param count: Number of entries, default 30 entries, maximum 1200 entries.
+        """
+        quote_request = GetEventTickRequest()
+        quote_request.set_symbol(symbol)
+        quote_request.set_category(category)
+        quote_request.set_count(count)
+        response = self.client.get_response(quote_request)
         return response

webull/data/quotes/instrument.py

@@ -12,7 +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_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
 from webull.data.request.get_event_series_request import GetEventSeriesRequest
 from webull.data.request.get_instruments_request import GetInstrumentsRequest
 from webull.data.request.get_crypto_instruments_request import GetCryptoInstrumentsRequest
@@ -111,7 +113,15 @@ def get_futures_instrument_by_code(self, code, category, contract_type=None):
         response = self.client.get_response(futures_instrument_request)
         return response
 
-    def get_event_series(self, category, last_instrument_id=None, page_size=500):
+    def get_event_categories(self):
+        """
+        Query event contract categories
+        """
+        event_categories_request = GetEventCategoriesRequest()
+        response = self.client.get_response(event_categories_request)
+        return response
+
+    def get_event_series(self, category=None, symbols=None, last_series_id=None, page_size=500):
         """
         Retrieve multiple series with specified filters.
         A series represents a template for recurring events that follow the same format and rules (e.g., “Monthly Jobs Report” ).
@@ -120,30 +130,57 @@ def get_event_series(self, category, last_instrument_id=None, page_size=500):
         :param category: The category which this series belongs to.Allowed values:
                         ECONOMICS, FINANCIALS, POLITICS, ENTERTAINMENT, SCIENCE_TECHNOLOGY,
                         CLIMATE_WEATHER, TRANSPORTATION, CRYPTO, SPORTS
-        :param last_instrument_id: Last series id for pagination.
+        :param symbols: Symbol of the event series, supports JSON array format, multiple symbols separated by commas; maximum 100 symbols per query.
+        :param last_series_id: Last series id for pagination.
         :param page_size: Page size, default 500.
         """
 
         event_series_request = GetEventSeriesRequest()
-        event_series_request.set_category(category)
-        if last_instrument_id:
-            event_series_request.set_last_instrument_id(last_instrument_id)
+        if category:
+            event_series_request.set_category(category)
+        if symbols:
+            event_series_request.set_symbols(symbols)
+        if last_series_id:
+            event_series_request.set_last_series_id(last_series_id)
         event_series_request.set_page_size(page_size)
         response = self.client.get_response(event_series_request)
         return response
 
-    def get_event_instrument(self, series_symbol, expiration_date_after=None, last_instrument_id=None, page_size=500):
+    def get_event_events(self, series_symbol, symbols=None, status=None):
+        """
+        Query event contract events
+
+        :param series_symbol: Series Symbol that identifies this series.
+        :param symbols: Symbol of the event events, supports JSON array format, multiple symbols separated by commas; maximum 100 symbols per query.
+        :param status: Event status (optional, defaults to querying tradable/valid events).
+        """
+        event_events_request = GetEventEventsRequest()
+        event_events_request.set_series_symbol(series_symbol)
+        if symbols:
+            event_events_request.set_symbols(symbols)
+        if status:
+            event_events_request.set_status(status)
+        response = self.client.get_response(event_events_request)
+        return response
+
+    def get_event_instrument(self, series_symbol, event_symbol=None, symbols=None, expiration_date_after=None, last_instrument_id=None, page_size=500):
         """
         Retrieve profile information for event contract markets based on the series symbol.
 
         :param series_symbol: Symbol that identifies this series.
+        :param event_symbol: Symbol of the event events.
+        :param symbols: Symbol of the event market, supports JSON array format, multiple symbols separated by commas; maximum 100 symbols per query.
         :param expiration_date_after: Used to filter items whose expiration date is later than a specified date; the default selection is the current day (inclusive).
-        :param last_instrument_id: Last series id for pagination.
+        :param last_instrument_id: Last instrument id for pagination.
         :param page_size: Page size, default 500.
         """
 
         event_instrument_request = GetEventInstrumentRequest()
         event_instrument_request.set_series_symbol(series_symbol)
+        if event_symbol:
+            event_instrument_request.set_event_symbol(event_symbol)
+        if symbols:
+            event_instrument_request.set_symbols(symbols)
         if expiration_date_after:
             event_instrument_request.set_expiration_date_after(expiration_date_after)
         if last_instrument_id:

webull/data/request/get_event_bars_request.py

@@ -0,0 +1,43 @@
+# 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 GetEventBarsRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/market-data/event/bars", version='v2', method="GET", query_params={})
+
+    def set_symbols(self, symbols):
+        if isinstance(symbols, str):
+            self.add_query_param("symbols", symbols)
+        elif isinstance(symbols, list):
+            self.add_query_param("symbols", ",".join(symbols))
+
+    def set_category(self, category):
+        self.add_query_param("category", category)
+
+    def set_timespan(self, timespan):
+        if timespan:
+            self.add_query_param("timespan", timespan)
+
+    def set_count(self, count):
+        if count:
+            self.add_query_param("count", count)
+
+    def set_real_time_required(self, real_time_required):
+        if real_time_required:
+            self.add_query_param("real_time_required", real_time_required)

webull/data/request/get_event_events_request.py

@@ -0,0 +1,33 @@
+# 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 GetEventEventsRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/openapi/instrument/event/events", version='v2', method="GET", query_params={})
+
+    def set_series_symbol(self, series_symbol):
+        self.add_query_param("series_symbol", series_symbol)
+
+    def set_symbols(self, symbols):
+        if isinstance(symbols, str):
+            self.add_query_param("symbols", symbols)
+        elif isinstance(symbols, list):
+            self.add_query_param("symbols", ",".join(symbols))
+
+    def set_status(self, status):
+        self.add_query_param("status", status)

webull/data/request/get_event_instrument_request.py

@@ -23,6 +23,15 @@ def __init__(self):
     def set_series_symbol(self, series_symbol):
         self.add_query_param("series_symbol", series_symbol)
 
+    def set_event_symbol(self, event_symbol):
+        self.add_query_param("event_symbol", event_symbol)
+
+    def set_symbols(self, symbols):
+        if isinstance(symbols, str):
+            self.add_query_param("symbols", symbols)
+        elif isinstance(symbols, list):
+            self.add_query_param("symbols", ",".join(symbols))
+
     def set_expiration_date_after(self, expiration_date_after):
         self.add_query_param("expiration_date_after", expiration_date_after)