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​

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.

For information on how to obtain the App Key and App Secret, please refer to the Individual Application Process.

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_endpoint>"
optional_quotes_endpoint = "<data_api_endpoint>"
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()