使用指南

本文档详细介绍如何使用xlt_api进行交易和行情接收。

初始化

创建API实例

使用 x1::XLTApi::create() 创建全局唯一的API实例：

using namespace x1;
XLTApi *api = XLTApi::create();

注意：API实例只能创建一次，在整个程序生命周期内使用同一个实例。

配置API

创建 x1::XLTApiConfig 对象并设置必要的配置参数。

配置项说明

以下是 x1::XLTApiConfig 类提供的所有配置接口：

配置项	配置接口	是否必填	配置样例	说明
设置交易日	set_trading_day()	必填	config.set_trading_day(20240320);	格式YYYYMMDD。用户需明确指定交易日，生产环境为当前交易日，测试环境为测试柜台的交易日
设置本地网卡IP	set_local_addr()	必填	config.set_local_addr("192.168.5.155", "192.168.2.155", "192.168.3.155");	需指定连接AGW、报单、行情接收的三个网卡IP。建议为solarflare网卡
添加网关地址	add_agw_addr()	必填	config.add_agw_addr("222.71.197.227", 60601);	请向券商获取AGW地址和端口，可重复调用添加多个AGW地址，每次登录会随机选取当前可用的AGW
设置文件路径	set_path()	选填	config.set_path(".");	存放API生成的文件路径，如日志文件等。默认为当前路径
设置日志级别	set_log_level()	选填	config.set_log_level(ApiLogLevel::LOG_INFO);	设置日志级别。默认为info级别
设置请求超时	set_request_timeout()	选填	config.set_request_timeout(10);	单位秒。查询超时将触发on_request_timeout
设置订单超时	set_order_timeout()	选填	config.set_order_timeout(10);	单位秒。委托超时将触发on_order_timeout
设置内存池大小	set_memory_pool_size()	选填	config.set_memory_pool_size(256, 8, 32);	单位MB。包括交易、level1、level2行情内存池。预留接口，当前版本暂不支持调整
自定义订单序号	set_order_seq_self_define()	选填	config.set_order_seq_self_define(true);	默认情况下，API会自动生成订单序号；若启用，用户必须确保每次下单时order_sequence字段值唯一
行情单线程模式	receive_quote_in_single_thread()	选填	配置样例	level1、上海level2、深圳level2分别在独立线程运行
行情快照逐笔模式	receive_quote_in_snap_tick_thread()	选填	配置样例	level1、上海level2快照、上海level2逐笔、深圳level2快照、深圳level2逐笔分别在独立线程运行
行情分类型模式	receive_quote_in_channel_per_thread()	选填	配置样例	level1及上海、深圳level2各行情类型分别在独立线程运行，粒度最细

注意：行情接收配置的三个方法（ x1::XLTApiConfig::receive_quote_in_single_thread() 、 x1::XLTApiConfig::receive_quote_in_snap_tick_thread() 、 x1::XLTApiConfig::receive_quote_in_channel_per_thread() ）调用其中一个即可，若都调用以最后一次调用为准。

配置示例

using namespace x1;
XLTApiConfig config;
 
// 必填：设置交易日，格式YYYYMMDD
config.set_trading_day(20240320);
 
// 必填：设置本地网卡IP地址
config.set_local_addr(
    "192.168.5.155",  // AGW网卡IP
    "192.168.5.155",  // 交易网卡IP
    "192.168.5.155"   // 行情网卡IP
);
 
// 必填：添加网关地址
config.add_agw_addr("222.71.197.227", 60601);
 
// 选填：设置日志路径
config.set_path(".");
 
// 选填：设置日志级别
config.set_log_level(ApiLogLevel::LOG_INFO);
 
// 选填：设置请求超时时间（秒）
config.set_request_timeout(10);
 
// 选填：设置订单超时时间（秒）
config.set_order_timeout(10);

实现回调类

继承 x1::XLTTradeSpi 类实现交易回调：

using namespace x1;
 
class MyTradeSpi : public XLTTradeSpi {
public:
    void on_login(uint64_t session_id, uint64_t request_id, 
                  xlt_error_info_t *error_info) override {
        // 处理登录响应
    }
    
    void on_order_response(uint64_t session_id, 
                          xlt_order_response_t *order_response) override {
        // 处理订单申报响应
    }
    
    void on_trade_report(uint64_t session_id, 
                        xlt_trade_report_t *trade_report) override {
        // 处理成交回报
    }
    
    void on_order_end(uint64_t session_id, 
                     xlt_order_end_t *order_end) override {
        // 处理订单结束通知
    }
    
    // 实现其他必要的回调函数...
};

如果需要接收行情，还需要继承 x1::XLTQuoteSpi 或 x1::EFHQuoteSpi 类。

初始化API

调用 x1::XLTApi::initialize() 方法初始化API：

using namespace x1;
XLTApi *api;
 
MyTradeSpi trade_spi;
XLTQuoteSpi *quote_spi = nullptr;  // 如果不需要行情，可以传nullptr
 
