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
PLACE_FAILEDOrder failed
MODIFY_SUCCESSChange order successfully
MODIFY_FAILEDChange order failed
CANCEL_SUCCESSCancellation succeeded
CANCEL_FAILEDCancellation failed
FILLEDPartially filled
FINAL_FILLEDAll filled

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 webullsdktrade.events.types import ORDER_STATUS_CHANGED, EVENT_TYPE_ORDER
from webullsdktradeeventscore.events_client import EventsClient
from webullsdkcore.common.region import Region

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


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('----request_id:%s----' % payload['request_id'])
print(payload['account_id'])
print(payload['client_order_id'])
print(payload['order_status'])

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


if __name__ == '__main__':
client = EventsClient(your_app_key, your_app_secret, Region.US.value)
client.on_log = _on_log
client.on_events_message = my_on_events_message
print("subscribe account", [account_id])
client.do_subscribe([account_id])

Subscription Success Response List

# Connection succeeded
subscribeType: 1
contentType: "text/plain"
payload: "344992976"
requestId: "c1d2e05d-6984-45d8-b69f-f5b674c19a01"
timestamp: 1663667365268

# eventType: Ping messages are heart-tuned messages and do not need to be processed.
eventType: Ping
subscribeType: 1
contentType: "text/plain"
requestId: "c1d2e05d-6984-45d8-b69f-f5b674c19a01"
timestamp: 1663667385269

# Receive order change messages
eventType: 1024
subscribeType: 1
contentType: "application/json"
payload: "{\"secAccountId\":36078,\"requestId\":\"EFICDJ8JBK19D4FJR7T1Q3K329\",\"account_id\":\"MHJ6G99LSOBR17DLI5APV6T269\",\"request_id\":\"1671758942155\",\"client_order_id\":\"I5JMHJG8C0CJCJT0F17PKRRD89\",\"instrument_id\":\"913256135\",\"order_status\":\"SUBMITTED\",\"symbol\":\"AAPL\",\"qty\":\"100.0\",\"side\":\"BUY\",\"scene_type\":\"MODIFY_SUCCESS\",\"category\":\"US_STOCK\",\"order_type\":\"LIMIT\"}"
requestId: "EFICDJ8JBK19D4FJR7T1Q3K329"
timestamp: 1671758942155

# The my_on_events_message method prints out the received message of order changes.
----request_id:47987108----
MDJQ432JHNK60LFN3TO1JA83N9
6bf6bcfa365745a3bed44df29e00fb15
Cancelled