vn.py 交易接口(Gateway)完全指南:加载、连接、配置与 21 大接口详解

原创2026-09-18 12:28:411,646 阅读
文章标签:金融科技桌面应用机器学习

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)会完成三件事:

  1. 若未显式传入 gateway_name,则使用 gateway_class.default_name(如 "CTP")作为注册名;
  2. 以 (event_engine, gateway_name) 实例化 Gateway 对象,并存入 self.gateways 字典;
  3. 将该 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 中的完整生命周期可以归纳为:

  1. 加载:通过 VeighNa Station 勾选或脚本 main_engine.add_gateway(GatewayClass) 注册接口(engine.py);
  2. 连接:图形界面走【系统】->【连接XX】动态菜单(ui/mainwindow.py),脚本则直接构造配置字典调用 main_engine.connect(setting, name)(engine.py);连接成功后接口自动查询账号、持仓、委托、成交,并通过 on_xxx 事件回调推送数据(gateway.py);
  3. 持久化:配置保存在用户目录 .vntrader 下的 connect_{接口名}.json 中,升级不影响已有配置(ui/widget.py、utility.py);
  4. 使用:通过【帮助】->【查询合约】确认可交易合约,随后即可订阅行情、发送委托、管理持仓。

实际接入时,请根据上表确认所选接口与你的操作系统、交易品种、持仓模式(单向/双向)是否匹配,并按对应机构渠道申请账号与授权。各具体柜台 Gateway 作为独立包发布,可在 examples/veighna_trader/run.py 中查看全部可用的加载清单。

登录后查看全文
vnpy