Merge branch 'main_merge_0508' into 'main'

feat: Support for Webull Hong Kong Institutional Clients.

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

Author: 方佳

webull-python-sdk-core/webullsdkcore/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.11"
+__version__ = "0.1.12"
 
 import logging
 

webull-python-sdk-core/webullsdkcore/client.py

@@ -45,8 +45,10 @@
 import platform
 import json
 from webullsdkcore import compat
+from webullsdkcore.common.customer_type import CustomerType
 from webullsdkcore.exception import error_code
 from webullsdkcore.exception.exceptions import ClientException, ServerException
+from webullsdkcore.headers import WB_USER_ID
 from webullsdkcore.retry.retry_policy_context import RetryPolicyContext
 from webullsdkcore.vendored.requests import codes
 from webullsdkcore.vendored.requests.adapters import HTTPAdapter
@@ -79,19 +81,22 @@ def __init__(
         app_secret=None,
         region_id=DEFAULT_REGION_ID,
         user_agent=None,
-        port=DEFAULT_PORT, 
+        port=DEFAULT_PORT,
+        customer_type=CustomerType.INDIVIDUAL,
         connect_timeout=None,
         timeout=None,
         credential=None,
         verify=None,
         auto_retry=False,
-        max_retry_num=None
+        max_retry_num=None,
+        user_id=None
     ):
         self._app_key = app_key
         self._app_secret = app_secret
         self._region_id = region_id
         self._user_agent = user_agent
         self._port = port
+        self._customer_type = customer_type
         self._connect_timeout = connect_timeout
         self._read_timeout = timeout
         self._extra_user_agent = {}
