使用指南

本文介绍交易API的完整业务流程，从初始化、登录、订阅回报、到委托下单、回报处理、查询等。

业务流程概览

典型的交易API使用流程如下：

1. 创建API实例（x1::XLTTradeApi::create ）
2. 配置参数（x1::XLTTradeConfig ）
3. 初始化（x1::XLTTradeApi::initialize ）
4. 登录（x1::XLTTradeApi::login ）
5. 获取日初资金/持仓（x1::XLTTradeApi::get_init_assets / x1::XLTTradeApi::get_init_positions ）
6. 订阅交易消息（x1::XLTTradeApi::subscribe_trade_message ）
7. 委托/撤单（x1::XLTTradeApi::insert_order / x1::XLTTradeApi::cancel_order ）
8. 在回调中处理回报（x1::XLTTradeSpi ）
9. 按需查询资金/持仓/订单/成交等

创建与初始化

首先创建API实例，然后配置交易参数并初始化。API实例只能创建一次，初始化也只能调用一次。

using namespace x1;
 
// 1. 创建API实例
XLTTradeApi* api = XLTTradeApi::create();
 
// 2. 配置参数
XLTTradeConfig config;
config.set_trading_day(20260402);                          // 设置交易日（必填）
config.set_local_addr(                                     //（必填）设置本地网卡IP地址。生产环境中，trade对应网卡建议为solarflare网卡，solarflare网卡将自动使用ef_vi，以便达到最优的性能，非solarflare网卡则回退到内核sock模式
        "172.16.10.155",                                   // agw 连接agw的本地网卡IP，生产环境需为AGW接入网段IP
        "172.16.10.155"                                    // trade 连接快速报单的本地网卡IP，生产环境需为快速报单网段IP
        );
config.add_agw_addr("192.168.5.64", 7060);                 // 添加AGW地址（必填，可多次调用）
config.set_order_timeout(10);                              // 订单超时时间，默认10秒（选填）
 
// 3. 初始化：传入配置和回调对象
MyTradeSpi spi;  // 继承自 XLTTradeSpi 的用户实现类
if (!api->initialize(&config, &spi)) {
    xlt_error_info_t err = XLTTradeApi::get_last_error();
    // 处理初始化失败
}

登录

登录请求为异步操作，调用 x1::XLTTradeApi::login 发起请求后，通过 x1::XLTTradeSpi::on_login 回调获取结果。登录成功后返回 session_id，后续所有接口调用都需要使用此 session_id。

uint64_t request_id = 1;
uint16_t client_id = 99;     // 委托源标识，详见"关键概念"
const char* account = "88888888888801";
const char* password = "12345678";
const char* pub_key = "XXXXXXXXXXXXXX";
 
api->login(request_id, client_id, account, password, pub_key);

登录回调处理：

void MyTradeSpi::on_login(uint64_t session_id, uint64_t request_id,
                          const xlt_error_info_t* error_info) {
    if (error_info && error_info->error_code_type != 0) {
        // 登录失败，处理错误
        return;
    }
    // 登录成功，保存 session_id，后续接口调用都需要用到
    session_id_ = session_id;
}

获取日初数据

登录成功后，可通过同步接口直接获取日初资金和持仓，用于初始化本地状态：

// 获取日初资金
const xlt_init_asset_info_t* init_assets = api->get_init_assets(session_id);
 
// 获取日初持仓列表
const XLTInitPositionList* init_positions = api->get_init_positions(session_id);
if (init_positions) {
    for (size_t i = 0; i < init_positions->data_count(); ++i) {
        const xlt_init_position_info_t* pos = init_positions->get(i);
        // 处理每条持仓记录
    }
}

订阅交易消息

登录成功后，需要订阅交易消息才能收到回报推送。订阅类型通过 x1::trade_message_type_t 按位或组合指定：

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::xlt_order_insert_info_t 结构体并调用 x1::XLTTradeApi::insert_order ：

xlt_order_insert_info_t order = {};
std::strcpy(order.security_code, "000002");       // 证券代码
order.exchange_index = ExchangeIndex::SZ;         // 深交所
order.price = 90500;                              // 委托价格，放大10000倍（即9.05元）
order.quantity = 1000;                            // 委托数量
order.order_type = OrderType::LIMIT_PRICE;        // 限价委托
order.side = Side::BUY;                           // 买入
order.business_type = BusinessType::CASH;         // 现货
 
uint64_t xid = api->insert_order(session_id, &order);
if (xid == 0) {
    // 发送失败，调用 XLTTradeApi::get_last_error() 获取原因
} else {
    // 发送成功，xid 为订单标识，后续回报/撤单都通过此 xid 关联
}