if (!api->initialize(&config, &trade_spi, quote_spi)) {
    // 初始化失败，获取错误信息
    auto error_info = api->get_last_error();
    printf("初始化失败: %s\n", error_info.error_msg);
    return -1;
}

注意：API只能初始化一次，必须在登录之前调用。

登录

调用 x1::XLTApi::login() 方法登录交易账户：

using namespace x1;
XLTApi *api;
 
uint64_t request_id = 1;  // 请求ID，用于定位响应
uint16_t client_id = 1;    // 客户端标识ID，取值范围[0, 255]
const char *account_name = "00700000010001";
const char *password = "12345678"; 
const char *pub_key = "XXXXXXXXXXXXXX";  // 用户公钥，预留字段，当前版本无意义
 
if (!api->login(request_id, client_id, account_name, password, pub_key)) {
    // 登录请求发送失败
    auto error_info = api->get_last_error();
    printf("登录请求失败: %s\n", error_info.error_msg);
    return -1;
}
 
// 等待登录响应（在on_login回调中处理）

登录响应通过 x1::XLTTradeSpi::on_login() 回调函数异步返回。登录成功后，会返回一个 session_id，后续所有接口调用都需要使用此 session_id。

交易

订阅交易数据

登录成功后，需要订阅交易数据才能收到订单回报, x1::XLTApi::subscribe_report() ：

using namespace x1;
XLTApi *api;
 
// 订阅交易数据
api->subscribe_report(session_id, TradeResumeType::QUICK, 0);

下单

调用 x1::XLTApi::insert_order() 方法下单：

using namespace x1;
XLTApi *api;
 
xlt_order_insert_info_t order_info = {};
strcpy(order_info.security_code, "600010");  // 证券代码
order_info.exchange_index = ExchangeIndex::SH;  // 交易市场
order_info.price = 100000;  // 委托价格，放大1万倍（即10.00元）
order_info.quantity = 100;  // 委托数量
order_info.order_type = OrderType::LIMIT_PRICE;  // 限价委托
order_info.side = Side::BUY;  // 买入
order_info.business_type = BusinessType::CASH;  // 股票现货
 
uint64_t xid = api->insert_order(session_id, &order_info);
if (xid == 0) {
    // 下单失败
    auto error_info = api->get_last_error();
    printf("下单失败: %s\n", error_info.error_msg);
}

撤单

调用 x1::XLTApi::cancel_order() 方法撤单：

using namespace x1;
XLTApi *api;
 
xlt_cancel_order_info_t cancel_info = {};
cancel_info.origin_xid = xid;  // 要撤销的订单xid
 
uint64_t cancel_xid = api->cancel_order(session_id, &cancel_info);
if (cancel_xid == 0) {
    // 撤单失败
    auto error_info = api->get_last_error();
    printf("撤单失败: %s\n", error_info.error_msg);
}

回报

订单的回报通过以下回调函数接收：

• x1::XLTTradeSpi::on_order_response() ：订单申报成功响应
• x1::XLTTradeSpi::on_trade_report() ：成交回报（可能多次）
• x1::XLTTradeSpi::on_cancel_response() ：撤单成功响应
• x1::XLTTradeSpi::on_order_end() ：订单结束通知
• x1::XLTTradeSpi::on_order_error_response() ：委托失败通知（包括拒单、废单、撤单失败等）

交易消息流

委托全部成交

1. 调用 x1::XLTApi::insert_order() 发送报单请求
2. 收到 x1::XLTTradeSpi::on_order_response() 回调，表示订单申报成功
3. 订单成交时，会多次收到 x1::XLTTradeSpi::on_trade_report() 回调（每笔成交一次）
4. 订单全部成交后，收到 x1::XLTTradeSpi::on_order_end() 回调

委托失败

1. 调用 x1::XLTApi::insert_order() 发送报单请求
2. 收到 x1::XLTTradeSpi::on_order_error_response() 回调，包含错误信息

委托全部撤单

1. 调用 x1::XLTApi::cancel_order() 发送撤单请求
2. 收到 x1::XLTTradeSpi::on_cancel_response() 回调，表示撤单成功
3. 原订单到达终结状态，收到 x1::XLTTradeSpi::on_order_end() 回调

委托部分撤单

1. 调用 x1::XLTApi::cancel_order() 发送撤单请求
2. 收到 x1::XLTTradeSpi::on_cancel_response() 回调，表示撤单成功
3. 原订单到达终结状态，收到 x1::XLTTradeSpi::on_order_end() 回调

撤单失败

1. 调用 x1::XLTApi::cancel_order() 发送撤单请求
2. 收到 x1::XLTTradeSpi::on_order_error_response() 回调，包含错误信息

查询

查询资金

调用 x1::XLTApi::query_assets() 方法查询资金信息：

using namespace x1;
XLTApi *api;
 
uint64_t request_id = next_request_id();
if (!api->query_assets(session_id, request_id)) {
    auto error_info = api->get_last_error();
    printf("查询资金失败: %s\n", error_info.error_msg);
}

