数据格式

WebSocket 加密货币交易推送使用 Protobuf 二进制编码传输。每条推送消息对应一个 ReportMsg 结构，客户端应先按 report_type 字段区分报告类型，再解析 new_rpt、cancel_rpt、fill_rpt、expire_rpt 等具体子报告字段。

注意

交易事件推送为 Protobuf 二进制格式，非 JSON 文本。鉴权响应（code/msg 字段）为 JSON 格式。客户端接收消息时需设置允许接收二进制帧（如 skip_utf8_validation=True）。

INFO

交易事件中的数值字段（如价格、数量）均以字符串类型传输，以避免浮点精度问题。时间字段使用微秒时间戳（Unix 微秒）。解析时请按字段说明做类型处理，未知字段建议忽略以保持向前兼容。

Proto 定义

proto

message Order {
    optional string order_id      = 1;  // 订单ID
    optional uint32 side          = 2;  // 买卖方向 1：BUY  2：SELL
    optional string coin          = 3;  // 交易对的基础资产，如 BTC、ETH
    optional string currency      = 4;  // 交易对的计价资产，如 USD
    optional string price         = 5;  // 订单价格
    optional string order_qty     = 6;  // 订单数量
    optional uint32 ord_type      = 7;  // 订单类型 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;  // 订单有效期 2：TIF_GTC 3：TIF_IOC
    optional int64 create_time    = 11; // 订单创建时间戳，微秒
    optional bool is_close        = 12; // 订单是否完结
    optional string cum_qty       = 13; // 累计成交数量
    optional string avg_px        = 14; // 平均成交价格
}

// 下单报告
message OrderNewRpt {
    optional int32 result    = 1; // 0 成功，非 0 失败
    optional string err_msg  = 2; // 错误信息
    optional string order_id = 3; // 订单ID
}

// 撤单报告
message OrderCancelRpt {
    optional int32 result    = 1; // 0 成功，非 0 失败
    optional string err_msg  = 2; // 错误信息
    optional string order_id = 3; // 订单ID
}

// 成交报告
message OrderFillRpt {
    optional string order_id    = 1;  // 订单ID
    optional string fill_id     = 2;  // 成交ID
    optional string last_px     = 3;  // 本次成交价格
    optional string last_qty    = 4;  // 本次成交数量
    optional string leave_qty   = 5;  // 剩余未成交数量
    optional uint32 fill_status = 6;  // 成交状态 1：部分成交 2：完全成交
    optional string last_amount = 9;  // 成交金额
    optional string biz_flow_id = 10; // 业务流水唯一ID
}

// 订单过期报告
message OrderExpireRpt {
    optional string order_id = 1; // 订单ID
}

// 交易报告
message ReportMsg {
    optional string report_id          = 1;  // 事件唯一 ID（UUID），用于客户端幂等处理
    optional Order order               = 4;  // 订单信息
    optional uint32 report_type        = 6;  // 报告类型 1：下单报告 3：撤单报告 4：成交报告 5：订单过期报告
    optional OrderNewRpt new_rpt       = 7;  // 下单结果报告
    optional OrderCancelRpt cancel_rpt = 9;  // 撤单结果报告
    optional OrderFillRpt fill_rpt     = 10; // 成交报告
    optional OrderExpireRpt expire_rpt = 11; // 订单过期报告
}

ReportMsg 顶层字段

字段	类型	说明
`report_id`	string	事件唯一 ID（UUID），可用于客户端幂等处理。
`order`	Order	订单信息快照，详见 Order 字段。
`report_type`	uint32	报告类型，详见下方报告类型说明。
`new_rpt`	OrderNewRpt	下单结果报告，仅 `report_type=1` 时有值，详见 OrderNewRpt 字段。
`cancel_rpt`	OrderCancelRpt	撤单结果报告，仅 `report_type=3` 时有值，详见 OrderCancelRpt 字段。
`fill_rpt`	OrderFillRpt	成交报告，仅 `report_type=4` 时有值，详见 OrderFillRpt 字段。
`expire_rpt`	OrderExpireRpt	订单过期报告，仅 `report_type=5` 时有值，详见 OrderExpireRpt 字段。

