vn.py 交易接口(Gateway)完全指南:加载、连接、配置与 21 大接口详解
vn.py 交易接口(Gateway)完全指南:加载、连接、配置与 21 大接口详解
交易接口(Gateway)是 vn.py 交易平台连接各类交易系统的核心桥梁:无论是 CTP 期货柜台、中泰 XTP 极速柜台,还是盈透证券海外账户,都必须通过对应 Gateway 才能完成行情订阅、委托发送与持仓查询。本指南以官方文档 gateway.md 为主线,结合仓库源码(gateway.py、engine.py)与运行示例,系统讲解 Gateway 的加载启动、图形化/脚本化连接、配置文件管理,并逐一详解 CTP、飞马、XTP、盈透等 21 大交易接口的支持范围、配置字段与账号获取方式,读完后你将能独立完成任意受支持柜台在 vn.py 中的接入与交易。
一、什么是交易接口(Gateway)
在 vn.py 的架构中,BaseGateway 是定义在 vnpy/trader/gateway.py 的抽象基类,它规定了所有交易接口必须实现的统一行为契约。从源码可以看到,每个 Gateway 至少要满足:
- 线程安全:所有方法必须线程安全,对象间不共享可变属性;
- 非阻塞:所有方法不得阻塞调用方线程;
- 自动重连:连接断开后需自动重连;
- 回调驱动:必须主动回调
on_tick、on_trade、on_order、on_position、on_account、on_contract等事件。
每个 Gateway 子类还需要声明三个关键类属性(见 gateway.py):
| 类属性 | 作用 |
|---|---|
default_name |
接口默认名称,如 CTP,用于在引擎中注册与标识 |
default_setting |
连接该接口所需配置字段(字段名、类型与默认值),驱动图形界面表单动态生成 |
exchanges |
该接口支持的交易所列表,注册时自动合并进引擎全局交易所列表 |
而真正的交易行为则通过 connect、close、subscribe、send_order、cancel_order、query_account、query_position 等抽象方法完成。需要说明的是,具体柜台 Gateway(如 vnpy_ctp 中的 CtpGateway)是以独立 Python 包形式发布、与主程序解耦的,本文仓库内的核心框架提供了承载这些 Gateway 的引擎与界面。
二、加载启动:让平台认识交易接口
使用某个交易接口前,必须先将其加载到主引擎(MainEngine)中。vn.py 提供两种加载方式。
2.1 通过 VeighNa Station 勾选加载
启动登录 VeighNa Station 后,点击【交易】按钮,在弹出的配置对话框中的【交易接口】栏勾选想要交易的接口即可。这种方式适合不熟悉代码的用户,本质上是 VeighNa Station 在生成启动脚本时自动帮你完成了 add_gateway 调用。
2.2 通过脚本加载(add_gateway)
以 CTP 接口为例,在启动脚本中添加如下代码(完整示例见 examples/veighna_trader/run.py):
# 写在顶部
from vnpy_ctp import CtpGateway
# 写在创建main_engine对象后
main_engine.add_gateway(CtpGateway)
从源码看,MainEngine.add_gateway(engine.py)会完成三件事:
- 若未显式传入
gateway_name,则使用gateway_class.default_name(如 "CTP")作为注册名; - 以
(event_engine, gateway_name)实例化 Gateway 对象,并存入self.gateways字典; - 将该 Gateway 支持的交易所合并进
MainEngine.exchanges全局交易所列表。
在 examples/veighna_trader/run.py 中可以看到,飞马、SOPT、易盛、XTP、Tora、盈透、TAP、直达、融航、TTS 等接口都被注释列出,需要哪个接口就取消对应 add_gateway 行的注释。通过 main_engine.get_all_gateway_names()(engine.py)可以随时查看当前已加载的全部接口名。
三、连接接口:从图形界面到登录成功
3.1 图形界面操作流程
在图形化操作界面 VeighNa Trader 的菜单栏中点击【系统】->【连接CTP】,会弹出账号配置窗口,输入账号、密码等相关信息即可连接接口。连接建立后,平台会立刻进行查询工作:查询账号信息、查询持仓、查询委托信息、查询成交信息等。查询成功后可在主界面的组件中看到输出的日志。
这一过程的源码实现值得注意:VeighNa Trader 主窗口的【系统】菜单并不是写死的,而是遍历 main_engine.get_all_gateway_names() 动态生成“连接XX”菜单项(见 ui/mainwindow.py),这就是为什么加载了哪些接口,菜单里就会出现哪些连接入口。点击菜单项后,会弹出 ConnectDialog 连接对话框(ui/widget.py),该对话框根据 default_setting 动态生成表单控件:
- 字段默认值为
list类型时,渲染为下拉框(如行情协议 TCP/UDP、日志级别等); - 字段名包含“密码”时,输入框自动切换为密码回显模式;
- 字段为
int类型时,输入框自动绑定整数校验器; - 输入内容会保存到本地,下次打开时自动回填上次使用的配置。
确认连接后,MainEngine.connect(setting, gateway_name)(engine.py)会调用对应 Gateway 的 connect(setting) 抽象方法,Gateway 内部完成与柜台服务器的建连、登录,并推送行情、委托、成交等事件(on_tick、on_order、on_trade、on_position、on_account、on_contract,见 gateway.py)。依据 gateway.py 中 connect 方法的接口约定,实现时除建立连接并输出连接成功日志外,还必须完成合约、资金、持仓、委托、成交的查询并通过 on_xxxx 回调与 write_log 反馈结果——这正是“连接后立刻查询”这一行为的来源。
3.2 无图形界面的脚本连接
对于部署在服务器上的无人值守场景,可以在脚本中直接构造配置字典并调用 main_engine.connect。参考 examples/no_ui/run.py,CTP 接口的配置字典如下:
ctp_setting = {
"用户名": "",
"密码": "",
"经纪商代码": "",
"交易服务器": "",
"行情服务器": "",
"产品名称": "",
"授权编码": "",
"产品信息": ""
}
main_engine.add_gateway(CtpGateway)
main_engine.connect(ctp_setting, "CTP")
四、修改接口配置文件(json)
接口配置相关信息保存在 json 文件中,放置在用户目录下的 .vntrader 文件夹内。该目录的定位逻辑定义在 vnpy/trader/utility.py 中:TRADER_DIR, TEMP_DIR = _get_trader_dir(".vntrader"),即默认取用户主目录下的 .vntrader 目录。
连接配置文件遵循 connect_{接口名小写}.json 的命名规则——该规则直接来自 ConnectDialog 的源码:self.filename = f"connect_{gateway_name.lower()}.json"(ui/widget.py)。例如 CTP 接口对应 connect_ctp.json,盈透证券对应 connect_ib.json。
如果需要修改接口配置,既可以在 VeighNa Trader 图形界面内修改,也可以直接在 .vntrader 文件夹下编辑对应的 json 文件。将 json 配置文件独立于 vn.py 主程序存放的好处在于:避免每次升级都要重新配置 json 文件——升级框架或接口包时,已保存的账号配置依然保留。
五、查看可交易的合约
先登录接口,然后在菜单栏中点击【帮助】->【查询合约】,即可弹出空白的【查询合约】窗口,点击【查询】按钮后才会显示查询结果,留空则查询全部合约。该入口在源码中对应 ui/mainwindow.py 中的 ContractManager 组件——【帮助】菜单下的【查询合约】动作会打开合约管理组件,通过 ContractData 事件(on_contract 回调推送,见 gateway.py)获取并展示所有已查询到的合约信息。输入合约代码或交易所名称可以缩小查询范围。
六、接口分类总览
vn.py 生态目前覆盖了国内期货、期权、A股、贵金属、银行间市场以及海外市场的各类柜台接口,官方文档将其分为以下 21 类:
| 接口 | 类型 |
|---|---|
| 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 |
七、接口详解
以下逐一说明各接口的支持环境、交易品种、持仓方向、历史数据、配置字段与账号获取方式。表格中的“操作系统”指该接口官方提供的 API 所支持的系统环境。
7.1 CTP
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:
- 仿真账号:从 SimNow 网站上获取,只需输入手机号码和短信验证(短信验证有时只能在工作日正常工作时段收到)。SimNow 的用户名(InvestorID)为 6 位纯数字,经纪商编号为 9999,并提供两套环境用于盘中仿真交易以及盘后测试。需要修改一次密码之后才能使用,且每套仿真环境的适用时间段不同。
- 实盘账号:在期货公司开户,通过联系客户经理开通。用户名为纯数字,经纪商编号也是 4 位纯数字(每个期货公司的经纪商编号都不同)。实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
7.2 CTPTEST(CTP测试)
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:在期货公司开户,通过联系客户经理向期货公司申请进行穿透式接入测试。
7.3 MINI(CTP Mini)
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:在期货公司开户,通过联系客户经理可以开通。用户名为纯数字,经纪商编号也是 4 位纯数字(每个期货公司的经纪商编号都不同)。实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
7.4 FEMAS(飞马)
- 操作系统:Windows
- 交易品种:期货
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:在期货公司开户,通过联系客户经理可以开通。用户名为纯数字,经纪商代码也是 4 位纯数字(每个期货公司的经纪商编号都不同)。实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
7.5 SOPT(CTP期权)
- 操作系统:Windows、Ubuntu
- 交易品种:ETF期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:在期货公司开户,通过联系客户经理可以开通。用户名为纯数字,经纪商代码也是 4 位纯数字(每个期货公司的经纪商代码都不同)。实盘账号也可以开通仿真交易功能,同样需要联系客户经理。
7.6 SEC(顶点飞创)
- 操作系统:Windows
- 交易品种:ETF期权
- 持仓方向:股票只支持单向持仓,股票期权只支持双向持仓
- 历史数据:不提供
相关字段:账号、密码、行情地址、交易地址、行情协议(TCP、UDP)、授权码、产品号、采集类型(顶点、恒生、金证、金仕达)、行情压缩(N、Y)。
获取账号:在期货公司开户,通过联系客户经理可以开通。
7.7 HTS(顶点HTS)
- 操作系统:Windows
- 交易品种:ETF期权
- 持仓方向:双向持仓
- 历史数据:不提供
相关字段:账号、密码、行情地址、交易地址、行情协议(TCP、UDP)、授权码、产品号、采集类型(顶点、恒生、金证、金仕达)、行情压缩(N、Y)。
获取账号:在期货公司开户,通过联系客户经理可以开通。
7.8 UFT(恒生UFT)
- 操作系统:Windows、Ubuntu
- 交易品种:期货、ETF期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、行情服务器、交易服务器、服务器类型(期货、ETF期权)、产品名称、授权编码、委托类型(q)。
获取账号:测试账号请通过恒生电子申请。
7.9 ESUNNY(易盛)
- 操作系统:Windows、Ubuntu
- 交易品种:期货、黄金TD
- 持仓方向:支持双向持仓
- 历史数据:不支持
相关字段:行情账号、行情密码、行情服务器、行情端口(0)、行情授权码、交易账号、交易密码、交易服务器、交易端口(0)、交易产品名称、交易授权编码、交易系统(内盘、外盘)。
获取账号:测试账号请通过易盛官方网站申请。
7.10 XTP(中泰柜台)
- 操作系统:Windows、Ubuntu
- 交易品种:A股、两融、ETF期权
- 持仓方向:股票只支持单向持仓,其余标的支持双向持仓
- 历史数据:不提供
相关字段:账号、密码、客户号(1)、行情地址、行情端口(0)、交易地址、交易端口(0)、行情协议(TCP、UDP)、日志级别(FATAL、ERROR、WARNING、INFO、DEBUG、TRACE)、授权码。
获取账号:测试账号请通过中泰证券申请。
其他特点:XTP 是首家提供融资融券的极速柜台。
7.11 HFT(国泰君安统一交易网关)
- 操作系统:Windows
- 交易品种:A股
- 持仓方向:只支持单向持仓
- 历史数据:不提供
相关字段:交易用户名、交易密码、交易服务器、交易端口、机构代号、营业部代号、网关、行情用户名、行情密码、行情服务器、行情端口。
获取账号:测试账号请通过国泰君安申请。
7.12 TORASTOCK(华鑫奇点股票)
- 操作系统:Windows
- 交易品种:A股
- 持仓方向:只支持单向持仓
- 历史数据:不提供
相关字段:账号、密码、行情服务器、交易服务器、账号类型(用户代码、资金账号)、地址类型(前置地址、FENS地址)。
获取账号:测试账号请通过华鑫证券申请。
7.13 TORAOPTION(华鑫奇点期权)
- 操作系统:Windows
- 交易品种:ETF期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:账号、密码、行情服务器、交易服务器、账号类型(用户代码、资金账号)、地址类型(前置地址、FENS地址)。
获取账号:测试账号请通过华鑫证券申请。
7.14 COMSTAR(中亿汇达)
- 操作系统:Windows
- 交易品种:银行间市场
- 持仓方向:无
- 历史数据:不提供
相关字段:交易服务器、用户名、密码、Key、routing_type(5)、valid_until_time(18:30:00.000)。
获取账号:只有各类大型金融机构才能用(券商自营交易部、银行金融市场部等),私募或个人都用不了,需要购买 ComStar 的交易接口服务之后才能使用。
7.15 OST(东方证券)
- 操作系统:Windows
- 交易品种:A股
- 持仓方向:单向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、上交所快照地址、上交所快照端口(0)、深交所快照地址、深交所快照端口(0)、本机ip地址。
获取账号:在证券公司开户,通过联系客户经理可以开通。
7.16 IB(盈透证券)
- 操作系统:Windows、Ubuntu、Mac
- 交易品种:海外多品种
- 持仓方向:只支持单向持仓
- 历史数据:提供
相关字段:TWS地址(127.0.0.1)、TWS端口(7497)、客户号(1)、交易账户。
获取账号:在盈透证券开户并且入金后可以获得 API 接入权限。
其他特点:可交易品种覆盖诸多海外市场的股票、期权、期货,手续费相对较低。请注意 IB 接口的合约代码较为特殊,请前往官网的产品查询板块查询。VeighNa Trader 中使用的是盈透证券对每个合约在某一交易所的唯一标识符 ConId 作为合约代码,而非 Symbol 或 LocalName。
7.17 TAP(易盛9.0外盘)
- 操作系统:Windows
- 交易品种:外盘期货
- 持仓方向:只支持单向持仓
- 历史数据:不提供
相关字段:行情账号、行情密码、行情服务器、行情端口(0)、交易账号、交易密码、交易服务器、交易端口(0)、授权码。
获取账号:测试账号请通过易盛官方网站申请。
7.18 DA(直达期货)
- 操作系统:Windows
- 交易品种:外盘期货
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、行情服务器、授权码。
获取账号:在直达期货开户并且入金后可以获得 API 接入权限。
7.19 ROHON(融航)
- 操作系统:Windows、Ubuntu
- 交易品种:期货资管
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:测试账号请通过融航申请。
特别注意:融航接口的【经纪商代码】不再是纯数字形态,而是可以包含英文和数字的字符串;VeighNa 连接融航进行交易在穿透式认证中属于【中继】模式,而不再是连接柜台(CTP、恒生等)进行交易时的【直连】模式,所以在申请穿透式认证测试填表时不要选错。
7.20 TTS
- 操作系统:Windows、Ubuntu
- 交易品种:期货、期货期权
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、经纪商代码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:请通过 OpenCTP 平台获取。
7.21 SGIT(飞鼠)
- 操作系统:Ubuntu
- 交易品种:黄金TD
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、行情服务器、产品名称、授权编码。
获取账号:请通过黄金现货经纪商获取。
7.22 KSGOLD(金仕达黄金)
- 操作系统:Ubuntu
- 交易品种:黄金TD
- 持仓方向:只支持双向持仓
- 历史数据:不提供
相关字段:用户名、密码、交易服务器、行情服务器、账号类型(银行账号、黄金账号)。
获取账号:请通过黄金现货经纪商获取。
八、小结:从文档到源码的完整接入路径
综合本文内容,一个交易接口在 vn.py 中的完整生命周期可以归纳为:
- 加载:通过 VeighNa Station 勾选或脚本
main_engine.add_gateway(GatewayClass)注册接口(engine.py); - 连接:图形界面走【系统】->【连接XX】动态菜单(ui/mainwindow.py),脚本则直接构造配置字典调用
main_engine.connect(setting, name)(engine.py);连接成功后接口自动查询账号、持仓、委托、成交,并通过on_xxx事件回调推送数据(gateway.py); - 持久化:配置保存在用户目录
.vntrader下的connect_{接口名}.json中,升级不影响已有配置(ui/widget.py、utility.py); - 使用:通过【帮助】->【查询合约】确认可交易合约,随后即可订阅行情、发送委托、管理持仓。
实际接入时,请根据上表确认所选接口与你的操作系统、交易品种、持仓模式(单向/双向)是否匹配,并按对应机构渠道申请账号与授权。各具体柜台 Gateway 作为独立包发布,可在 examples/veighna_trader/run.py 中查看全部可用的加载清单。