Skip to main content

Subscribe Trade Events

Interface Description​

Trade events subscription is a server streaming persistent connection implemented based on gRPC, which is suitable for connecting Webull customers through the OpenAPI development platform. The trade events subscription fully follows the gRPC open source protocol, and you can refer to the gRPC open source library when using it.

Currently, the interface supports order status change message push, and the supported scenarios are as follows:

scene_typeDescription
FILLEDPartially filled
FINAL_FILLEDAll filled
PLACE_FAILEDOrder failed
MODIFY_SUCCESSChange order successfully
MODIFY_FAILEDChange order failed
CANCEL_SUCCESSCancellation succeeded
CANCEL_FAILEDCancellation failed

Trade events subscribe Proto protocol definition.​

Request Proto

message SubscribeRequest {
	 uint32 subscribeType = 1; // Subscription type
	 int64 timestamp = 2; // Timestamp
	 string contentType = 3; // Content type
	 string payload = 4; // Content
	 repeated string accounts = 5; // Account ID
}

Response Proto

message SubscribeResponse {
	 EventType eventType = 1; // Event type
	 uint32 subscribeType = 2; // Subscription type
	 string contentType = 3; // Subscription type
	 string payload = 4; // Content
	 string requestId = 5; // Request id
	 int64  timestamp = 6; // Timestamp
}

EventType enumeration

enum EventType {
	SubscribeSuccess = 0; // Subscription succeeded
	Ping = 1; // Heartbeat information
	AuthError = 2; // Authentication error
	NumOfConnExceed = 3; // Connection limit exceeded
	SubscribeExpired = 4; // Subscription expired
}

Request Example​

When using sdk request, subscribeType, timestamp, contentType, and payload can be ignored. Just pass in the accounts. subscribeType currently only supports =1. In the following case, the _on_log method is used to output the log. The my_on_events_message method is to receive order status change messages.

import logging

from webull.trade.events.types import ORDER_STATUS_CHANGED, EVENT_TYPE_ORDER
from webull.trade.trade_events_client import TradeEventsClient

your_app_key = "<your_app_key>"
your_app_secret = "<your_app_secret>"
account_id = "<your_account_id>"
region_id = "<region_id>"

optional_api_endpoint = "<event_api_endpoint>"


def _on_log(level, log_content):
    print(logging.getLevelName(level), log_content)


def my_on_events_message(event_type, subscribe_type, payload, raw_message):
    if EVENT_TYPE_ORDER == event_type and ORDER_STATUS_CHANGED == subscribe_type:
        print('%s' % payload)

if __name__ == '__main__':

    # Create EventsClient instance
    trade_events_client = TradeEventsClient(your_app_key, your_app_secret, region_id)
    # 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
    # trade_events_client = TradeEventsClient(your_app_key, your_app_secret, region_id, host=optional_api_endpoint)
    trade_events_client.on_log = _on_log

    # Set the callback function when the event data is received.
    # The data of order status change is printed here

    trade_events_client.on_events_message = my_on_events_message
    # Set the account ID to be subscribed and initiate the subscription. This method is synchronous
    trade_events_client.do_subscribe([account_id])

Response Example​

Transaction event scene type

{
    "request_id": "1045473299175309312",
    "account_id": "4MHSOMIJ88O7E80VBG0O4G6E9A",
    "client_order_id": "5783758dc6c240c6811c0cbea60c72d8",
    "instrument_id": "913256135",
    "order_status": "SUBMITTED",
    "symbol": "AAPL",
    "qty": "10.00",
    "filled_price": "180.00",
    "filled_qty": "1.00",
    "filled_time": "2025-11-21T06:23:28.601+0000",
    "side": "BUY",
    "scene_type": "FILLED",
    "category": "US_STOCK",
    "order_type": "LIMIT"
}
DEBUG response:eventType: Ping
subscribeType: 1
contentType: "text/plain"
requestId: "486daa2d-7be8-438f-b7fa-ecafa3d0e89f"
timestamp: 1763706218682