| Xlight API用户手册 v1.6.0.23 Xlight极速柜台接口文档

载入中...
搜索中...
未找到
消息流

本文介绍交易API推送消息的订阅、重推和处理方式。

# 订阅交易消息

登录成功后，调用 x1::XLTTradeApi::subscribe_trade_message 订阅交易消息。 每个 `session_id` 仅第一次调用有效。

using namespace x1;
XLTTradeApi* api;
// 选择订阅的消息类型（按位或组合）
trade_message_type_t msg_type = TradeMessageType::REPORT | TradeMessageType::ORDER_BOOK;
// 选择推送方式
api->subscribe_trade_message(session_id, request_id, msg_type, TradeResumeType::QUICK, 0);
x1::XLTTradeApi
接口类
定义 xlt_trade_api.h:305
x1::XLTTradeApi::subscribe_trade_message
bool subscribe_trade_message(uint64_t session_id, uint64_t request_id, trade_message_type_t trade_message_type, TradeResumeType resume_type, uint64_t start_sequence)
订阅交易数据 每个session_id，仅第一次调用有效。
x1
定义 xlt_data_type.h:13
x1::trade_message_type_t
uint32_t trade_message_type_t
交易消息类型
定义 xlt_trade_data_type.h:97

## 消息类型（TradeMessageType）

通过 x1::trade_message_type_t 按位或组合指定需要订阅的消息类型：

类型 | 值 | 说明
--- | --- | ---
REPORT | 1 | 委托回报消息：申报成功、撤单成功、成交回报、委托失败、订单结束
RAW_REPORT | 1<<1 | 交易所原始报文，需要用户自行解码
ORDER_BOOK | 1<<2 | 订单簿消息：订单簿变动、资金变动、持仓变动

可同时订阅多种类型，例如：

trade_message_type_t msg_type = TradeMessageType::REPORT | TradeMessageType::ORDER_BOOK;

注意：资金划拨相关推送（\ref x1::XLTTradeSpi::on_counter_fund_transfer_request 等）在订阅任意消息类型后均会推送。

## 推送方式（TradeResumeType）

方式 | 说明
--- | ---
x1::TradeResumeType::RESTART | 从本交易日日初开始推送
x1::TradeResumeType::QUICK | 从最新数据开始推送（不回补历史）
x1::TradeResumeType::SPECIFY | 从指定 `start_sequence` 开始推送

# 重推消息

如果需要重新拉取某个区间的历史消息，可调用 x1::XLTTradeApi::rebuild_trade_message ：

// 重推 sequence 101 ~ 200 之间的消息（从 start_sequence+1 开始推送）
api->rebuild_trade_message(session_id, request_id, msg_type, 100, 200);
x1::XLTTradeApi::rebuild_trade_message
bool rebuild_trade_message(uint64_t session_id, uint64_t request_id, trade_message_type_t trade_message_type, uint64_t start_sequence, uint64_t end_sequence, uint64_t account_index=0)
重推消息

重推的消息通过与正常订阅相同的回调接口推送，可通过 x1::xlt_msg_desc_t::is_rebuild 字段区分是否为重推消息。

# 委托回报消息（REPORT）

订阅掩码包含 REPORT 时，以下回调会被触发：

回调 | 触发时机 | 数据结构
--- | --- | ---
x1::XLTTradeSpi::on_order_response | 新订单申报成功（交易所已接受） | x1::xlt_order_response_t
x1::XLTTradeSpi::on_cancel_response | 撤单成功 | x1::xlt_cancel_response_t
x1::XLTTradeSpi::on_trade_report | 成交回报 | x1::xlt_trade_report_t
x1::XLTTradeSpi::on_order_error_response | 委托失败（内部拒单/交易所拒单/废单/撤单失败） | x1::xlt_order_error_response_t
x1::XLTTradeSpi::on_order_end | 订单到达终止状态（全成/全撤/废单等） | x1::xlt_order_end_t

特点：直接由交易所回报转换而来，推送速度快，适合需要快速获取订单响应/成交回报的场景。

注意：委托回报消息可能不包含交易费用等信息，本地计算资金/持仓时可能存在误差。

典型使用方式：

1）登录成功后获取日初资金和持仓：

