The Event Object

All event types share the same basic structure, consisting of the following fields:

• eventId: A unique identifier for each event. It is recommended to store this field after receiving the event to facilitate troubleshooting.

• eventType: Each type of event has a corresponding eventType.

• payload: Contains the actual event data. The payload structure differs for each event type, as explained separately below.

• timestamp: The timestamp of when the event was generated.

{
    "eventId": "2d088fa9d029a8484cf294ef3657e27d",
    "eventType": "order.created",
    "payload": {
      ......
    },
    "timestamp": 1646381210
}

Order Event

Order events are generated when an order's status changes.

Major order statuses include:

When the order status is not Filled (it may be New, Canceled, Expired, or Rejected), a partial fill may still have occurred. This can be determined by checking whether the filled quantity is greater than 0.

{
    "eventId": "2d088fa9d029a8484cf294ef3657e27d",
    "eventType": "order.created",
    "payload": {
        "orderId": 25249862780060672,
        "uuid": 3461650494590786,
        "accountId": "15134345",
        "symbol": "AAPL",
        "market": "US",
        "currency": "USD",
        "secType": "STK",
        "expiry": "20221021",
        "strike": "200",
        "right": "CALL",
        "orderType": "LMT",
        "totalQuantity": 100,
        "price": 20,
        "stopLossPrice": 20,
        "action": "BUY",
        "status": "NEW",
        "outsideRth": true,
        "message": ""
    },
    "timestamp": 1646381210
}

User Register Event

After a user successfully registers, the Open API will push the registration success information to the callback URL provided by the third-party platform. The callback payload is in JSON format, with the following fields and example:

{
    "eventId": "36c565ad20071a581a7d62d6d233cf11",
    "eventType": "user.created",
    "payload": {
        "uid":1111111122222222,
        "clientId":"aaaaaabbbbbbbccccccddddd",
        "externalId":"abcd1234"
    },
    "timestamp":1644909898907
}

Among them, externalId is the user's ID on the third-party platform. The third-party platform should extract this field to identify the successfully registered user.

In cases such as unstable network conditions, the Open API will automatically retry up to three times, so the probability of missed delivery is relatively low. If a customer reports a missed delivery, you can contact us for confirmation and manual binding.

Third-party platform callback URL:
The third-party platform must provide a callback address that supports the HTTP POST method (both test and production addresses are supported).

To ensure the callback endpoint is not invoked maliciously, the callback also supports an optional authentication header x-api-token (which can be left empty) for the third-party platform to verify the identity of the requester.

After successfully processing the request, the callback address must return an HTTP 200 status code. If the returned status code is not 200, we will retry up to three more times.

User Authorization Event

After user authentication and authorization, the Open API will push authorization information to the callback URL provided by the third-party platform.
Data example: The accounts and license fields can be empty. If the user has already opened an account, these fields will contain data. Multiple accounts are separated by a comma (,).

{
    "eventId": "36aaa111222071a581f7d62e6d832cf15",
    "eventType": "user.authorized",
    "payload": {
        "uid":1111112222222333333,
        "clientId":"abccabc123123123123abc",
        "externalId":"123456",
        "accounts":"1234", 
        "licenses":"TBSG"
    },
    "timestamp":1644909898907
}

Account Created Event

This event will be returned when the account is successfully created.

{
    "eventId": "c803c7a73f39711ce6b2132aa508af12",
    "eventType": "account.created",
    "payload": {
        "uuid": 3461650494590786,
        "externalId": "377645782",
        "accountId": "14763915"
    },
    "timestamp": 1646294761419
}

Note on identifier fields: User events (user.created, user.authorized) use uid to identify the user, while order and account events (order.created, account.created) use uuid.