撤单

填写 x1::xlt_cancel_order_info_t 结构体并调用 x1::XLTTradeApi::cancel_order ：

xlt_cancel_order_info_t cancel = {};
cancel.origin_xid = xid;   // 填写需要撤销的原订单 xid
 
uint64_t cancel_xid = api->cancel_order(session_id, &cancel);
if (cancel_xid == 0) {
    // 撤单发送失败
}

回报处理

委托/撤单发送成功后，交易系统会通过 x1::XLTTradeSpi 的推送回调返回结果。回调在独立的推送线程中触发（参见 线程模型 ），用户需要注意线程安全。

典型的回报处理流程：

// 申报成功
void MyTradeSpi::on_order_response(uint64_t session_id, const xlt_msg_desc_t* msg_desc,
                                   const xlt_order_response_t* rsp) {
    // 订单已被交易所接受，更新本地订单状态
}
 
// 成交回报
void MyTradeSpi::on_trade_report(uint64_t session_id, const xlt_msg_desc_t* msg_desc,
                                 const xlt_trade_report_t* rpt) {
    // 订单发生成交，更新本地成交记录、资金、持仓
}
 
// 撤单成功
void MyTradeSpi::on_cancel_response(uint64_t session_id, const xlt_msg_desc_t* msg_desc,
                                    const xlt_cancel_response_t* rsp) {
    // 撤单成功，更新本地订单状态
}
 
// 委托失败（拒单/废单/撤单失败）
void MyTradeSpi::on_order_error_response(uint64_t session_id, const xlt_msg_desc_t* msg_desc,
                                         const xlt_order_error_response_t* err) {
    // 处理委托或撤单失败
}
 
// 订单结束（终结状态：全成/全撤/废单等）
void MyTradeSpi::on_order_end(uint64_t session_id, const xlt_msg_desc_t* msg_desc,
                              const xlt_order_end_t* end) {
    // 订单生命周期结束
}

查询

API提供多种查询接口，均为异步模式：发送查询请求后在对应回调中接收结果。

查询资金

api->query_assets(session_id, request_id);

结果通过 x1::XLTTradeSpi::on_query_assets 回调返回。

查询持仓

// 查询全部持仓
api->query_positions(session_id, request_id, "");
// 查询指定证券持仓
api->query_positions(session_id, request_id, "000002", ExchangeIndex::SZ);

结果通过 x1::XLTTradeSpi::on_query_positions 回调返回。

查询订单

// 条件查询
xlt_order_query_param_t param = {};
param.xid = 0;  // 为0则按后续条件查询
api->query_orders(session_id, request_id, &param);

结果通过 x1::XLTTradeSpi::on_query_orders 回调返回。

对于大量订单，建议使用分页查询 x1::XLTTradeApi::query_orders_by_page ， 回调通过 x1::XLTTradeSpi::on_query_orders_by_page 返回，其中 query_reference 用于下一次分页查询定位。

查询成交

// 查询所有成交，xid填0
api->query_trades(session_id, request_id, 0);
// 查询指定订单的成交
api->query_trades(session_id, request_id, xid);

结果通过 x1::XLTTradeSpi::on_query_trades 回调返回。

断线处理

当连接异常断开时，会触发 x1::XLTTradeSpi::on_disconnect 回调。用户需要在此回调中重新发起登录：

void MyTradeSpi::on_disconnect(uint64_t session_id) {
    // 连接断开，需要重新调用 login() 建立连接
}

算法母单

用户侧下算法单建议按以下流程进行：

1. 登录并完成必要初始化（XLTTradeApi::login_sync 或 XLTTradeApi::login）。
2. 提交算法母单创建请求（XLTTradeApi::algo_create）。
3. 处理创建响应（XLTTradeSpi::on_algo_create_report），确认母单是否创建成功。
4. 接收算法状态推送（XLTTradeSpi::on_algo_state），跟踪母单生命周期。
5. 需要撤销时，提交控制请求（XLTTradeApi::algo_control）。
6. 处理控制响应（XLTTradeSpi::on_algo_control_report），并持续以状态推送为准更新本地状态。

实践建议：

• 以 xlt_algo_id 作为母单主键管理本地上下文，避免创建/控制并发导致状态错乱。
• 创建成功后，不要仅依赖请求返回值，建议始终以 on_algo_state 作为状态收敛依据。
• 控制请求（撤销）需做幂等处理，重复请求应可安全重试。