Data Format

WebSocket crypto trade event push uses Protobuf binary encoding. Each push message corresponds to one trade event. The client should first distinguish the event type by the event_type field, then parse the specific fields such as order_info and fill_infos.

Note

Trade event pushes are transmitted as Protobuf binary frames, not JSON text. The authentication response (code/msg) is JSON. Clients must allow receiving binary frames (e.g., skip_utf8_validation=True).

INFO

Numeric fields in trade events (such as price and quantity) are transmitted as strings to avoid floating-point precision issues. Time fields use microsecond timestamps (Unix microseconds). Handle types according to field descriptions when parsing, and ignore unknown fields to maintain forward compatibility.

Message Structure

The top level of each push message is a CryptoTradeEvent object:

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "EVENT_FILL",
  "event_time_us": 1751433600000000,
  "user_info": {
    "uid": 123456789,
    "account_id": 987654321098765432
  },
  "order_info": {
    "order_id": "FTHC2989880641155745280T",
    "version": 2,
    "symbol_pair": {
      "symbol": "BTCUSD",
      "base": "BTC",
      "quote": "USD"
    },
    "side": "BUY",
    "order_qty": "0.1",
    "price": "29500",
    "order_amount": "2950",
    "cum_qty": "0.06",
    "avg_px": "29498.50",
    "fill_amount": "1769.91",
    "ord_type": "LIMIT",
    "time_in_force": "TIF_GTC",
    "create_time": 1751433500000000,
    "update_time": 1751433600000000,
    "ord_status": "PARTIAL_FILLED",
    "order_show_id": "C2989880641155745280",
    "is_close": false,
    "trigger_price": "",
    "trigger_time": 0,
    "cash_order_qty": ""
  },
  "fill_infos": [
    {
      "order_id": "FTHC2989880641155745280T",
      "fill_id": "FILL001",
      "quantity": "0.06",
      "price": "29498.50",
      "amount": "1769.91",
      "fill_time": 1751433600000000
    }
  ]
}

CryptoTradeEvent Top-Level Fields

Field	Type	Description
event_id	string	Unique event ID (UUID). Can be used for client-side idempotency.
event_type	string	Event type. See event type descriptions below.
event_time_us	integer	Event occurrence time, Unix microsecond timestamp.
user_info	object	User information. See user_info Fields.
order_info	object	Order snapshot reflecting the latest order state at the time of the event. See order_info Fields.
fill_infos	object[]	List of fill details. See fill_infos Fields. Only populated for EVENT_FILL events; empty array for all other event types.

Event Types

Possible values for the event_type field:

Value	Description
EVENT_NEW	Order placement succeeded. The order has been accepted by the system and entered the order queue. order_info.is_close = false.
EVENT_NEW_REJECTED	Order placement failed. The order was rejected by the system. order_info.is_close = true.
EVENT_FILL	Fill event. fill_infos contains the fill details for this event. Use order_info.ord_status to distinguish partial fill (PARTIAL_FILLED) from full fill (FILLED). order_info.is_close = true when fully filled.
EVENT_CANCELED	Cancellation succeeded. The order has been cancelled. order_info.is_close = true.
EVENT_EXPIRED	Order expired. The order was cancelled by the system due to expiry. order_info.is_close = true.

user_info Fields

Field	Type	Description
uid	integer	User ID (nnid).
account_id	integer	Crypto account ID (uint64). If the same user holds multiple crypto accounts, this field identifies which account the event belongs to.

order_info Fields

Each push message carries the current snapshot of the order, reflecting the latest order state at the time of the event.

Key Field: is_close

is_close = true means the order has reached a terminal state — no further push events will be received for this order. is_close = false means the order is still active; fill or cancellation events may follow.

Field	Type	Description
order_id	string	Order ID, unchanged throughout the order lifecycle.
version	uint32	Order version number.
symbol_pair	SymbolPair	Trading pair.
side	side	Trade direction.
order_qty	string	Order quantity.
price	string	Limit price. May be empty for market orders.
order_amount	string	Order amount.
cum_qty	string	Cumulative filled quantity as of this event.
avg_px	string	Average fill price as of this event. "0" if no fills yet.
fill_amount	string	Cumulative fill amount as of this event.
ord_type	ord_type	Order type.
time_in_force	time_in_force	Time in force.
create_time	int64	Order creation time, Unix microsecond timestamp.
update_time	int64	Order last update time, Unix microsecond timestamp.
ord_status	ord_status	Current order status.
order_show_id	string	Display order ID for client UI.
is_close	bool	true indicates the order has reached a terminal state — no further events will be pushed for this order. See note above.
trigger_price	string	Trigger price for conditional orders; empty string for non-conditional orders.
trigger_time	int64	Trigger time for conditional orders (Unix microseconds); 0 if not yet triggered.
cash_order_qty	string	Order amount for amount-based orders; empty string for quantity-based orders.

fill_infos Fields

Only contains valid data for EVENT_FILL events; empty array for all other event types.

Field	Type	Description
order_id	string	Associated order ID.
fill_id	string	Fill ID. Can be used for idempotency deduplication.
quantity	string	Quantity filled in this event.
price	string	Fill price in this event.
amount	string	Fill amount in this event (price × quantity).
fill_time	int64	Fill time, Unix microsecond timestamp.

Compatibility Recommendations

• Dispatch by event_type: Whether fill_infos has data varies significantly across event types. Use switch/match for handling.
• Ignore unknown fields: The server may add new fields; clients should maintain forward compatibility.
• Handle unknown event_type values: Log and skip them to avoid errors from newly added event types.
• Parse numeric fields as strings: Price, quantity, and similar fields are strings — convert to Decimal or float as needed for precision.
• Microsecond timestamps: event_time_us, create_time, update_time, and fill_time are all Unix microsecond timestamps — be careful not to confuse them with millisecond timestamps.

Related Documentation

• Subscription & Event Handling — Event identification, terminal state detection, and timing examples.
• Connection Keep-Alive
• Error Codes