 |
Xlight API用户手册 v1.7.0.16
Xlight极速柜台接口文档
|
|
Xlight API用户手册 v1.7.0.16
Xlight极速柜台接口文档
|
本文面向算法厂商侧开发，描述厂商接入 Xlight 算法母单能力时的接口、流程与状态约定。
| 参与方 | 核心职责 | 关键接口/回调 |
|---|---|---|
| 用户侧（User） | 发起算法母单或篮子母单的创建与操作 | x1::XLTTradeApi::algo_create, x1::XLTTradeApi::algo_control, x1::XLTTradeApi::basket_algo_create, x1::XLTTradeApi::basket_algo_control |
| 管理侧（Privilege） | 账户管理、请求路由、状态分发 | |
| 厂商侧（Vendor） | 注册算法、处理请求、上报执行结果、查询和恢复母单状态 | x1::XLTTradeApi::vendor_algo_register, x1::XLTTradeSpi::on_vendor_basket_algo_create_request, x1::XLTTradeSpi::on_vendor_basket_algo_control_request, x1::XLTTradeApi::vendor_submit_algo_exec_report, x1::XLTTradeApi::vendor_query_algo_state, x1::XLTTradeApi::vendor_query_algo_state_ex |
算法厂商服务接入前，需先完成以下准备：
vendor_account_index）。algo_type。algo_type（XLTTradeApi::vendor_algo_register），注册成功后才能接收对应算法母单请求。运行期基础动作建议如下：
下图从厂商视角抽取了核心链路：登录/订阅/注册 -> 处理创建请求 -> 执行交易 -> 处理控制请求。
厂商可以使用以下两组接口查询已存在的母单：
两种查询都要求传入 algo_type；xlt_algo_id 传入具体母单 ID 时查询单个母单，传入 0 时查询该算法类型下的全部母单。查询请求立即返回发送结果，实际数据通过对应回调异步返回。回调中的列表通过 data_count() 和 get(i) 访问，is_last 为 false 时还会有后续批次。
xlt_algo_state_ex_t 在普通状态信息的基础上增加 create_params，包含开始/结束时间、市场、证券代码、数量及厂商定义的 params JSON 等创建信息。厂商应在回调中拷贝需要异步使用的数据，不要保存列表或元素指针。
篮子母单是一组 algo_type 相同、证券和逐母单参数可不同的算法母单。厂商侧会收到两层消息：
| 层级 | 创建 | 操作 | 处理职责 |
|---|---|---|---|
| 篮子级 | x1::XLTTradeSpi::on_vendor_basket_algo_create_request | x1::XLTTradeSpi::on_vendor_basket_algo_control_request | 建立篮子上下文，记录公共参数、algo_count 和 xlt_algo_ids |
| 母单级 | x1::XLTTradeSpi::on_vendor_algo_create_request | x1::XLTTradeSpi::on_vendor_algo_control_request | 逐个创建/操作策略实例，并逐个上报执行结果 |
收到篮子级创建回调后，厂商会继续收到 algo_count 个逐母单创建回调；收到篮子级操作回调后，会继续收到对应的逐母单操作回调。篮子级回调是分组和预处理通知，不替代逐母单回调；厂商仍使用 x1::XLTTradeApi::vendor_submit_algo_exec_report 对每个 xlt_algo_id 分别上报结果，不需要另外上报篮子级执行结果。
xlt_basket_algo_create_request_t::xlt_algo_ids 和 xlt_basket_algo_control_request_t::xlt_algo_ids 是柔性数组，有效元素数为 basket_algo_info.algo_count。如果需要异步处理，应在回调返回前拷贝篮子信息、参数和 ID 列表，不要保存回调入参指针。
执行类型来自 AlgoExecType，建议状态映射来自 algo_v1_7.md。
| ExecType | 建议目标状态 | 说明 |
|---|---|---|
ALGO_EXEC_NEW | CREATED | 母单创建成功 |
ALGO_EXEC_NEW_REJECT | REJECTED | 母单创建被拒绝 |
ALGO_EXEC_START | STARTED | 母单进入运行 |
ALGO_EXEC_CONTROL | CANCELED（按操作语义） | 常见是撤单成功 |
ALGO_EXEC_CONTROL_REJECT | 保持原状态 | 常见是撤单被拒 |
ALGO_EXEC_FINISH | FINISHED | 母单正常完成 |
ALGO_EXEC_ABORT | ABORTED | 母单异常中止 |
| 回调 | 场景 | 厂商处理建议 |
|---|---|---|
| x1::XLTTradeSpi::on_vendor_algo_create_request | 收到新母单创建请求 | 校验参数并尽快上报创建结果 |
| x1::XLTTradeSpi::on_vendor_algo_control_request | 收到母单操作请求（当前为撤单） | 幂等处理，明确成功/失败结果 |
| x1::XLTTradeSpi::on_vendor_basket_algo_create_request | 收到篮子创建上下文 | 按 basket_id 建立分组，记录 algo_count 与母单 ID 列表，等待逐母单回调 |
| x1::XLTTradeSpi::on_vendor_basket_algo_control_request | 收到篮子操作上下文 | 记录篮子操作 ID 和目标母单集合，按逐母单结果收敛 |
| x1::XLTTradeSpi::on_vendor_algo_state | 算法管理系统状态通知（每次母单状态变动触发） | 以管理平台状态为准更新本地状态：按 xlt_algo_id 迁移状态机；若与本地推导不一致则以回调为准并记录对账日志；对跳变/回退告警；落库状态变更时间与来源用于恢复追溯 |
| x1::XLTTradeSpi::on_vendor_query_algo_state | 查询母单状态 | 按 request_id 关联查询请求，遍历列表并处理多批响应；以 is_last 判断查询结束 |
| x1::XLTTradeSpi::on_vendor_query_algo_state_ex | 查询母单状态及创建参数 | 在恢复本地上下文时同时保存 xlt_algo_state_ex_t::create_params，并按 is_last 判断查询结束 |
| x1::XLTTradeSpi::on_auth_trade | 厂商授权响应 | 缓存 trade_token 并绑定会话 |
| x1::XLTTradeSpi::on_order_response | 委托确认 | 记录订单生命周期起点 |
| x1::XLTTradeSpi::on_trade_report | 成交回报 | 驱动算法执行进度与风控 |
| x1::XLTTradeSpi::on_order_error_response | 委托失败 | 及时上报 ALGO_EXEC_ABORT 或控制类失败 |
xlt_algo_id 建立唯一上下文，保证创建/操作/状态上报串行有序。on_vendor_algo_control_request 做幂等设计，避免重复操作导致状态抖动。ALGO_EXEC_ABORT，并附带可追踪的错误原因。basket_id -> xlt_algo_ids 建立双向索引，但仍以 xlt_algo_id 作为执行和上报的最小单元。algo_count 不一致时告警，不要静默忽略缺失母单。vendor_query_algo_state_ex 补齐状态和创建参数，再接收实时状态通知；查询结果按 request_id 去重并支持多批次收敛。 
1.11.0