Data Format

WebSocket crypto trade event push uses Protobuf binary encoding. Each push message corresponds to a ReportMsg structure. The client should first distinguish the report type by the report_type field, then parse the relevant sub-report fields such as new_rpt, cancel_rpt, fill_rpt, or expire_rpt.

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.

Proto Definition

message Order {
    optional string order_id      = 1;  // Order ID
    optional uint32 side          = 2;  // Trade direction: 1=BUY, 2=SELL
    optional string coin          = 3;  // Base asset of the trading pair, e.g. BTC, ETH
    optional string currency      = 4;  // Quote asset of the trading pair, e.g. USD
    optional string price         = 5;  // Order price
    optional string order_qty     = 6;  // Order quantity
    optional uint32 ord_type      = 7;  // Order type: 1=Limit, 2=Market, 3=TAKE_PROFIT_LIMIT, 4=TAKE_PROFIT_MARKET, 5=STOP_LOSS_LIMIT, 6=STOP_LOSS_MARKET
    optional uint32 time_in_force = 8;  // Time in force: 2=TIF_GTC, 3=TIF_IOC
    optional int64 create_time    = 11; // Order creation timestamp, microseconds
    optional bool is_close        = 12; // Whether the order has reached a terminal state
    optional string cum_qty       = 13; // Cumulative filled quantity
    optional string avg_px        = 14; // Average fill price
}

// Order placement report
message OrderNewRpt {
    optional int32 result    = 1; // 0 = success, non-0 = failure
    optional string err_msg  = 2; // Error message
    optional string order_id = 3; // Order ID
}

// Order cancellation report
message OrderCancelRpt {
    optional int32 result    = 1; // 0 = success, non-0 = failure
    optional string err_msg  = 2; // Error message
    optional string order_id = 3; // Order ID
}

// Fill report
message OrderFillRpt {
    optional string order_id    = 1;  // Order ID
    optional string fill_id     = 2;  // Fill ID
    optional string last_px     = 3;  // Fill price for this event
    optional string last_qty    = 4;  // Fill quantity for this event
    optional string leave_qty   = 5;  // Remaining unfilled quantity
    optional uint32 fill_status = 6;  // Fill status: 1=partial fill, 2=full fill
    optional string last_amount = 9;  // Fill amount for this event
    optional string biz_flow_id = 10; // Unique business flow ID
}

// Order expiry report
message OrderExpireRpt {
    optional string order_id = 1; // Order ID
}

// Trade report
message ReportMsg {
    optional string report_id          = 1;  // Unique event ID (UUID), for client-side idempotency
    optional Order order               = 4;  // Order information
    optional uint32 report_type        = 6;  // Report type: 1=placement, 3=cancellation, 4=fill, 5=expiry
    optional OrderNewRpt new_rpt       = 7;  // Order placement result report
    optional OrderCancelRpt cancel_rpt = 9;  // Order cancellation result report
    optional OrderFillRpt fill_rpt     = 10; // Fill report
    optional OrderExpireRpt expire_rpt = 11; // Order expiry report
}

ReportMsg Top-Level Fields

Field	Type	Description
report_id	string	Unique event ID (UUID). Can be used for client-side idempotency.
order	Order	Order information snapshot. See Order Fields.
report_type	uint32	Report type. See report type descriptions below.
new_rpt	OrderNewRpt	Order placement result report. Only present when report_type=1. See OrderNewRpt Fields.
cancel_rpt	OrderCancelRpt	Order cancellation result report. Only present when report_type=3. See OrderCancelRpt Fields.
fill_rpt	OrderFillRpt	Fill report. Only present when report_type=4. See OrderFillRpt Fields.
expire_rpt	OrderExpireRpt	Order expiry report. Only present when report_type=5. See OrderExpireRpt Fields.

Report Types

Possible values for the report_type field:

Value	Description
1	Order placement report. Use new_rpt.result to determine success (0) or failure (non-0). On success, order.is_close = false; on failure, order.is_close = true.
3	Order cancellation report. Use cancel_rpt.result to determine success (0) or failure (non-0). On successful cancellation, order.is_close = true.
4	Fill report. Use fill_rpt.fill_status to distinguish partial fill (1) from full fill (2). On full fill, order.is_close = true.
5	Order expiry report. The order was cancelled by the system due to expiry. order.is_close = true.

Order Fields

Each push message carries a snapshot of the current order information.

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.
side	uint32	Trade direction. 1=BUY, 2=SELL.
coin	string	Base asset of the trading pair, e.g. BTC, ETH.
currency	string	Quote asset of the trading pair, e.g. USD.
price	string	Order price. May be empty for market orders.
order_qty	string	Order quantity.
ord_type	uint32	Order type. 1=Limit, 2=Market, 3=TAKE_PROFIT_LIMIT, 4=TAKE_PROFIT_MARKET, 5=STOP_LOSS_LIMIT, 6=STOP_LOSS_MARKET.
time_in_force	uint32	Time in force. 2=TIF_GTC, 3=TIF_IOC.
create_time	int64	Order creation time, Unix microsecond timestamp.
is_close	bool	true indicates the order has reached a terminal state — no further events will be pushed for this order.
cum_qty	string	Cumulative filled quantity.
avg_px	string	Average fill price. "0" if no fills yet.

OrderNewRpt Fields

Only present when report_type=1.

Field	Type	Description
result	int32	0 = placement succeeded; non-0 = placement failed.
err_msg	string	Failure reason. Empty when result=0.
order_id	string	Order ID.

OrderCancelRpt Fields

Only present when report_type=3.

Field	Type	Description
result	int32	0 = cancellation succeeded; non-0 = cancellation failed.
err_msg	string	Failure reason. Empty when result=0.
order_id	string	Order ID.

OrderFillRpt Fields

Only present when report_type=4.

Field	Type	Description
order_id	string	Order ID.
fill_id	string	Fill ID. Can be used for idempotency deduplication.
last_px	string	Fill price for this event.
last_qty	string	Fill quantity for this event.
leave_qty	string	Remaining unfilled quantity.
fill_status	uint32	Fill status. 1=partial fill, 2=full fill.
last_amount	string	Fill amount for this event.
biz_flow_id	string	Unique business flow ID.

OrderExpireRpt Fields

Only present when report_type=5.

Field	Type	Description
order_id	string	Order ID.

Compatibility Recommendations

• Dispatch by report_type: Different report types carry different sub-report fields. Use switch/match for handling.
• Ignore unknown fields: The server may add new fields; clients should maintain forward compatibility.
• Handle unknown report_type values: Log and skip them to avoid errors from newly added report types.
• Parse numeric fields as strings: Price, quantity, and similar fields are strings — convert to Decimal or float as needed for precision.
• Microsecond timestamps: create_time is a Unix microsecond timestamp — be careful not to confuse it with millisecond timestamps.

Related Documentation

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