@@ -105,6 +110,7 @@ def __init__(
         self._endpoint_resolver = DefaultEndpointResolver(self) 
         self._max_retry_num = max_retry_num
         self._auto_retry = auto_retry
+        self._user_id = user_id
         if self._auto_retry:
             self._retry_policy = retry_policy.get_default_retry_policy(self._max_retry_num)
         else:
@@ -125,6 +131,12 @@ def get_user_agent(self):
     def get_verify(self):
         return self._verify
 
+    def set_customer_type(self):
+        return self._customer_type
+
+    def set_user_id(self):
+        return self._user_id
+
     def set_user_agent(self, agent):
         """
         User agent set to client will overwrite the request setting.
@@ -237,6 +249,10 @@ def _implementation_of_do_action(self, request, signer=None):
         if not isinstance(request, BaseRequest):
             raise ClientException(error_code.SDK_INVALID_REQUEST)
         request.add_header('Accept-Encoding', 'gzip')
+
+        if self._user_id:
+            request.add_header(WB_USER_ID, self._user_id)
+
         if request.endpoint:
             endpoint = request.endpoint
         else:
@@ -320,7 +336,8 @@ def _get_request_connect_timeout(self, request):
 
     def _resolve_endpoint(self, request):
         resolve_request = ResolveEndpointRequest(
-            self._region_id
+            self._region_id,
+            self._customer_type
         )
         return self._endpoint_resolver.resolve(resolve_request)
 

webull-python-sdk-core/webullsdkcore/common/customer_type.py

@@ -0,0 +1,14 @@
+from enum import Enum
+from typing import Optional
+
+
+class CustomerType(Enum):
+    INSTITUTION = "institution"
+    INDIVIDUAL = "individual"
+
+    @classmethod
+    def of(cls, name: str) -> Optional['CustomerType']:
+        for item in cls:
+            if item.name == name:
+                return item
+        return None

webull-python-sdk-core/webullsdkcore/data/endpoints.json

@@ -3,19 +3,35 @@
     "regions": ["us", "hk", "jp"],
     "region_mapping": {
         "us": {
-            "api": "api.webull.com",
-            "quotes-api": "usquotes-api.webullfintech.com",
-            "events-api": "events-api.webull.com"
+            "individual": {
+                "api": "api.webull.com",
+                "quotes-api": "usquotes-api.webullfintech.com",
+                "events-api": "events-api.webull.com"
+            },
+            "institution": {
+                "api": "",
+                "quotes-api": "",
+                "events-api": ""
+            }
         },
         "hk": {
-            "api": "api.webull.hk",
-            "quotes-api": "quotes-api.webull.hk",
-            "events-api": "events-api.webull.hk"
+            "individual": {
+                "api": "api.webull.hk",
+                "quotes-api": "quotes-api.webull.hk",
+                "events-api": "events-api.webull.hk"
+            },
+            "institution": {
+                "api": "inst-api.webull.hk",
+                "quotes-api": "quotes-api.webull.hk",
+                "events-api": "events-inst-api.webull.hk"
+            }
         },
         "jp": {
-            "api": "api.webull.co.jp",
-            "quotes-api": "",
-            "events-api": "events-api.webull.co.jp"
+            "individual": {
+                "api": "api.webull.co.jp",
+                "quotes-api": "",
+                "events-api": "events-api.webull.co.jp"
+            }
         }
     }
 }

webull-python-sdk-core/webullsdkcore/endpoint/default_endpoint_resolver.py

@@ -45,11 +45,12 @@
 from webullsdkcore.endpoint.user_customized_endpoint_resolver import UserCustomizedEndpointResolver
 
 class DefaultEndpointResolver(EndpointResolver):
-    def __init__(self, client, user_config=None):
+    def __init__(self, customer_type, user_config=None):
+        self._customer_type = customer_type
         self._user_customized_endpoint_resolver = UserCustomizedEndpointResolver()
         endpoint_resolvers = [
             self._user_customized_endpoint_resolver,
-            LocalConfigRegionalEndpointResolver(user_config)
+            LocalConfigRegionalEndpointResolver(user_config, customer_type=self._customer_type)
         ] 
         self._resolver = ChainedEndpointResolver(endpoint_resolvers)
 

webull-python-sdk-core/webullsdkcore/endpoint/local_config_regional_endpoint_resolver.py

@@ -43,13 +43,15 @@
 import os
 import webullsdkcore
 from webullsdkcore.endpoint import EndpointResolver
+from webullsdkcore.common.customer_type import CustomerType
 
 ENDPOINT_JSON = os.path.join(os.path.dirname(webullsdkcore.__file__), "data", "endpoints.json")
 
 
 class LocalConfigRegionalEndpointResolver(EndpointResolver):
-    def __init__(self, config_json_str=None):
+    def __init__(self, config_json_str=None, customer_type=None):
         EndpointResolver.__init__(self)
+        self._customer_type = customer_type
         if config_json_str:
             obj = json.loads(config_json_str)
         else:
@@ -68,7 +70,12 @@ def resolve(self, request):
         if request.region_id:
             region_code_mapping = self._region_mapping.get(request.region_id)
         else:
-            region_code_mapping = self._region_code_mapping.get(self._default_region)
+            region_code_mapping = self._region_mapping.get(self._default_region)
+
         if region_code_mapping:
-            return region_code_mapping.get(request.api_type)
+            # Select the appropriate API endpoint based on client type
+            customer_type = self._customer_type.set_customer_type() if self._customer_type else CustomerType.INDIVIDUAL
+            customer_type_key = "institution" if customer_type.value == CustomerType.INSTITUTION.value else "individual"
+            customer_endpoints = region_code_mapping.get(customer_type_key, {})
+            return customer_endpoints.get(request.api_type)
         return None

webull-python-sdk-core/webullsdkcore/endpoint/resolver_endpoint_request.py

@@ -41,6 +41,7 @@
 
 from webullsdkcore.common.api_type import DEFAULT as HTTP_API_TYPE
 class ResolveEndpointRequest(object):
-    def __init__(self, region_id=None, api_type=HTTP_API_TYPE):
+    def __init__(self, region_id=None, customer_type=None, api_type=HTTP_API_TYPE):
         self.region_id = region_id
-        self.api_type = api_type
+        self.api_type = api_type
+        self.customer_type = customer_type

webull-python-sdk-core/webullsdkcore/headers.py

@@ -47,6 +47,7 @@
 NONCE = "x-signature-nonce"
 TIMESTAMP = "x-timestamp"
 VERSION = "x-version"
+WB_USER_ID = "wb-user-id"
 
 NATIVE_HOST = "Host"
 NATIVE_CONTENT_TYPE = "Content-Type"

webull-python-sdk-demos/setup.py

@@ -15,8 +15,8 @@
     LONG_DESCRIPTION = fp.read()
 
 requires = [
-    "webull-python-sdk-mdata==0.1.11",
-    "webull-python-sdk-trade==0.1.11"
+    "webull-python-sdk-mdata==0.1.12",
+    "webull-python-sdk-trade==0.1.12"
 ]
 
 setup_args = {

webull-python-sdk-demos/tests/events-core/test_subscribe.py

@@ -14,24 +14,25 @@
 
 import unittest
 
+from webullsdkcore.common.customer_type import CustomerType
 from webullsdktrade.events.types import ORDER_STATUS_CHANGED, EVENT_TYPE_ORDER
 from webullsdktradeeventscore.events_client import EventsClient
 
 your_app_key = "<your_app_key>"
 your_app_secret = "<your_app_secret>"
 account_id = "<your_account_id>"
 region_id = "hk"
+customer_type = CustomerType.INSTITUTION
 
 endpoint = "<event_api_endpoint>"
 
 
 class TestGrpcSubscribe(unittest.TestCase):
     def test_subscribe(self):
         # Create EventsClient instance
-        events_client = EventsClient(your_app_key, your_app_secret, region_id)
+        events_client = EventsClient(your_app_key, your_app_secret, region_id, customer_type=customer_type)
         # For non production environment, you need to set the domain name of the subscription service through eventsclient. For example, the domain name of the UAT environment is set here
-        events_client = EventsClient(your_app_key, your_app_secret, region_id,
-                                     host=endpoint)
+        # events_client = EventsClient(your_app_key, your_app_secret, region_id, host=endpoint, customer_type=customer_type)
 
         # Set the callback function when the event data is received.
         # The data of order status change is printed here