交易事件檢閱

接口說明

交易事件檢閱是基於grpc實現的Server Streaming長連接，適用於通過OpenApi開發平台對接Webull客戶。交易事件檢閱完全遵循grpc開源協議,您在使用時可以參考Python grpc開源庫。

目前接口支持訂單狀態變化消息推送，支持的場景類型如下：

場景類型	描述
PLACE_FAILED	下單失敗
MODIFY_SUCCESS	改單成功
MODIFY_FAILED	改單失敗
CANCEL_SUCCESS	撤單成功
CANCEL_FAILED	撤單失敗
FILLED	部分成交
FINAL_FILLED	全部成交

交易事件檢閱Proto協議定義

請求Proto

message SubscribeRequest {
     uint32 subscribeType = 1; // 訂閱類型
     int64 timestamp = 2; // 時間戳
     string contentType = 3; // 內容類型
     string payload = 4; // 內容
     repeated string accounts = 5; // 賬戶ID
}

響應Proto

message SubscribeResponse {
     EventType eventType = 1; // 事件類型
     uint32 subscribeType = 2; // 訂閱類型
     string contentType = 3; // 內容類型
     string payload = 4; // 內容
     string requestId = 5; // 請求ID
     int64  timestamp = 6; // 時間戳
}

EventType 枚舉

enum EventType {
    SubscribeSuccess = 0; // 訂閱成功
    Ping = 1; // 心跳信息
    AuthError = 2; // 認證錯誤
    NumOfConnExceed = 3; // 連接次數超出限制
    SubscribeExpired = 4; // 订阅过期
}

請求示例

Python

使用sdk請求時，subscribeType、timestamp、contentType、payload可以不用關注。只需要傳入accounts即可。 subscribeType目前僅支持=1。 以下案例中，_on_log方法是輸出日誌使用。 my_on_events_message方法是接受訂單狀態變化消息。

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.HK.value)
    client.on_log = _on_log
    client.on_events_message = my_on_events_message
    print("subscribe account", [account_id])
    client.do_subscribe([account_id])

Java

handleEventMessage方法接受訂單狀態變化消息。

import com.google.common.reflect.TypeToken;
import com.webull.openapi.common.Region;
import com.webull.openapi.example.config.Env;
import com.webull.openapi.logger.Logger;
import com.webull.openapi.logger.LoggerFactory;
import com.webull.openapi.serialize.JsonSerializer;
import com.webull.openapi.trade.events.subscribe.EventClient;
import com.webull.openapi.trade.events.subscribe.Subscription;
import com.webull.openapi.trade.events.subscribe.message.EventType;
import com.webull.openapi.trade.events.subscribe.message.SubscribeRequest;
import com.webull.openapi.trade.events.subscribe.message.SubscribeResponse;

import java.util.Map;

public class TradeEvents {

    private static final Logger logger = LoggerFactory.getLogger(TradeEvents.class);

    public static void main(String[] args) {
        try (EventClient client = EventClient.builder()
                .appKey(Env.APP_KEY)
                .appSecret(Env.APP_SECRET)
                .regionId(Region.hk.name())
                .onMessage(TradeEvents::handleEventMessage)
                .build()) {

            SubscribeRequest request = new SubscribeRequest("<your_account_id>");

            Subscription subscription = client.subscribe(request);
            subscription.blockingAwait();
        } catch (Exception ex) {
            logger.error("Subscribe trade events error", ex);
        }
    }

    private static void handleEventMessage(SubscribeResponse response) {
        if (SubscribeResponse.CONTENT_TYPE_JSON.equals(response.getContentType())) {
            Map<String, String> payload = JsonSerializer.fromJson(response.getPayload(),
                    new TypeToken<Map<String, String>>(){}.getType());
            if (EventType.Order.getCode() == response.getEventType() || EventType.Position.getCode() == response.getEventType()) {
                logger.info("----request_id:{}----", payload.get("request_id"));
                logger.info(payload.get("account_id"));
                logger.info(payload.get("client_order_id"));
                logger.info(payload.get("order_status"));
            }
        }
    }
}

訂閱成功響應示列

# 連接成功
subscribeType: 1
contentType: "text/plain"
payload: "344992976"
requestId: "c1d2e05d-6984-45d8-b69f-f5b674c19a01"
timestamp: 1663667365268

# eventType：Ping消息為心調信息，無需處理。
eventType: Ping
subscribeType: 1
contentType: "text/plain"
requestId: "c1d2e05d-6984-45d8-b69f-f5b674c19a01"
timestamp: 1663667385269

# 接收訂單變更消息
eventType: 1024
subscribeType: 1
contentType: "application/json"
payload: "{\"secAccountId\":18955861,\"requestId\":\"H2GIPOP8I0TPBREPCPDFDENO5B\",\"account_id\":\"MDJQ432JHNK60LFN3TO1JA83N9\",\"request_id\":\"47987108\",\"client_order_id\":\"6bf6bcfa365745a3bed44df29e00fb15\",\"instrument_id\":\"913256409\",\"order_status\":\"Cancelled\",\"symbol\":\"00700\",\"short_name\":\"TENCENT\",\"qty\":\"100.0\",\"filled_qty\":\"0.0\",\"side\":\"BUY\",\"scene_type\":\"CANCEL_SUCCESS\",\"category\":\"HK_STOCK\",\"order_type\":\"ENHANCED_LIMIT\"}"
requestId: "H2GIPOP8I0TPBREPCPDFDENO5B"
timestamp: 1663729830258

# my_on_events_message方法打印出來接收到訂單變更消息
----request_id:47987108----
MDJQ432JHNK60LFN3TO1JA83N9
6bf6bcfa365745a3bed44df29e00fb15
Cancelled