Merge branch 'main_merge_260808' into 'main'

[20260808日常发布]: 【Market Data API】Instrument接口优化(增加标的sub_category) (link)

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

Author: 方佳

samples/__init__.py

@@ -1 +1 @@
-__version__ = '2.0.16'
+__version__ = '2.0.17'

samples/trade/trade_client_v3.py

@@ -60,6 +60,17 @@
     # ============================================================
 
     # normal equity order
+    # normal equity order
+    # leg_in_or_out: Currently, only the US market is supported.
+    #   Specifies whether this order is adding or removing a leg from an existing position.
+    #   LEG_IN: Add this leg to an existing position to form a multi-leg strategy.
+    #   LEG_OUT: Close this leg from an existing multi-leg strategy position.
+    # position_id: Currently, only the US market is supported.
+    #   The unique position identifier of the target leg. Obtained from the Account Positions API.
+    #   Required when leg_in_or_out is specified.
+    # leg_in_strategy: Currently, only the US market is supported.
+    #   The target strategy type expected after legging in. Only applicable when leg_in_or_out is LEG_IN.
+    #   (e.g., VERTICAL, CALENDAR, STRANGLE, STRADDLE, IRON_CONDOR, BUTTERFLY, CUSTOM).
     normal_equity_client_order_id = uuid.uuid4().hex
     print('client order id:', normal_equity_client_order_id)
     new_normal_equity_orders = [
@@ -76,6 +87,9 @@
             "side": "BUY",
             "time_in_force": "DAY",
             "entrust_type": "QTY",
+            "leg_in_or_out": "LEG_IN",
+            "position_id": "<your_position_id>",
+            "leg_in_strategy": "VERTICAL",
             # Currently, only Webull JP is supported.
             # "account_tax_type":"GENERAL",
             # "margin_type": "ONE_DAY"
@@ -119,6 +133,9 @@
     if res.status_code == 200:
         print('get order detail res:', res.json())
 
+    res = trade_client.order_v3.get_order_executions(account_id, client_order_id= "", start_date="2026-01-20", end_date="2026-01-23")
+    if res.status_code == 200:
+        print('get order executions res:', res.json())
 
 
     # combo equity order
@@ -257,6 +274,15 @@
 
     # normal option order
     # position_intent: Currently, only the US market is supported, and only options orders are allowed.
+    # leg_in_or_out: Currently, only the US market is supported.
+    #   Specifies whether this leg is being legged into or legged out of an existing position.
+    #   LEG_IN: Add this leg to an existing position.
+    #   LEG_OUT: Close this leg from an existing multi-leg strategy position.
+    # position_id: Currently, only the US market is supported.
+    #   The unique position identifier of the target leg to be legged in or legged out. Obtained from the Account Positions API. Required when leg_in_or_out is specified.
+    # leg_in_strategy: Currently, only the US market is supported.
+    #   The target strategy type expected after legging in. Specifies what multi-leg strategy the position should become once this leg is added. Only applicable when leg_in_or_out is LEG_IN.
+    #   (e.g., VERTICAL, CALENDAR, STRANGLE, STRADDLE, IRON_CONDOR, BUTTERFLY, CUSTOM).
     normal_option_client_order_id = uuid.uuid4().hex
     new_normal_option_orders = [
         {
@@ -270,6 +296,9 @@
             "time_in_force": "GTC",
             "entrust_type": "QTY",
             "position_intent": "BUY_TO_OPEN",
+            "leg_in_or_out": "LEG_IN",
+            "position_id": "<your_position_id>",
+            "leg_in_strategy": "VERTICAL",
             "legs": [
                 {
                     "side": "BUY",

tests/trade/request/v2/test_get_order_executions.py

@@ -0,0 +1,48 @@
+# 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.
+import json
+import unittest
+
+from webull.core.client import ApiClient
+from webull.core.exception.exceptions import ServerException
+from webull.core.http.initializer.client_initializer import ClientInitializer
+from webull.trade.request.v2.get_order_executions_request import GetOrderExecutionsRequest
+
+optional_api_endpoint = "<api_endpoint>"
+your_app_key = "<your_app_key>"
+your_app_secret = "<your_app_secret>"
+region_id = "<region_id>"
+account_id = "<your_account_id>"
+api_client = ApiClient(your_app_key, your_app_secret, region_id)
+api_client.add_endpoint(region_id, optional_api_endpoint)
+ClientInitializer.initializer(api_client)
+
+
+class TestGetOrderExecutions(unittest.TestCase):
+    def test_get_order_executions(self):
+        request = GetOrderExecutionsRequest()
+        request.set_endpoint(optional_api_endpoint)
+        request.set_account_id(account_id)
+        request.set_client_order_id("")
+        request.set_start_date("2024-01-01")
+        request.set_end_date("2024-01-31")
+        request.set_page_size(10)
+        params = request.get_query_params()
+        print(params)
+        try:
+            response = api_client.get_response(request)
+            print(json.dumps(response.json(), indent=4))
+
+        except ServerException as se:
+            print(se.get_error_code(), ":", se.get_error_msg())

webull/__init__.py

@@ -1 +1 @@
-__version__ = '2.0.16'
+__version__ = '2.0.17'

webull/core/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '2.0.16'
+__version__ = '2.0.17'
 
 import logging
 

webull/data/__init__.py

@@ -1,3 +1,3 @@
 # coding=utf-8
 
-__version__ = '2.0.16'
+__version__ = '2.0.17'

webull/data/quotes/instrument.py

@@ -32,21 +32,23 @@ class Instrument:
     def __init__(self, api_client):
         self.client = api_client
 
-    def get_instrument(self, symbols=None, category=Category.US_STOCK.name, status=None, last_instrument_id=None,
-                       page_size=1000):
+    def get_instrument(self, symbols=None, category=Category.US_STOCK.name, status=None, sub_category=None,
+                       last_instrument_id=None, page_size=1000):
         """
          Query the underlying information according to the security symbol list and security type.
 
         :param symbols: Securities symbol, such as: 00700,00981.
         :param category: Security type, enumeration.
         :param status: Tradable status.
+        :param sub_category: Security sub category.
         :param last_instrument_id: Last instrument id for pagination.
         :param page_size: Page size, default 1000.
         """
         instruments_request = GetInstrumentsRequest()
         instruments_request.set_symbols(symbols)
         instruments_request.set_category(category)
         instruments_request.set_status(status)
+        instruments_request.set_sub_category(sub_category)
         instruments_request.set_last_instrument_id(last_instrument_id)
         instruments_request.set_page_size(page_size)
         response = self.client.get_response(instruments_request)

webull/data/request/get_instruments_request.py

@@ -33,6 +33,10 @@ def set_status(self, status):
         if status:
             self.add_query_param("status", status)
 
+    def set_sub_category(self, sub_category):
+        if sub_category:
+            self.add_query_param("sub_category", sub_category)
+
     def set_last_instrument_id(self, last_instrument_id):
         if last_instrument_id:
             self.add_query_param("last_instrument_id", last_instrument_id)

webull/trade/__init__.py

@@ -1 +1 @@
-__version__ = '2.0.16'
+__version__ = '2.0.17'

webull/trade/request/v2/get_order_executions_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.
+
+from webull.core.request import ApiRequest
+
+
+class GetOrderExecutionsRequest(ApiRequest):
+    def __init__(self):
+        ApiRequest.__init__(self, "/trading/orders/executions/list", version='v2', method="GET", query_params={})
+
+    def set_account_id(self, account_id):
+        self.add_query_param("account_id", account_id)
+
+    def set_client_order_id(self, client_order_id):
+        self.add_query_param("client_order_id", client_order_id)
+
+    def set_start_date(self, start_date):
+        self.add_query_param("start_date", start_date)
+
+    def set_end_date(self, end_date):
+        self.add_query_param("end_date", end_date)
+
+    def set_last_execution_id(self, last_execution_id):
+        self.add_query_param("last_execution_id", last_execution_id)
+
+    def set_page_size(self, page_size):
+        self.add_query_param("page_size", page_size)