本文介绍交易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);

后续的回报及查询信息将带回此 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);

重要注意事项：

启用后，每次下单的 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);

注意事项：

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 字段：

订单标识（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);
}

会话ID（session_id）

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

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

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