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

载入中...
搜索中...
未找到
关键概念

本文介绍交易API中的核心概念。

# 委托源（client_id）

`client_id` 是客户端标识ID，取值范围 [0, 255]，在调用 x1::XLTTradeApi::login 时指定。

在本次登录 session 中进行的所有委托及回报，系统都将打上此 `client_id` 标记，用于委托隔离。 例如，用户可以使用不同的 `client_id` 来区分不同的策略或客户端：

using namespace x1;
XLTTradeApi* api;
// 策略1使用 client_id = 1
api->login(request_id, 1, account_name, password, pub_key);
// 登录回调得到 session_id_s1
// 策略2使用 client_id = 2
api->login(request_id, 2, account_name, password, pub_key);
// 登录回调得到 session_id_s2
// 策略1下单
xlt_order_insert_info_t order1 = {};
uint64_t xid1 = api->insert_order(session_id_s1, &order1);
// 策略2下单
xlt_order_insert_info_t order2 = {};
uint64_t xid2 = api->insert_order(session_id_s2, &order2);
x1::XLTTradeApi
接口类
定义 xlt_trade_api.h:305
x1::XLTTradeApi::insert_order
uint64_t insert_order(uint64_t session_id, xlt_order_insert_info_t *order, uint64_t trade_token=0)
委托 报单录入请求，所有业务统一报单接口，根据业务类型字段区分不同业务。 Xlight接收订单后，会在报单响应函数on_order_response, on_cancel_response,...
x1::XLTTradeApi::login
bool login(uint64_t request_id, uint16_t client_id, const char *account_name, const char *password, const char *pub_key, const xlt_user_terminal_info_t *info=nullptr)
用户登录请求
x1
定义 xlt_data_type.h:13
x1::xlt_order_insert_info_t
新订单请求数据结构
定义 xlt_trade_struct.h:17

后续的回报及查询信息将带回此 `client_id`：

- x1::xlt_order_response_t::client_id
- x1::xlt_trade_report_t::client_id
- x1::xlt_cancel_response_t::client_id
- x1::xlt_order_error_response_t::client_id
- x1::xlt_order_end_t::client_id
- x1::xlt_order_info_t::client_id

# 订单序号（order_sequence）

默认情况下，API自动生成订单序号，用户无需关心。

若启用自定义订单序号（x1::XLTTradeConfig::set_order_seq_self_define）， 则用户在每次下单时必须在 x1::xlt_order_insert_info_t 或 x1::xlt_cancel_order_info_t 中指定 `order_sequence` 字段。

using namespace x1;
// 启用自定义订单序号
config.set_order_seq_self_define(true);
// 下单时指定 order_sequence
xlt_order_insert_info_t order = {};
order.order_sequence = 99; // 用户自定义序号
uint64_t xid = api->insert_order(session_id, &order);
// 通过 xid 获取订单序号
uint64_t seq = XLTTradeApi::get_order_sequence(xid); // seq == 99
// 撤单时也需要指定 order_sequence
xlt_cancel_order_info_t cancel = {};
cancel.order_sequence = 500099; // 撤单使用不同序号段
cancel.origin_xid = xid;
uint64_t cancel_xid = api->cancel_order(session_id, &cancel);
x1::XLTTradeApi::cancel_order
uint64_t cancel_order(uint64_t session_id, xlt_cancel_order_info_t *cancel_order, uint64_t trade_token=0)
撤单 撤单请求。 如果撤单成功，会在报单响应函数on_cancel_response里返回原单部撤或者全撤的消息， 如果不成功，会在on_order_error_response响应函数中返回错误原因。
x1::xlt_cancel_order_info_t
撤单请求数据结构
定义 xlt_trade_struct.h:31
x1::xlt_cancel_order_info_t::order_sequence
uint64_t order_sequence
订单序号，当API配置中开启自定义模式时，由用户填写，session内不能重复，否则由系统生成，取值范围[0, 2^20-1]。
定义 xlt_trade_struct.h:32
x1::xlt_cancel_order_info_t::origin_xid
uint64_t origin_xid
原始订单标识
定义 xlt_trade_struct.h:33
x1::xlt_order_insert_info_t::order_sequence
uint64_t order_sequence
订单序号，当API配置中开启自定义模式时，由用户填写，session内不能重复，否则由系统生成，取值范围[0, 2^20-1]。
定义 xlt_trade_struct.h:18

重要注意事项：

- 启用后，每次下单的 `order_sequence` 必须保证唯一，否则会被识别为重单，重单将没有任何响应。
- `order_sequence` 取值范围 [1, 2^20-1]。
- 建议委托和撤单使用不同的序号分段，例如委托使用 1~500000，撤单使用 500001~1000000。

