数据格式

WebSocket 加密货币交易推送使用 Protobuf 二进制编码传输。每条推送消息对应一个交易事件，反序列化后对应下方描述的 CryptoTradeEvent 结构，客户端应先按 event_type 字段区分事件类型，再解析 order_info 和 fill_infos 等具体字段。

注意

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

INFO

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

消息结构

每条推送消息的顶层为一个 CryptoTradeEvent 对象：

json

{
  "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 顶层字段

字段	类型	说明
`event_id`	string	事件唯一 ID（UUID），可用于客户端幂等处理。
`event_type`	string	事件类型，详见下方事件类型说明。
`event_time_us`	integer	事件发生时间，Unix 微秒时间戳。
`user_info`	object	用户信息，详见 user_info 字段。
`order_info`	object	订单快照，反映事件发生时刻的最新订单状态，详见 order_info 字段。
`fill_infos`	object[]	成交信息列表，详见 fill_infos 字段。仅在 `EVENT_FILL` 事件中有值，其他事件该字段为空数组。

事件类型

event_type 字段的可选值：

值	说明
`EVENT_NEW`	下单成功事件。订单已被系统受理，进入委托队列。`order_info.is_close = false`。
`EVENT_NEW_REJECTED`	下单失败事件。订单被系统拒绝。`order_info.is_close = true`。
`EVENT_FILL`	成交事件。`fill_infos` 包含本次成交明细。通过 `order_info.ord_status` 区分部分成交（`PARTIAL_FILLED`）和全部成交（`FILLED`）。全部成交时 `order_info.is_close = true`。
`EVENT_CANCELED`	撤单成功事件。订单已被撤销。`order_info.is_close = true`。
`EVENT_EXPIRED`	订单过期事件。订单因有效期到期被系统撤销。`order_info.is_close = true`。

user_info 字段

字段	类型	说明
`uid`	integer	用户 ID（nnid）。
`account_id`	integer	加密货币账户 ID（uint64）。如果同一用户持有多个加密货币账户，可通过该字段区分事件来源账户。

order_info 字段

每条推送消息均携带订单的当前快照，反映事件发生时刻的最新订单状态。

关键字段：is_close

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

字段	类型	说明
`order_id`	string	订单号，生命周期内不变。
`version`	uint32	订单版本号。
`symbol_pair`	SymbolPair	交易对。
`side`	side	买卖方向。
`order_qty`	string	订单委托数量。
`price`	string	委托价格。市价单可能为空。
`order_amount`	string	委托金额。
`cum_qty`	string	截至本事件时刻的累计已成交数量。
`avg_px`	string	截至本事件时刻的成交均价。未成交时为 `"0"`。
`fill_amount`	string	截至本事件时刻的累计成交金额。
`ord_type`	ord_type	订单类型。
`time_in_force`	time_in_force	订单有效期。
`create_time`	int64	订单创建时间，Unix 微秒时间戳。
`update_time`	int64	订单最后更新时间，Unix 微秒时间戳。
`ord_status`	ord_status	订单当前状态。
`order_show_id`	string	客户端展示用订单 ID。
`is_close`	bool	`true` 表示订单已到达终态，不会再推送该订单的后续事件。见上方提示。
`trigger_price`	string	条件单触发价，非条件单为空字符串。
`trigger_time`	int64	条件单触发时间（Unix 微秒），未触发为 `0`。
`cash_order_qty`	string	金额下单时的委托金额，数量下单时为空字符串。

fill_infos 字段

仅在 EVENT_FILL 事件中包含有效数据，其他事件类型该字段为空数组。

字段	类型	说明
`order_id`	string	关联的订单 ID。
`fill_id`	string	成交 ID，可用于幂等去重。
`quantity`	string	本次成交数量。
`price`	string	本次成交价格。
`amount`	string	本次成交金额（`price × quantity`）。
`fill_time`	int64	成交时间，Unix 微秒时间戳。

兼容性建议

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

数据格式 ​

消息结构 ​

CryptoTradeEvent 顶层字段 ​

事件类型 ​

user_info 字段 ​

order_info 字段 ​

fill_infos 字段 ​

兼容性建议 ​

相关文档 ​