VeighNa 交易接口(Gateway)完全指南:加载、连接、配置与 21 大交易接口详解
VeighNa 交易接口(Gateway)完全指南:加载、连接、配置与 21 大交易接口详解
VeighNa 是一套基于 Python 的开源量化交易平台开发框架,其核心能力之一便是通过“交易接口(Gateway)”连接各大期货、证券与银行间市场的交易柜台。本文以官方文档为骨架,结合仓库源码,系统讲解交易接口的加载启动、连接配置、合约查询方式,并逐一详解 CTP、飞马、中泰 XTP、盈透证券(IB)等 21 个内置接口的支持范围、配置字段与账号获取途径,帮助你在 VeighNa Trader 图形界面或纯脚本环境中快速接入真实交易通道。
交易接口在 VeighNa 架构中的位置
在 VeighNa 中,交易接口是连接“上层业务引擎”与“底层交易柜台”的桥梁。从源码结构看,所有接口都继承自 vnpy/trader/gateway.py 中定义的抽象基类 BaseGateway,它规定了接口必须实现的抽象方法与事件回调:
- 必须实现的方法:
connect(setting)(建立连接)、close()(断开连接)、subscribe(req)(订阅行情)、send_order(req)(发送委托)、cancel_order(req)(撤销委托)、query_account()(查询资金)、query_position()(查询持仓); - 必须响应的事件回调:
on_tick、on_trade、on_order、on_position、on_account、on_contract,分别对应行情、成交、委托、持仓、资金、合约数据的推送; - 类属性约定:
default_name(接口默认名称)、default_setting(连接所需的配置字段字典)、exchanges(该接口支持的交易所列表)。
每个接口实例在创建时会绑定一个事件引擎,通过 on_event 将各类数据以事件形式推送到平台内部,例如 on_tick 会同时推送通用 EVENT_TICK 事件和带 vt_symbol 的个股事件(见 vnpy/trader/gateway.py)。上层的主引擎 MainEngine(定义于 vnpy/trader/engine.py)维护一个 gateways 字典,通过 add_gateway(gateway_class) 注册接口,并自动把接口声明支持的交易所汇总到全局 exchanges 列表中;connect(setting, gateway_name) 则把配置字典透传给对应接口的 connect 方法完成登录。
加载启动交易接口
在 VeighNa 中加载交易接口有两种方式:图形化的 VeighNa Station 加载,以及脚本加载。
通过 VeighNa Station 加载
启动登录 VeighNa Station 后,点击【交易】按钮,在弹出的配置对话框中的【交易接口】一栏,勾选想要交易的接口即可。Station 会自动生成带有所选接口的启动脚本并拉起 VeighNa Trader。
通过脚本加载
以 CTP 接口为例,在启动脚本中只需两步:
# 写在顶部
from vnpy_ctp import CtpGateway
# 写在创建main_engine对象后
main_engine.add_gateway(CtpGateway)
完整的参考实现在仓库的 examples/veighna_trader/run.py 中:该脚本创建 EventEngine 与 MainEngine 后,通过 main_engine.add_gateway(CtpGateway) 注册 CTP 接口,同时以注释形式列出了 CTP 测试(CtptestGateway)、CTP Mini(MiniGateway)、飞马(FemasGateway)、中泰 XTP(XtpGateway)、华鑫奇点(ToraStockGateway/ToraOptionGateway)、盈透(IbGateway)、易盛外盘(TapGateway)等其余接口的加载写法,需要哪个接口就把对应的 add_gateway 取消注释即可。
值得注意的一个细节是:MainEngine.add_gateway 在未显式传入 gateway_name 时,会直接使用接口类属性 default_name 作为注册名(见 vnpy/trader/engine.py),这也是图形界面中“连接 CTP”等菜单项名称的来源。
连接交易接口
在 VeighNa Trader 图形界面中连接
在图形化操作界面 VeighNa Trader 的菜单栏中点击【系统】->【连接 CTP】,会弹出账号配置窗口。输入账号、密码等相关信息即可连接接口,并立刻进行查询工作:如查询账号信息、查询持仓、查询委托信息、查询成交信息等。查询成功后可在主界面的组件中看到输出的日志。
从 vnpy/trader/ui/mainwindow.py 的源码可以看到,主窗口会遍历主引擎中已注册的全部接口,为每个接口自动生成一个“连接{接口名}”的菜单动作,点击后调用 connect_gateway(gateway_name) 弹出对应的连接配置对话框,因此界面上出现哪些连接菜单项,完全取决于你在启动脚本中 add_gateway 了哪些接口。
修改 json 配置文件
接口配置相关信息保存在 json 文件中,放置在用户目录下的 .vntrader 文件夹内。如果需要修改接口配置文件,用户既可以在图形化界面 VeighNa Trader 内修改,也可以直接在 .vntrader 文件夹下修改对应的 json 文件。
至于为什么配置文件要放在用户目录而不是随项目安装,仓库源码给出了明确的实现依据:在 vnpy/trader/utility.py 中,_get_trader_dir 函数会先检查当前工作目录下是否存在 .vntrader 文件夹,若存在则直接使用;否则回退到系统用户主目录下的 .vntrader,并在不存在时自动创建,同时把该目录追加到 sys.path。也就是说,.vntrader 就是 VeighNa 的全局配置目录,所有接口的 json 配置文件、日志文件等都存放于此。
将 json 配置文件分离于 vnpy 本身的好处在于:避免每次升级 vnpy 都要重新配置 json 文件,升级框架不会影响你已有的账号、密码、服务器地址等连接配置。
无图形界面的脚本连接示例
如果你不使用图形界面,可以参考 examples/no_ui/run.py 的写法:脚本中直接构造 CTP 接口的配置字典,字段与图形界面弹出的配置窗口完全一致,之后调用 main_engine.connect(ctp_setting, "CTP") 即可完成连接,适合部署在服务器上的无人值守场景:
ctp_setting = {
"用户名": "",
"密码": "",
"经纪商代码": "",
"交易服务器": "",
"行情服务器": "",
"产品名称": "",
"授权编码": "",
"产品信息": ""
}
查看可交易的合约
先登录接口,然后在菜单栏中点击【帮助】->【查询合约】,即可弹出空白的【查询合约】窗口,点击【查询】按钮后才会显示查询结果。留空则查询全部合约,也可以输入合约代码(如 rb2210)精确查询指定合约。
该功能在底层对应 BaseGateway.query_contracts() 等查询方法,查询结果通过 on_contract 回调以 ContractData 事件推送到界面。查询合约的意义在于:VeighNa 的委托、行情订阅均以“合约代码 + 交易所”组成的 vt_symbol(形如 rb2210.SHFE)为标识,合约数据是后续下单、计算持仓和转换开平仓方向的基础。
接口分类总览
VeighNa 目前支持 21 大交易接口,覆盖期货、期货期权、ETF 期权、A 股、两融、黄金 TD、银行间市场、外盘期货等多个市场,分类如下:
| 接口 | 类型 |
|---|---|
| CTP | 期货、期货期权(实盘6.5.1) |
| CTP测试 | 期货、期货期权(测试6.5.1) |
| CTP Mini | 期货、期货期权(实盘1.4) |
| 飞马 | 期货 |
| CTP期权 | ETF期权(实盘20190802) |
| 顶点飞创 | ETF期权 |
| 顶点HTS | ETF期权 |
| 恒生UFT | 期货、ETF期权 |
| 易盛 | 期货、黄金TD |
| 中泰XTP | A股、两融、ETF期权 |
| 国泰君安统一交易网关 | A股 |
| 华鑫奇点股票 | A股 |
| 华鑫奇点期权 | ETF期权 |
| 中亿汇达Comstar | 银行间市场 |
| 东方证券OST | A股 |
| 盈透证券 | 海外多品种 |
| 易盛9.0外盘 | 外盘期货 |
| 直达期货 | 外盘期货 |
| 融航 | 期货资管 |
| TTS | 期货 |
| 飞鼠 | 黄金TD |
| 金仕达黄金 | 黄金TD |
接口详解
以下逐一说明各接口的硬件/系统支持范围、交易品种、持仓方向、历史数据能力、连接配置字段及账号获取方式。
CTP
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码
获取账号
- 仿真账号:从 SimNow 网站上获取。只需输入手机号码和短信验证即可(短信验证有时只能在工作日正常工作时段收到)。SimNow 的用户名(InvestorID)为 6 位纯数字,经纪商编号为 9999,并且提供两套环境用于盘中仿真交易以及盘后的测试。需要修改一次密码之后才能使用。请注意每套仿真环境的适用时间段是不同的。
- 实盘账号:在期货公司开户,通过联系客户经理可以开通。用户名为纯数字,经纪商编号也是 4 位纯数字(每个期货公司的经纪商编号都不同)。另外,实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
CTPTEST(CTP 测试)
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码
获取账号:在期货公司开户,通过联系客户经理向期货公司申请进行穿透式接入测试。
MINI(CTP Mini)
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码
获取账号:在期货公司开户,通过联系客户经理可以开通。用户名为纯数字,经纪商编号也是 4 位纯数字(每个期货公司的经纪商编号都不同)。另外,实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
FEMAS(飞马)
接口支持
- 操作系统:Windows
- 交易品种:期货
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码
获取账号:在期货公司开户,通过联系客户经理可以开通。用户名为纯数字,经纪商代码也是 4 位纯数字(每个期货公司的经纪商编号都不同)。另外,实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
SOPT(CTP 期权)
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:ETF期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码
获取账号:在期货公司开户,通过联系客户经理可以开通。用户名为纯数字,经纪商代码也是 4 位纯数字(每个期货公司的经纪商代码都不同)。另外,实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
SEC(顶点飞创)
接口支持
- 操作系统:Windows
- 交易品种:ETF期权
- 持仓方向:股票只支持单向持仓,股票期权只支持双向持仓
- 历史数据:不提供
相关字段:账号、密码、行情地址、交易地址、行情协议(TCP、UDP)、授权码、产品号、采集类型(顶点、恒生、金证、金仕达)、行情压缩(N、Y)
获取账号:在期货公司开户,通过联系客户经理可以开通。
HTS(顶点 HTS)
接口支持
- 操作系统:Windows
- 交易品种:ETF期权
- 持仓方向:双向持仓
- 历史数据:不提供
相关字段:账号、密码、行情地址、交易地址、行情协议(TCP、UDP)、授权码、产品号、采集类型(顶点、恒生、金证、金仕达)、行情压缩(N、Y)
获取账号:在期货公司开户,通过联系客户经理可以开通。
UFT(恒生 UFT)
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:期货、ETF期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、行情服务器、交易服务器、服务器类型(期货、ETF期权)、产品名称、授权编码、委托类型(q)
获取账号:测试账号请通过恒生电子申请。
ESUNNY(易盛)
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:期货、黄金TD
- 持仓方向:支持双向持仓
- 历史数据:不支持
相关字段:行情账号、行情密码、行情服务器、行情端口(默认 0)、行情授权码、交易账号、交易密码、交易服务器、交易端口(默认 0)、交易产品名称、交易授权编码、交易系统(内盘、外盘)
获取账号:测试账号请通过易盛官方网站申请。
XTP(中泰柜台)
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:A股、两融、ETF期权
- 持仓方向:股票只支持单向持仓,其余标的支持双向持仓
- 历史数据:不提供
相关字段:账号、密码、客户号(默认 1)、行情地址、行情端口(默认 0)、交易地址、交易端口(默认 0)、行情协议(TCP、UDP)、日志级别(FATAL、ERROR、WARNING、INFO、DEBUG、TRACE)、授权码
获取账号:测试账号请通过中泰证券申请。
其他特点:XTP 是首家提供融资融券的极速柜台。
HFT(国泰君安统一交易网关)
接口支持
- 操作系统:Windows
- 交易品种:A股
- 持仓方向:只支持单向持仓
- 历史数据:不提供
相关字段:交易用户名、交易密码、交易服务器、交易端口、机构代号、营业部代号、网关、行情用户名、行情密码、行情服务器、行情端口
获取账号:测试账号请通过国泰君安申请。
TORASTOCK(华鑫奇点股票)
接口支持
- 操作系统:Windows
- 交易品种:A股
- 持仓方向:只支持单向持仓
- 历史数据:不提供
相关字段:账号、密码、行情服务器、交易服务器、账号类型(用户代码、资金账号)、地址类型(前置地址、FENS地址)
获取账号:测试账号请通过华鑫证券申请。
TORAOPTION(华鑫奇点期权)
接口支持
- 操作系统:Windows
- 交易品种:ETF期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:账号、密码、行情服务器、交易服务器、账号类型(用户代码、资金账号)、地址类型(前置地址、FENS地址)
获取账号:测试账号请通过华鑫证券申请。
COMSTAR(中亿汇达)
接口支持
- 操作系统:Windows
- 交易品种:银行间市场
- 持仓方向:无
- 历史数据:不提供
相关字段:交易服务器、用户名、密码、Key、routing_type(默认 5)、valid_until_time(默认 18:30:00.000)
获取账号:只有各类大型金融机构才能用(券商自营交易部、银行金融市场部等),私募或者个人都用不了。需要购买 ComStar 的交易接口服务之后才能使用。
OST(东方证券)
接口支持
- 操作系统:Windows
- 交易品种:A股
- 持仓方向:单向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、上交所快照地址、上交所快照端口(默认 0)、深交所快照地址、深交所快照端口(默认 0)、本机 ip 地址
获取账号:在证券公司开户,通过联系客户经理可以开通。
IB(盈透证券)
接口支持
- 操作系统:Windows、Ubuntu、Mac
- 交易品种:海外多品种
- 持仓方向:只支持单向持仓
- 历史数据:提供(是各接口中少数提供历史数据的接口)
相关字段:TWS 地址(默认 127.0.0.1)、TWS 端口(默认 7497)、客户号(默认 1)、交易账户
获取账号:在盈透证券开户并且入金后可以获得 API 接入权限。
其他特点
可交易品种覆盖诸多海外市场的股票、期权、期货;手续费相对较低。
请注意,IB 接口的合约代码较为特殊,请前往官网的产品查询板块查询。VeighNa Trader 中使用的是盈透证券对于每个合约在某一交易所的唯一标识符 ConId 来作为合约代码,而非 Symbol 或者 LocalName。
TAP(易盛 9.0 外盘)
接口支持
- 操作系统:Windows
- 交易品种:外盘期货
- 持仓方向:只支持单向持仓
- 历史数据:不提供
相关字段:行情账号、行情密码、行情服务器、行情端口(默认 0)、交易账号、交易密码、交易服务器、交易端口(默认 0)、授权码
获取账号:测试账号请通过易盛官方网站申请。
DA(直达期货)
接口支持
- 操作系统:Windows
- 交易品种:外盘期货
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、行情服务器、授权码
获取账号:在直达期货开户并且入金后可以获得 API 接入权限。
ROHON(融航)
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:期货资管
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码
获取账号:测试账号请通过融航申请。
请注意,融航接口的【经纪商代码】不再是纯数字形态,而是可以包含英文和数字的字符串;VeighNa 连接融航进行交易在穿透式认证中属于【中继】模式,而不再是连接柜台(CTP、恒生等)进行交易时的【直连】模式,所以在申请穿透式认证测试填表时不要选错。
TTS
接口支持
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码
获取账号:请通过 OpenCTP 平台获取。
SGIT(飞鼠)
接口支持
- 操作系统:Ubuntu
- 交易品种:黄金TD
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、行情服务器、产品名称、授权编码
获取账号:请通过黄金现货经纪商获取。
KSGOLD(金仕达黄金)
接口支持
- 操作系统:Ubuntu
- 交易品种:黄金TD
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、行情服务器、账号类型(银行账号、黄金账号)
获取账号:请通过黄金现货经纪商获取。
连接后的数据流:接口如何与主引擎协同
连接成功后,接口会立刻执行合约、资金、持仓、委托、成交的查询,并通过事件机制持续推送数据。在 vnpy/trader/engine.py 的 OmsEngine 中,这些事件会被统一收编:process_tick_event 按 vt_symbol 缓存最新行情,process_order_event 按 vt_orderid 维护委托状态并同步活动委托表,process_position_event 与 process_trade_event 还会驱动开平仓方向转换器 OffsetConverter 的更新。这意味着上层 CTA、价差、算法等策略模块只需面向统一的 MainEngine 接口编程,而无需关心底层连接的是 CTP 还是 XTP、是内盘还是外盘——这正是交易接口抽象层设计的价值所在。
小结
交易接口是 VeighNa 连接真实市场的入口。本文完整梳理了从加载启动(Station 勾选或脚本 add_gateway)、连接配置(图形界面或 .vntrader 下的 json 文件)、合约查询到 21 大接口逐一详解的完整链路,并结合 vnpy/trader/gateway.py 的 BaseGateway 抽象基类与 vnpy/trader/engine.py 的主引擎实现,说明了接口“加载即注册、连接即查询、回调即推送”的底层工作方式。无论你是准备接入仿真环境验证策略,还是对接实盘柜台投入生产,都可按上述步骤选择对应接口完成接入。