# 请求标识（request_id）

`request_id` 用于在异步回调中定位对应的请求。API不对 `request_id` 做任何验证或业务假设，在回调中原样返回。

用户可根据业务场景自定义，例如使用递增序号：

using namespace x1;
uint64_t next_request_id() {
static std::atomic<uint64_t> counter(0);
return ++counter;
}
uint64_t req_id = next_request_id();
api->login(req_id, client_id, account_name, password, pub_key);
// on_login 回调中会原样返回此 req_id

以下回调携带 `request_id`：

- x1::XLTTradeSpi::on_login
- x1::XLTTradeSpi::on_auth_trade
- x1::XLTTradeSpi::on_subscribe_trade_message
- x1::XLTTradeSpi::on_rebuild_trade_message
- 所有查询回调（x1::XLTTradeSpi::on_query_assets 等）

# 回报消息序号（sequence）

柜台对交易消息进行全局唯一递增编号，即 x1::xlt_msg_desc_t::sequence ，用于断点续传。

订阅回报时指定 `start_sequence`，柜台会从该序号的 下一条 消息开始推送：

using namespace x1;
// 从指定序号断点续传
uint64_t last_sequence = /* 上次记录的最后一个序号 */;
api->subscribe_trade_message(session_id, request_id,
TradeMessageType::REPORT, TradeResumeType::SPECIFY, last_sequence);
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，仅第一次调用有效。

注意事项：

- `sequence` 为 0 时表示快速返回的交易所回报，此时不能作为续传标识。
- 因此断点续传恢复数据时，需要根据 report_id 进行去重。

以下消息中包含 `sequence` 字段（通过 x1::xlt_msg_desc_t ）：

- 所有推送回调的 `msg_desc->sequence`

# 回报消息唯一标识（report_id）

`report_id` 为 32 字节长度的回报消息唯一标识，非字符串。

在单个API生命周期中，回调会保证相同 `report_id` 只回调一次。但在异常恢复场景下（进程重启后重拉回报），用户需要自行根据 `report_id` 与本地持久化的回报进行去重。

若本地没有持久化，建议重启时从头拉取全部回报：

using namespace x1;
// 从日初开始拉取全部回报
api->subscribe_trade_message(session_id, request_id,
TradeMessageType::REPORT, TradeResumeType::RESTART, 0);

以下消息中包含 `report_id` 字段：

- x1::xlt_order_response_t::report_id
- x1::xlt_trade_report_t::report_id
- x1::xlt_cancel_response_t::report_id
- x1::xlt_order_error_response_t::report_id
- x1::xlt_order_end_t::report_id

# 订单标识（xid）

`xid` 是调用 x1::XLTTradeApi::insert_order 或 x1::XLTTradeApi::cancel_order 时由系统返回的订单标识。

- xid 在当前交易日内唯一，不同交易日不保证唯一。
- 返回值为 0 表示发送失败。
- 后续所有回报中都会携带此 xid，用于关联订单。
- 撤单时通过 x1::xlt_cancel_order_info_t::origin_xid 指定需要撤销的原订单 xid。
- 可通过 x1::XLTTradeApi::get_order_sequence 从 xid 中提取订单序号。
- 可通过 x1::XLTTradeApi::get_xid_sender 从 xid 获取发送者的 session_id 和 trade_token。

# 订单超时

通过 x1::XLTTradeConfig::set_order_timeout 设置订单超时时间（单位：秒）。 当委托在指定时间内未收到任何响应时，触发 x1::XLTTradeSpi::on_order_timeout 回调。

注意：订单超时不代表委托失败，用户需要自行查询确认订单状态。超时后可调用 x1::XLTTradeApi::resend_order_request 重发订单。如果柜台已处理原请求，重发的订单会被识别为重单，不会有任何响应。

void MyTradeSpi::on_order_timeout(uint64_t session_id, uint64_t xid) {
// 可选择查询订单状态或重发
api->resend_order_request(session_id, xid);
}
x1::XLTTradeApi::resend_order_request
bool resend_order_request(uint64_t session_id, uint64_t xid)
重发订单请求

# 会话ID（session_id）

`session_id` 在 x1::XLTTradeSpi::on_login 回调中返回，代表一次成功的登录会话。后续几乎所有API接口调用都需要传入此 `session_id`。

当连接断开（x1::XLTTradeSpi::on_disconnect 触发）后，原 `session_id` 失效，需要重新登录获取新的 `session_id`。

注意：`session_id`在单台机器上是唯一的，但不同机器之间不保证唯一。