Skip to main content

Getting Started

This is a quick guide to help you access market data via API. The guide covers the following topics: installing the Webull SDK, obtaining API keys, and how to request historical and real-time market data.

1. Install the Webull Client SDK​

Requirements​

First, please generate your App Key and App Secret:

  • For individual users, please see here.
  • For institutional users, please see here.

Python version 3.8 through 3.11 is required.

SDK Installation​

Install via pip

pip3 install --upgrade webull-openapi-python-sdk

2. Generate API Keys and Authenticate​

Each API call requires authentication based on the App Key and a signature generated using the App Secret. The client must include the App Key and the signature value in the HTTP request headers named x-app-key and x-signature, respectively.

Note

To comply with Hong Kong security and regulatory requirements, in addition to App Key and signature authentication, OpenAPI also requires Token authentication. For details on how to create and verify tokens, please refer to Token Creation and Verification.

3. Request Market Data via SDK​

After installing the SDK and obtaining your API keys, you can use the Market Data API. The following example demonstrates how to request candlestick bars data. For other types of data, please refer to the Market Data API Reference Documentation.

Requesting Historical Data: Example with candlestick bars Data​

from webull.data.common.category import Category
from webull.data.common.timespan import Timespan
from webull.core.client import ApiClient
from webull.data.data_client import DataClient

optional_api_endpoint = "<api_endpoint>"
your_app_key = "<your_app_key>"
your_app_secret = "<your_app_secret>"
region_id = "<region_id>"
api_client = ApiClient(your_app_key, your_app_secret, region_id)
api_client.add_endpoint(region_id, optional_api_endpoint)

if __name__ == '__main__':
    data_client = DataClient(api_client)

    res = data_client.market_data.get_history_bar('AAPL', Category.US_STOCK.name, Timespan.M1.name)
    if res.status_code == 200:
        print('get_history_bar:', res.json())
        
    res = data_client.market_data.get_batch_history_bar(['AAPL', 'TSLA'], Category.US_STOCK.name, Timespan.M1.name, 1)
    if res.status_code == 200:
        print('get_batch_history_bar:', res.json())

The following example demonstrates how to use the SDK to retrieve real-time quote data push. If you prefer not to use the SDK, please refer to the Data Streaming API。

Example for Retrieving Real-Time Quote Push​

from webull.data.common.category import Category
from webull.data.common.subscribe_type import SubscribeType
from webull.data.data_streaming_client import DataStreamingClient


your_app_key = "<your_app_key>"
your_app_secret = "<your_app_secret>"
optional_api_endpoint = "api.sandbox.webull.hk"
optional_quotes_endpoint = "data-api.sandbox.webull.hk"
region_id = "<region_id>"

session_id = "demo_session_1"
data_streaming_client = DataStreamingClient(your_app_key, your_app_secret, region_id, session_id,
                                    http_host=optional_api_endpoint,
                                    mqtt_host=optional_quotes_endpoint)

if __name__ == '__main__':
    def my_connect_success_func(client, api_client,session_id):
        print("connect success with session_id:%s" % client.get_session_id())

        symbols = ['AAPL']
        sub_types = [SubscribeType.QUOTE.name, SubscribeType.SNAPSHOT.name, SubscribeType.TICK.name]
        client.subscribe(symbols, Category.US_STOCK.name, sub_types)


    def my_quotes_message_func(client, topic, quotes):
        print("receive message: topic:%s, quotes:%s" % (topic, quotes))


    def my_subscribe_success_func(client, api_client,session_id):
        print("subscribe success with session_id:%s" % client.get_session_id())


    # set connect success callback func
    data_streaming_client.on_connect_success = my_connect_success_func
    # set quotes receiving callback func
    data_streaming_client.on_quotes_message = my_quotes_message_func
    # set subscribe success callback func
    data_streaming_client.on_subscribe_success = my_subscribe_success_func
    # the sync mode, blocking in current thread
    data_streaming_client.connect_and_loop_forever()