Skip to content
BranchesTags

Repository files navigation

MetaTrader 5

MetaTrader 5 plugin for bt_api, supporting multi-asset trading via MT5 Web API.

PyPI VersionPython VersionsLicenseCIDocs

English | 中文

Overview

This package provides a MetaTrader 5 gateway adapter for the bt_api framework. It connects to MT5 terminals via the pymt5 WebSocket client and exposes a unified interface for trading and market data.

Features

  • MT5 WebSocket connection via pymt5 library
  • Real-time tick data via WebSocket push notifications
  • Order placement — market, limit, stop orders with SL/TP support
  • Position & balance tracking — open positions, account balance, equity
  • Historical bars — M1/M5/M15/M30/H1/H4/D1/W1/MN1 timeframes
  • Symbol subscription — batch subscribe to multiple symbols
  • Order management — place, cancel, track open orders

Requirements

  • Python 3.9+
  • bt_api_base >= 0.15
  • pymt5 >= 0.5.0 (Windows/macOS only — MT5 terminal required)
  • A running MT5 terminal with WebAPI enabled

Installation

pip install bt_api_mt5

Or install from source:

git clone https://github.com/cloudQuant/bt_api_mt5
cd bt_api_mt5
pip install -e .

Note:pymt5 connects to a running MT5 terminal via WebSocket. MT5 only runs on Windows and macOS. Linux users can install the package but will not be able to establish connections without a remote MT5 terminal.

Quick Start

frombt_api_mt5importMt5GatewayAdapter# Initialize the adapteradapter=Mt5GatewayAdapter(
login=12345678, # MT5 account loginpassword="your_password",
ws_uri="ws://localhost:8080", # MT5 WebAPI URIsymbol_suffix="", # optional: symbol suffix mapping
)
# Connect to MT5adapter.connect()
# Subscribe to symbolsadapter.subscribe_symbols(["EURUSD", "GBPUSD"])
# Get account balancebalance=adapter.get_balance()
print(balance)
# Get open positionspositions=adapter.get_positions()
print(positions)
# Place a limit orderorder_result=adapter.place_order({
"symbol": "EURUSD",
"volume": 0.1,
"price": 1.0850,
"order_type": "limit",
"direction": "buy",
"sl": 1.0800,
"tp": 1.0900,
})
print(order_result)
# Cancel an ordercancel_result=adapter.cancel_order({"order_id": 12345678})
print(cancel_result)
# Get historical barsbars=adapter.get_bars("EURUSD", "H1", 100)
print(f"Got {len(bars)} bars")
# Disconnectadapter.disconnect()

Supported Operations

OperationMethodStatus
Connectconnect()✅
Disconnectdisconnect()✅
Subscribe symbolssubscribe_symbols(symbols)✅
Account balanceget_balance()✅
Open positionsget_positions()✅
Place orderplace_order(payload)✅
Cancel ordercancel_order(payload)✅
Historical barsget_bars(symbol, timeframe, count)✅
Symbol infoget_symbol_info(symbol)✅
Open ordersget_open_orders()✅

Order Payload Format

{
"symbol": "EURUSD", # Trading symbol"volume": 0.1, # Order volume (lots)"price": 1.0850, # Limit price (for limit/stop orders)"order_type": "limit", # "market", "limit", "stop""direction": "buy", # "buy" or "sell""sl": 1.0800, # Stop loss price (optional)"tp": 1.0900, # Take profit price (optional)"comment": "order comment"# Optional comment
}

Symbol Resolution

The adapter maintains a symbol map for mapping bt_api symbol names to MT5 symbol names. Configure it via the symbol_map kwarg:

adapter=Mt5GatewayAdapter(
login=12345678,
password="your_password",
ws_uri="ws://localhost:8080",
symbol_map={
"EURUSD": "EURUSD",
"XAUUSD": "GOLD",
},
symbol_suffix=""# optional suffix appended to all symbols
)

Architecture

bt_api_mt5/
├── src/bt_api_mt5/
│ ├── __init__.py # Package init, exports Mt5GatewayAdapter
│ ├── plugin.py # bt_api plugin registration
│ └── gateway/
│ ├── __init__.py
│ └── adapter.py # Mt5GatewayAdapter implementation
├── tests/
│ └── conftest.py # Pytest configuration
└── docs/
└── index.md # Documentation

Online Documentation

ResourceLink
English Docshttps://bt-api-mt5.readthedocs.io/
Chinese Docshttps://bt-api-mt5.readthedocs.io/zh/latest/
GitHub Repositoryhttps://github.com/cloudQuant/bt_api_mt5
Issue Trackerhttps://github.com/cloudQuant/bt_api_mt5/issues