- x1::XLTTradeApi::get_init_assets
- x1::XLTTradeApi::get_init_positions

2）订阅委托回报消息：

api->subscribe_trade_message(session_id, request_id, TradeMessageType::REPORT, TradeResumeType::QUICK, 0);

3）实现回调接口，在回调中更新本地订单、资金、持仓状态。

- x1::XLTTradeSpi::on_counter_fund_transfer_result
- x1::XLTTradeSpi::on_cluster_fund_transfer_result

委托回报消息处理时序：

# 订单簿消息（ORDER_BOOK）

订阅掩码包含 ORDER_BOOK 时，以下回调会被触发：

回调 | 触发时机 | 数据结构
--- | --- | ---
x1::XLTTradeSpi::on_order_book_insert | 新订单创建 | x1::xlt_order_book_insert_t
x1::XLTTradeSpi::on_order_book_update | 订单状态变更（申报响应/撤单/成交等） | x1::xlt_order_book_update_t
x1::XLTTradeSpi::on_order_book_error | 订单错误（申报失败/撤单失败） | x1::xlt_order_book_error_t
x1::XLTTradeSpi::on_asset | 资金变动 | x1::xlt_asset_info_t
x1::XLTTradeSpi::on_position | 持仓变动 | x1::xlt_position_info_t

特点：将柜台订单簿、资金、持仓状态变动同步推送，用户通常不需要自行推导计算，仅需按推送更新本地状态。

注意：相对委托回报消息，推送速度略慢。

典型使用方式：

1）登录成功后获取日初资金和持仓：

- x1::XLTTradeApi::get_init_assets
- x1::XLTTradeApi::get_init_positions

2）订阅订单簿消息：

api->subscribe_trade_message(session_id, request_id, TradeMessageType::ORDER_BOOK, TradeResumeType::QUICK, 0);

3）实现回调接口，在回调中直接用推送数据更新本地订单、资金、持仓状态。

提示： x1::xlt_order_book_update_t 中的 x1::xlt_order_book_update_t::report_type 字段标识了本次变动的类型（申报成功/撤单成功/成交），对应 x1::xlt_order_book_update_t::report 联合体中的不同字段。

订单簿消息处理时序：

# 原始报文消息（RAW_REPORT）

订阅掩码包含 RAW_REPORT 时，交易所原始订单执行报告通过 x1::XLTTradeSpi::on_raw_report 推送。原始报文需要用户自行解码。

# 资金划拨消息

资金划拨相关消息在订阅任意消息类型后均会推送：

回调 | 触发时机
--- | ---
x1::XLTTradeSpi::on_fund_transfer_exec_result | 资金划拨执行结果
x1::XLTTradeSpi::on_counter_fund_transfer_request | 主柜资金划拨请求推送
x1::XLTTradeSpi::on_counter_fund_transfer_result | 主柜资金划拨结果推送
x1::XLTTradeSpi::on_cluster_fund_transfer_request | 双中心资金划拨请求推送
x1::XLTTradeSpi::on_cluster_fund_transfer_result | 双中心资金划拨结果推送

# 消息描述（xlt_msg_desc_t）

每条推送消息都携带 x1::xlt_msg_desc_t 描述信息：

字段 | 说明
--- | ---
x1::xlt_msg_desc_t::account_index | 账号索引
x1::xlt_msg_desc_t::sequence | 消息序号，递增，用于断点续传。为0时不能作为续传标识（快速订单回报为0）
x1::xlt_msg_desc_t::is_rebuild | 是否为重推消息：`true` 表示由 x1::XLTTradeApi::rebuild_trade_message 发起

关于 `sequence` 和断点续传的更多说明，参见 关键概念 。

# 同时订阅两类消息

REPORT 和 ORDER_BOOK 可以同时订阅：

trade_message_type_t msg_type = TradeMessageType::REPORT | TradeMessageType::ORDER_BOOK;
api->subscribe_trade_message(session_id, request_id, msg_type, TradeResumeType::QUICK, 0);

此时委托回报回调和订单簿回调会同时触发。两类消息独立推送，用户可根据业务需求选择一种或同时使用：

- 需要低延迟响应 → 使用 REPORT
- 需要完整状态同步 → 使用 ORDER_BOOK
- 同时使用 → 可对照两类消息做校验或互补