MT5CTP3 开发手册

MT5CTP（API 3.00）采用全新四层架构，提供与 MQL5 原生函数完全兼容的统一交易接口。本手册面向使用 MQL5 语言开发期货、证券量化策略的开发者。

本手册能做什么

帮助 MQL5 开发者快速理解 MT5CTP3 的架构设计与接口层次
指导如何配置开发环境、编写第一个可运行的 CTP 报单脚本
详细说明同步/异步报单、条件单、CTP 原生报单、IPO 申购等交易指令
介绍合约、账户、持仓（双模型）、订单、成交的查询方法
提供 48 个示例脚本的完整索引与使用场景

核心特性

MQL5 原生兼容：SymbolInfoDouble、AccountInfoInteger、PositionsTotal 等函数签名与 MT5 原生一致，已有策略代码近乎零改动迁移
同步/异步双报单：同步指令与 MQL 使用习惯和执行规则完全一致；异步指令无阻塞、速度快，适合高频场景
双持仓模型：同时支持 MT5 风格分笔持仓与 CTP 风格汇总持仓
多账户支持：通过账户句柄参数实现单策略多账户交易
期货+证券扩展：uni.mqh 扩展了证券报单类型（IPO、ETF 申赎、融资融券等）与字段枚举
AI 驱动入口：通过 MCP 服务，外部 AI Agent 可调用交易工具完成查询与报单闭环（详见产品介绍页）

环境准备

1. 安装 MT5CTP3 组件

参考下载安装页面，将社区版压缩包解压到合适位置。社区版已包含：

MetaTrader 5 客户端
MT5CTP3 接口库（mt5ctp.dll 等）
官方示例脚本
VC++ 运行时安装包

2. 确认核心库文件

打开 MT5 客户端数据目录，确认 MQL5\Include\uni\ 目录下存在三个核心库文件：

文件	层级	说明
`mt5ctp.mqh`	接口封装层	`uni` 命名空间，MQL5 兼容函数签名
`uni.mqh`	常量扩展层	证券报单类型、字段枚举补充定义
`Trade.mqh`	高级封装层	`CTrade` 类，同步/异步交易

3. 安装 VC++ 运行时

若专家日志提示无法引导 mt5ctp.dll 关联函数，请安装 VC++ 运行时库（见下载安装）。

快速上手：第一个脚本

下面是一个最简的同步市价买入脚本。将代码保存为 MQL5\Scripts\FirstBuy.mq5 并编译运行。

// MT5CTP生产环境标识 | 历史数据测试需要注释掉该标识
#define __MT5CTP__
#include <uni\mt5ctp.mqh>
#include <uni\Trade.mqh>

void OnStart()
{
   // 创建交易对象
   CTrade trade;
   trade.LogLevel(LOG_LEVEL_ALL);           // 日志级别
   trade.SetExpertMagicNumber(123456);      // Magic 标识

   // 市价买入开仓 1 手
   bool bRet = trade.Buy(1,                 // 报单数量
                         NULL,              // 合约代码，空为图表合约
                         0.0,               // 保护性价格，0.0 默认对手价
                         0.0,               // 止损价
                         0.0,               // 止盈价
                         "",                // 报单注释
                         0);                // 账户句柄，单账户用默认值

   Print("报单执行结果：", bRet);
}

关键要点

#define __MT5CTP__ 必须写在 #include 之前。定义该标识时调用 MT5CTP 接口直连 CTP 柜台；注释掉后回退为 MT5 客户端原生 API，可用于历史数据回测。
同步报单仅支持 FOK 和 IOC(FAK) 指令，默认 FOK（全部成交，否则撤销）。
市价报单的保护性价格为 0.0 时，系统默认使用对手价；不支持市价单的交易所会转为 FOK 限价单。

手册目录

章节	内容
架构说明	四层架构、命名空间设计、`__MT5CTP__` 编译标识、数据流向
交易指令	CTrade 同步/异步报单、条件单、CTP 原生报单、IPO 申购、多账户、错误码与事件回调
信息查询	合约、账户、持仓（双模型）、订单、成交查询与性能计量
示例程序	48 个官方示例脚本索引（交易/合约/持仓/订单/账户/合规测试）

开发调试建议

先在 SimNow 仿真环境验证：所有策略上线前，建议在 SimNow 仿真环境（www.simnow.com.cn）完成充分测试。
使用微秒级计时：示例脚本内置 GetMicrosecondCount() 高精度计时，便于评估报单与查询链路性能。
关注错误码：异步报单需通过 trade.ResultRetcode() 获取真实回报码，不能仅依赖 Buy/Sell 返回的布尔值。
日志留痕：生产环境建议设置合适的日志级别，保留完整交易记录以满足合规审计要求。

MT5CTP3 开发手册 ​

本手册能做什么 ​

核心特性 ​

环境准备 ​

1. 安装 MT5CTP3 组件 ​

2. 确认核心库文件 ​

3. 安装 VC++ 运行时 ​

快速上手：第一个脚本 ​

手册目录 ​

开发调试建议 ​

相关资源 ​