使用指南

本文介绍交易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::XLTTradeApi::query_issue_rights 和 x1::XLTTradeApi::query_allot_rights 使用相同的过滤参数：

参数	说明
request_id	用户自定义的查询标识，回调原样返回；并发查询应使用不同的 ID
security_code	nullptr 或空字符串表示查询全部；非空时为不带空格、以 \0 结尾的证券代码
exchange_index	ExchangeIndex::INIT 表示不指定市场；按证券代码查询时建议同时指定正确市场
account_index	0 表示当前登录交易账号；非 0 表示指定账号，可由 x1::XLTTradeApi::get_account_index 或 x1::XLTTradeApi::query_trade_account_info 获取

uint64_t issue_request_id = next_request_id();
if (!api->query_issue_rights(
        session_id, issue_request_id, "", ExchangeIndex::INIT, 0)) {
    xlt_error_info_t error = XLTTradeApi::get_last_error();
    // 请求未发送
}
 
uint64_t allot_request_id = next_request_id();
if (!api->query_allot_rights(
        session_id, allot_request_id, "000001", ExchangeIndex::SZ,
        account_index)) {
    xlt_error_info_t error = XLTTradeApi::get_last_error();
    // 请求未发送
}

两个查询都是异步接口。true 仅表示请求已发送；结果分别通过 x1::XLTTradeSpi::on_query_issue_rights 和 x1::XLTTradeSpi::on_query_allot_rights 返回。

新股新债查询结果

x1::XLTIssueRightsList 中的每个 x1::xlt_issue_rights_t 表示一只可申购证券：

字段	说明
account_index / exchange_index / security_code	账号、市场和证券标识
issue_type	1 表示新股，2 表示新债/可转债
issue_price	认购价格，放大 10000 倍
min_price / max_price / price_unit	价格下限、上限和最小价格变动单位，均放大 10000 倍
unit	申购数量单位，委托数量应为该值的整数倍
qty_lower_limit / qty_upper_limit	单笔申购数量下限和上限
has_right_avail / right_avail	has_right_avail 为 true 时，right_avail 才是有效的账户权益数量
has_tech_avail / tech_avail	has_tech_avail 为 true 时，tech_avail 才是有效的科创板可申购数量

布尔标志为 false 时，不应将对应的数量字段当作有效额度。

配股配债查询结果

x1::XLTAllotRightsList 中的每个 x1::xlt_allot_rights_t 包含：

字段	说明
account_index / exchange_index / security_code	账号、市场和证券标识
allotment_price / price_unit	配股/配债价格和最小价格变动单位，均放大 10000 倍
unit	申购数量单位，委托数量应为该值的整数倍
initial_pos_avail	交易日开始时的初始可配数量
current_available	当前可配数量，委托前风控应使用该字段
security_total / security_freeze	交易日开始时的证券总数和冻结数量

分批回调处理

同一个 request_id 可对应多次回调。每次回调只代表当前批次，应迭代列表的 data_count() 条数并累积结果，直到 is_last == true 才结束该查询。空结果时列表指针可为空；回调指针只在当次回调期间使用，需要异步处理时应先拷贝数据。

void MyTradeSpi::on_query_issue_rights(
        uint64_t session_id, uint64_t request_id,
        const XLTIssueRightsList* rights_list, bool is_last,
        const xlt_error_info_t* error_info) {
    if (error_info &&
        (error_info->error_code_type != 0 || error_info->error_code != 0)) {
        // 记录查询错误，结束 request_id 对应的上下文
        return;
    }
 
    if (rights_list) {
        for (size_t i = 0; i < rights_list->data_count(); ++i) {
            const xlt_issue_rights_t* item =
                rights_list->get(static_cast<int>(i));
            // 将 *item 拷贝到 request_id 对应的本地结果集
        }
    }
    if (is_last) {
        // 该 request_id 的所有批次已收齐
    }
}

网上发行/配售业务委托

当前 x1::XLTTradeApi::insert_special_order 和 x1::XLTTradeApi::cancel_special_order 支持以下业务：

场景	额度来源	business_type	下单/撤单接口
新股、新债/可转债申购	x1::XLTTradeApi::query_issue_rights	x1::BusinessType::ISSUE	insert_special_order / cancel_special_order
配股、配债	x1::XLTTradeApi::query_allot_rights	x1::BusinessType::ALLOT	insert_special_order / cancel_special_order

ISSUE 和 ALLOT 需使用特殊业务接口，不要改用普通 x1::XLTTradeApi::insert_order / x1::XLTTradeApi::cancel_order 流程。以新股新债查询结果构造委托的示例：

void submit_issue_order(const xlt_issue_rights_t& rights,
                        quantity_t quantity) {
    if (rights.unit <= 0 || quantity < rights.qty_lower_limit ||
        quantity > rights.qty_upper_limit || quantity % rights.unit != 0) {
        // 申购数量不符合查询结果的约束
        return;
    }
 
    xlt_order_insert_info_t order = {};
    std::strncpy(order.security_code, rights.security_code,
                 sizeof(order.security_code) - 1);
    order.exchange_index = rights.exchange_index;
    order.price = rights.issue_price;
    order.quantity = quantity;
    order.order_type = OrderType::LIMIT_PRICE;
    order.side = Side::BUY;
    order.business_type = BusinessType::ISSUE;
 
    uint64_t xid =
        api->insert_special_order(session_id, &order, trade_token);
    if (xid == 0) {
        xlt_error_info_t error = XLTTradeApi::get_last_error();
        // 请求未发送
    }
}

配股配债的构造方式相同，但应使用 xlt_allot_rights_t::allotment_price、unit 和 current_available，并将 business_type 设为 BusinessType::ALLOT。市场规则和柜台实时风控仍是最终判定依据，查询结果仅用于下单前预检。

委托回调和撤单

insert_special_order 返回的非 0 xid 仅表示请求已发送，不表示交易所已接受委托。特殊业务使用独立回调：

回调	处理方式
x1::XLTTradeSpi::on_special_order_insert	记录订单创建和 xid；不应单独将该回调视为交易所接受
x1::XLTTradeSpi::on_special_order_update	根据 report_type 解析 report 联合体，处理申报、撤单和成交回报，并更新 order_status
x1::XLTTradeSpi::on_special_order_error	处理新单或撤单失败，记录 order_error.error_info

这些是消息推送回调，调用特殊业务委托前应已完成 XLTTradeApi::subscribe_trade_message。回调携带 xlt_msg_desc_t，也可通过 sequence 和 is_rebuild 进行断点恢复和去重。

xlt_cancel_order_info_t cancel = {};
cancel.origin_xid = xid;
uint64_t cancel_xid =
    api->cancel_special_order(session_id, &cancel, trade_token);
if (cancel_xid == 0) {
    xlt_error_info_t error = XLTTradeApi::get_last_error();
    // 撤单请求未发送
}

如果已通过 x1::XLTTradeConfig::set_order_seq_self_define 开启自定义订单序号，特殊业务新单和撤单也必须分别填写唯一的 order_sequence。还需注意，不同市场和业务对撤单的支持可能不同，应以当日交易规则及实际回报为准。

断线处理

当连接异常断开时，会触发 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 作为状态收敛依据。
• 控制请求（撤销）需做幂等处理，重复请求应可安全重试。

篮子母单

篮子母单用于一次创建多个相同 algo_type 的算法母单。篮子使用统一的时间和金额等公共参数，每个母单使用独立的市场、证券代码、数量和厂商算法参数。

数据	用途	关键约束
client_basket_id	用户自定义篮子标识	用于请求关联，不代替系统生成的 basket_id
x1::xlt_basket_algo_create_params_t	篮子公共参数	amount 是每个母单的金额上限，不是整个篮子的总额
algo_count	篮子内母单数	最多 3000 个，与 algo_create_params 数组长度一致
x1::xlt_algo_create_params_t 数组	逐母单创建参数	数组元素与母单一一对应
basket_id	系统生成的篮子标识	后续篮子控制和本地状态管理的主键
xlt_algo_id	系统生成的母单标识	篮子内每个母单各有一个，可通过 basket_id 归组

创建示例：

xlt_basket_algo_create_params_t basket_params = {};
std::strcpy(basket_params.start_time, "09:30:00");
std::strcpy(basket_params.end_time, "15:00:00");
basket_params.amount = 100000000;  // 每个母单 10000.0000 元，放大 10000 倍
 
constexpr uint32_t algo_count = 3;
xlt_algo_create_params_t children[algo_count] = {};
const char* security_codes[algo_count] = {"000001", "000002", "000006"};
for (uint32_t i = 0; i < algo_count; ++i) {
    std::strcpy(children[i].start_time, "09:30:00");
    std::strcpy(children[i].end_time, "15:00:00");
    children[i].exchange_index = ExchangeIndex::SZ;
    std::strcpy(children[i].security_code, security_codes[i]);
    children[i].quantity = 1000;
    children[i].frozen_position = false;
    std::strcpy(children[i].params, "{}");  // 按 algo_type 填写厂商算法参数
}
 
uint64_t basket_id = api->basket_algo_create(
    session_id, client_basket_id, algo_type, &basket_params,
    algo_count, children, trade_token, vendor_account_index);
if (basket_id == 0) {
    xlt_error_info_t error = XLTTradeApi::get_last_error();
    // 请求未发送，处理同步错误
}

basket_algo_create 返回非 0 仅表示请求已成功发送，不表示篮子或其中母单已创建成功。用户应同时处理：

1. x1::XLTTradeSpi::on_basket_algo_create_report 返回篮子级创建结果，通过 error_info 判断成功与否。
2. x1::XLTTradeSpi::on_algo_create_report 返回每个母单的创建结果。
3. x1::XLTTradeSpi::on_algo_state 持续返回每个母单的状态；通过 state->algo_info.basket_id 归并篮子状态。
4. 订阅同一账号消息的客户端还可通过 x1::XLTTradeSpi::on_basket_algo_new_create_request 和 x1::XLTTradeSpi::on_algo_new_create_request 同步篮子及逐母单请求。

篮子操作示例：

char params[] = "{}";
uint64_t basket_control_id = api->basket_algo_control(
    session_id, basket_id, client_basket_control_id,
    AlgoControlType::ALGO_CONTROL_CANCEL, params, trade_token);
if (basket_control_id == 0) {
    xlt_error_info_t error = XLTTradeApi::get_last_error();
    // 请求未发送
}

basket_algo_control 会将操作应用到篮子内全部母单。返回的 basket_control_id 仅表示篮子操作请求已发送；当前没有独立的篮子操作结果回调，应使用 x1::XLTTradeSpi::on_algo_control_report 和 x1::XLTTradeSpi::on_algo_state 按 basket_id 汇总每个母单的结果。不要因为某一个母单已进入终态就将整个篮子判定为操作完成。