查询结果通过 x1::XLTTradeSpi::on_query_assets() 回调函数返回。

查询持仓

调用 x1::XLTApi::query_positions() 方法查询持仓信息：

using namespace x1;
XLTApi *api;
 
char security_code[CONST_STR_SECURITY_CODE_LEN] = "";  // 空字符串表示查询所有持仓
uint64_t request_id = next_request_id();
 
if (!api->query_positions(session_id, request_id, security_code, 
                          ExchangeIndex::INIT, 0)) {
    auto error_info = api->get_last_error();
    printf("查询持仓失败: %s\n", error_info.error_msg);
}

查询结果通过 x1::XLTTradeSpi::on_query_positions() 回调函数返回。

查询订单

调用 x1::XLTApi::query_orders() 方法查询订单：

using namespace x1;
XLTApi *api;
 
xlt_order_query_param_t query_param = {};
query_param.xid = 0;  // 0表示按条件查询
strcpy(query_param.security_code, "000001");  // 证券代码
 
uint64_t request_id = next_request_id();
if (!api->query_orders(session_id, request_id, &query_param)) {
    auto error_info = api->get_last_error();
    printf("查询订单失败: %s\n", error_info.error_msg);
}

查询结果通过 x1::XLTTradeSpi::on_query_orders() 回调函数返回。

分页查询订单

调用 x1::XLTApi::query_orders_by_page() 方法分页查询订单：

using namespace x1;
XLTApi *api;
 
xlt_query_by_page_param_t page_param = {};
page_param.req_count = 100;  // 每页数量
page_param.reference = 0;  // 首次查询为0，后续使用上次返回的query_reference
 
uint64_t request_id = next_request_id();
if (!api->query_orders_by_page(session_id, request_id, &page_param)) {
    auto error_info = api->get_last_error();
    printf("分页查询订单失败: %s\n", error_info.error_msg);
}

查询结果通过 x1::XLTTradeSpi::on_query_orders_by_page() 回调函数返回。

查询成交

调用 x1::XLTApi::query_trades() 方法查询成交：

using namespace x1;
XLTApi *api;
 
uint64_t xid = 12345;  // 要查询的订单xid，0表示查询所有成交
uint64_t request_id = next_request_id();
 
if (!api->query_trades(session_id, request_id, xid)) {
    auto error_info = api->get_last_error();
    printf("查询成交失败: %s\n", error_info.error_msg);
}

查询结果通过 x1::XLTTradeSpi::on_query_trades() 回调函数返回。

行情

行情配置

若需要使用行情，请确保在初始化API时， x1::XLTApiConfig 已配置行情接收， 以下三个之一：

• x1::XLTApiConfig::receive_quote_in_single_thread() ：行情单线程模式
• x1::XLTApiConfig::receive_quote_in_snap_tick_thread() ：行情快照逐笔模式
• x1::XLTApiConfig::receive_quote_in_channel_per_thread() ：行情分类型模式

参见 配置API 和 行情线程

实现回调类

如果需要接收Level1行情，继承 x1::XLTQuoteSpi 类：

using namespace x1;
 
class MyQuoteSpi : public XLTQuoteSpi {
public:
    void on_sse_l1_snapshot(const sse_l1_snapshot_t *snapshot) override {
        // 处理上交所Level1快照行情
    }
    
    void on_szse_l1_snapshot(const szse_l1_snapshot_t *snapshot) override {
        // 处理深交所Level1快照行情
    }
    
    // 实现其他行情回调函数...
};

如果需要接收Level2行情，继承 x1::EFHQuoteSpi 类：

using namespace x1;
 
class MyEFHQuoteSpi : public EFHQuoteSpi {
public:
    void on_report_efh_sse_lev2_snap(const sse_hpf_lev2 *p_snap) override {
        // 处理上交所Level2快照
    }
    
    void on_report_efh_sse_lev2_tick_merge(const sse_hpf_tick_merge *p_tick) override {
        // 处理上交所Level2逐笔合并
    }
    
    // 实现其他Level2行情回调函数...
};

行情代码订阅

订阅行情时可以设置订阅代码， x1::XLTApi::subscribe_quote() 或者 x1::XLTApi::subscribe_all_quote()

using namespace x1;
XLTApi *api;
 
// 订阅指定证券代码的行情
api->subscribe_quote(ExchangeIndex::SH, "000072");
 
// 订阅全市场行情
api->subscribe_all_quote(ExchangeIndex::SZ);

启动行情接收

登录成功后，调用 x1::XLTApi::start_quote() 启动行情接收：

using namespace x1;
XLTApi *api;
 
if (!api->start_quote(session_id)) {
    auto error_info = api->get_last_error();
    printf("启动行情接收失败: %s\n", error_info.error_msg);
}

行情接收启动结果通过 x1::XLTQuoteSpi::on_start_quote() 回调函数返回。