报告类型

report_type 字段的可选值：

值	说明
`1`	下单报告。通过 `new_rpt.result` 判断下单成功（`0`）或失败（非 `0`）。下单成功时 `order.is_close = false`，下单失败时 `order.is_close = true`。
`3`	撤单报告。通过 `cancel_rpt.result` 判断撤单成功（`0`）或失败（非 `0`）。撤单成功时 `order.is_close = true`。
`4`	成交报告。通过 `fill_rpt.fill_status` 区分部分成交（`1`）和完全成交（`2`）。完全成交时 `order.is_close = true`。
`5`	订单过期报告。订单因有效期到期被系统撤销。`order.is_close = true`。

Order 字段

每条推送消息均携带订单的当前信息快照。

关键字段：is_close

is_close = true 表示订单已到达终态，不会再收到该订单的任何后续推送。 is_close = false 表示订单仍然活跃，后续还可能收到成交或撤单事件。

字段	类型	说明
`order_id`	string	订单 ID，生命周期内不变。
`side`	uint32	买卖方向。`1`=BUY，`2`=SELL。
`coin`	string	交易对的基础资产，如 `BTC`、`ETH`。
`currency`	string	交易对的计价资产，如 `USD`。
`price`	string	订单价格。市价单可能为空。
`order_qty`	string	订单数量。
`ord_type`	uint32	订单类型。`1`=Limit，`2`=Market，`3`=TAKE_PROFIT_LIMIT，`4`=TAKE_PROFIT_MARKET，`5`=STOP_LOSS_LIMIT，`6`=STOP_LOSS_MARKET。
`time_in_force`	uint32	订单有效期。`2`=TIF_GTC，`3`=TIF_IOC。
`create_time`	int64	订单创建时间，Unix 微秒时间戳。
`is_close`	bool	`true` 表示订单已到达终态，不会再推送该订单的后续事件。
`cum_qty`	string	累计成交数量。
`avg_px`	string	平均成交价格。未成交时为 `"0"`。

OrderNewRpt 字段

仅 report_type=1 时存在。

字段	类型	说明
`result`	int32	`0` 表示下单成功，非 `0` 表示下单失败。
`err_msg`	string	失败原因。`result=0` 时为空。
`order_id`	string	订单 ID。

OrderCancelRpt 字段

仅 report_type=3 时存在。

字段	类型	说明
`result`	int32	`0` 表示撤单成功，非 `0` 表示撤单失败。
`err_msg`	string	失败原因。`result=0` 时为空。
`order_id`	string	订单 ID。

OrderFillRpt 字段

仅 report_type=4 时存在。

字段	类型	说明
`order_id`	string	订单 ID。
`fill_id`	string	成交 ID，可用于幂等去重。
`last_px`	string	本次成交价格。
`last_qty`	string	本次成交数量。
`leave_qty`	string	剩余未成交数量。
`fill_status`	uint32	成交状态。`1`=部分成交，`2`=完全成交。
`last_amount`	string	本次成交金额。
`biz_flow_id`	string	业务流水唯一 ID。

OrderExpireRpt 字段

仅 report_type=5 时存在。

字段	类型	说明
`order_id`	string	订单 ID。

兼容性建议

按 report_type 分发处理：不同报告类型携带不同子报告字段，建议 switch/match 处理。
未知字段忽略：服务端可能新增字段，客户端应保持向前兼容。
未知 report_type 兼容：记录日志后跳过，避免因新增报告类型导致处理异常。
数值字段以字符串解析：价格、数量等字段均为字符串，需自行转换为 Decimal 或 float 处理精度。
微秒时间戳：create_time 为 Unix 微秒时间戳，注意与毫秒时间戳区分。

数据格式 ​

Proto 定义 ​

ReportMsg 顶层字段 ​

报告类型 ​

Order 字段 ​

OrderNewRpt 字段 ​

OrderCancelRpt 字段 ​

OrderFillRpt 字段 ​

OrderExpireRpt 字段 ​

兼容性建议 ​

相关文档 ​