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

原创2026-09-18 16:37:451,982 阅读
文章标签:金融科技桌面应用机器学习数据可视化后端

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 的主引擎实现,说明了接口“加载即注册、连接即查询、回调即推送”的底层工作方式。无论你是准备接入仿真环境验证策略,还是对接实盘柜台投入生产,都可按上述步骤选择对应接口完成接入。

登录后查看全文
vnpy