License

MIT License - see LICENSE for details.

Support

中文

概述

本包为 bt_api 框架提供 MetaTrader 5 网关适配器。通过 pymt5 WebSocket 客户端连接 MT5 终端，提供统一的交易和行情数据接口。

功能特点

  • MT5 WebSocket 连接 — 通过 pymt5 库连接 MT5 终端
  • 实时 tick 数据 — WebSocket 推送行情
  • 下单 — 市价单、限价单、止损单，支持 SL/TP
  • 持仓与余额查询 — 持仓、账户余额、权益
  • 历史 K 线 — M1/M5/M15/M30/H1/H4/D1/W1/MN1 时间周期
  • 品种订阅 — 批量订阅多个交易品种
  • 订单管理 — 下单、撤单、查询挂单

系统要求

  • Python 3.9+
  • bt_api_base >= 0.15
  • pymt5 >= 0.5.0（仅 Windows/macOS，需运行 MT5 终端）
  • 已启用 WebAPI 的 MT5 终端

安装

pip install bt_api_mt5

或从源码安装：

git clone https://github.com/cloudQuant/bt_api_mt5
cd bt_api_mt5
pip install -e .

注意：pymt5 通过 WebSocket 连接运行中的 MT5 终端。MT5 仅在 Windows 和 macOS 上运行。Linux 用户可以安装包，但需要远程 MT5 终端才能建立连接。

快速开始

frombt_api_mt5importMt5GatewayAdapter# 初始化适配器adapter=Mt5GatewayAdapter(
login=12345678, # MT5 账户登录名password="your_password",
ws_uri="ws://localhost:8080", # MT5 WebAPI 地址symbol_suffix="", # 可选：品种后缀映射
)
# 连接 MT5adapter.connect()
# 订阅品种adapter.subscribe_symbols(["EURUSD", "GBPUSD"])
# 查询账户余额balance=adapter.get_balance()
print(balance)
# 查询持仓positions=adapter.get_positions()
print(positions)
# 下限价单order_result=adapter.place_order({
"symbol": "EURUSD",
"volume": 0.1,
"price": 1.0850,
"order_type": "limit",
"direction": "buy",
"sl": 1.0800,
"tp": 1.0900,
})
print(order_result)
# 撤单cancel_result=adapter.cancel_order({"order_id": 12345678})
print(cancel_result)
# 查询历史 K 线bars=adapter.get_bars("EURUSD", "H1", 100)
print(f"获取了 {len(bars)} 根 K 线")
# 断开连接adapter.disconnect()

支持的操作

操作方法状态
连接connect()✅
断开disconnect()✅
订阅品种subscribe_symbols(symbols)✅
账户余额get_balance()✅
持仓查询get_positions()✅
下单place_order(payload)✅
撤单cancel_order(payload)✅
历史 K 线get_bars(symbol, timeframe, count)✅
品种信息get_symbol_info(symbol)✅
挂单查询get_open_orders()✅

下单参数格式

{
"symbol": "EURUSD", # 交易品种"volume": 0.1, # 委托数量（手）"price": 1.0850, # 委托价格（限价单/止损单）"order_type": "limit", # "market", "limit", "stop""direction": "buy", # "buy" 或 "sell""sl": 1.0800, # 止损价格（可选）"tp": 1.0900, # 止盈价格（可选）"comment": "订单备注"# 可选备注
}

品种名称解析

适配器维护品种映射表，通过 symbol_map 参数配置 bt_api 品种名到 MT5 品种名的映射：

adapter=Mt5GatewayAdapter(
login=12345678,
password="your_password",
ws_uri="ws://localhost:8080",
symbol_map={
"EURUSD": "EURUSD",
"XAUUSD": "GOLD",
},
symbol_suffix=""
)

架构

bt_api_mt5/
├── src/bt_api_mt5/
│ ├── __init__.py # 包初始化，导出 Mt5GatewayAdapter
│ ├── plugin.py # bt_api 插件注册
│ └── gateway/
│ ├── __init__.py
│ └── adapter.py # Mt5GatewayAdapter 实现
├── tests/
│ └── conftest.py # Pytest 配置
└── docs/
└── index.md # 文档

在线文档

资源链接
英文文档https://bt-api-mt5.readthedocs.io/
中文文档https://bt-api-mt5.readthedocs.io/zh/latest/
GitHub 仓库https://github.com/cloudQuant/bt_api_mt5
问题反馈https://github.com/cloudQuant/bt_api_mt5/issues

许可证

MIT 许可证 - 详见 LICENSE。

技术支持

About

Exchange adapter package for bt_api

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages