204 lines
7.2 KiB
Markdown
204 lines
7.2 KiB
Markdown
# mt5bridge-ccxt
|
|
|
|
[](https://www.python.org/downloads/)
|
|
[](LICENSE)
|
|
[](https://github.com/psf/black)
|
|
|
|
> CCXT-compatible wrapper for the [MT5Bridge](https://code.aifunny.ltd/gavindiaz/my-Mt5Bridge) HTTP API.
|
|
> Use MetaTrader 5 with **any** CCXT-aware framework — Freqtrade, Jesse, Hummingbot, backtrader, 30+ others.
|
|
|
|
## Why?
|
|
|
|
Most quant frameworks ship with **native** broker support (Binance, OKX, Alpaca, IB, …) but not MetaTrader 5. This wrapper exposes MT5 through the standard CCXT interface so that:
|
|
|
|
- **Freqtrade** can backtest and live-trade MT5 with zero changes to your strategy
|
|
- **Jesse** can connect to MT5
|
|
- **Backtrader** can use MT5 as a live broker
|
|
- **Hummingbot** can arbitrage via MT5
|
|
- Your own scripts can use the standard CCXT API
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install mt5bridge-ccxt
|
|
```
|
|
|
|
Or from source:
|
|
|
|
```bash
|
|
git clone https://code.aifunny.ltd/gavindiaz/mt5bridge-ccxt.git
|
|
cd mt5bridge-ccxt
|
|
pip install -e .
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
import mt5bridge_ccxt
|
|
|
|
exchange = mt5bridge_ccxt.mt5bridge({
|
|
"apiKey": "your-mt5bridge-api-key",
|
|
"host": "http://localhost:8080",
|
|
"symbols": {
|
|
"XAU/USD": "XAUUSDc",
|
|
"EUR/USD": "EURUSDc",
|
|
},
|
|
})
|
|
|
|
# Check status
|
|
print(exchange.fetch_status())
|
|
|
|
# Fetch ticker
|
|
ticker = exchange.fetch_ticker("XAU/USD")
|
|
print(f"XAU/USD bid={ticker['bid']} ask={ticker['ask']}")
|
|
|
|
# Fetch OHLCV
|
|
bars = exchange.fetch_ohlcv("XAU/USD", "1h", limit=100)
|
|
|
|
# Place a market order
|
|
order = exchange.create_order(
|
|
"XAU/USD", "market", "buy", 0.01,
|
|
params={"sl": 4170.0, "tp": 4190.0, "magic": 12345}
|
|
)
|
|
|
|
# Read MQL5 indicator signal (e.g. Alpha Trend)
|
|
signal = exchange.mql5.alpha_trend_signal("XAUUSDc", "H1")
|
|
```
|
|
|
|
## Features
|
|
|
|
| CCXT method | Status | MT5Bridge endpoint |
|
|
|--------------------------|---------|-------------------------------------|
|
|
| `fetch_status` | ✅ | `GET /health` |
|
|
| `fetch_markets` | ✅ | derived from `symbols` config |
|
|
| `fetch_ticker` | ✅ | `GET /symbols/{s}/tick` |
|
|
| `fetch_ohlcv` | ✅ | `GET /rates/from-pos` / `from-date` |
|
|
| `fetch_balance` | ✅ | `GET /account` |
|
|
| `fetch_positions` | ✅ | `GET /positions` |
|
|
| `fetch_open_orders` | ✅ | `GET /orders` |
|
|
| `fetch_my_trades` | ✅ | `GET /history/deals` |
|
|
| `create_order` | ✅ | `POST /order/send` |
|
|
| `cancel_order` | ⚠️ async | via `GlobalVariable` + helper EA |
|
|
| `fetch_order` | ❌ | not exposed by MT5Bridge |
|
|
| `fetch_order_book` | ❌ | not applicable |
|
|
| `fetch_trades` (realtime)| ❌ | not exposed |
|
|
| `set_leverage` | ❌ | MT5 manages this |
|
|
|
|
## Supported Timeframes
|
|
|
|
`1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`
|
|
|
|
## Configuration
|
|
|
|
| Key | Type | Default | Description |
|
|
|-----------------------|--------|----------------------------|------------------------------------------------|
|
|
| `apiKey` | str | (required) | Your MT5Bridge API key (`X-API-Key` header) |
|
|
| `secret` | str | (unused) | Placeholder for CCXT compatibility |
|
|
| `host` | str | `http://localhost:8080` | Base URL of your MT5Bridge service |
|
|
| `timeout` | int | `30000` | Request timeout in milliseconds |
|
|
| `symbols` | dict | `{}` | Map of CCXT symbol → MT5 symbol |
|
|
| `default_volume_step` | float | `0.01` | Default lot rounding step |
|
|
|
|
## Async Cancel / Modify / Close
|
|
|
|
MT5Bridge does not expose synchronous cancel/modify/close endpoints. To support these, the wrapper writes **GlobalVariable commands** that the included MQL5 helper EA reads and executes on the MT5 side.
|
|
|
|
**Setup the MQL5 helper EA:**
|
|
|
|
1. Copy `mql5/Mt5BridgeHelper.mq5` to your MT5 `MQL5/Experts/` directory.
|
|
2. Compile in MetaEditor (F7).
|
|
3. Drag `Mt5BridgeHelper` onto any chart in MT5.
|
|
4. Enable Algo Trading.
|
|
|
|
See [mql5/README.md](mql5/README.md) for details.
|
|
|
|
```python
|
|
# Async cancel
|
|
exchange.cancel_order("12345")
|
|
|
|
# Async close
|
|
exchange.mql5.send_close_command(ticket=67890, volume=0.01)
|
|
```
|
|
|
|
## Reading MQL5 Indicator Signals
|
|
|
|
If you have the [Alpha Trend indicator](https://code.aifunny.ltd/gavindiaz/my-Mt5Bridge) loaded on a chart, you can read its signals via the `/gvar` endpoint:
|
|
|
|
```python
|
|
# Read the indicator's GlobalVariables
|
|
signal = exchange.mql5.alpha_trend_signal(
|
|
symbol="XAUUSDc",
|
|
timeframe="H1",
|
|
length=14,
|
|
atr_mult=1.0,
|
|
)
|
|
# {'alpha': 4180.0, 'offset': 4178.0, 'trend': 1.0, 'buy': 1.0, 'sell': 0.0}
|
|
|
|
# Read a custom signal key
|
|
rsi = exchange.mql5.get("MY_RSI_XAUUSDc_PERIOD_H1")
|
|
|
|
# List all GlobalVariables
|
|
for gv in exchange.mql5.list():
|
|
print(gv["name"], "=", gv["value"])
|
|
```
|
|
|
|
## Examples
|
|
|
|
- [examples/01_basic_usage.py](examples/01_basic_usage.py) — basic operations
|
|
- [examples/02_strategy.py](examples/02_strategy.py) — moving-average crossover strategy
|
|
- [examples/03_freqtrade_config.json](examples/03_freqtrade_config.json) — Freqtrade config
|
|
- [examples/04_mql5_signal_reader.py](examples/04_mql5_signal_reader.py) — read MQL5 signals
|
|
|
|
## Using with Freqtrade
|
|
|
|
1. `pip install mt5bridge-ccxt`
|
|
2. Copy `examples/03_freqtrade_config.json` to `user_data/config.json`
|
|
3. Edit API key, host, and symbols
|
|
4. `freqtrade trade --config user_data/config.json --strategy YourStrategy`
|
|
|
|
> **Note**: Freqtrade uses `ccxt` internally. The wrapper is auto-discovered once the package is installed in the same Python environment.
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
pip install -e ".[test]"
|
|
pytest
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Freqtrade / Jesse / Your strategy
|
|
|
|
|
v standard CCXT methods
|
|
mt5bridge (this package)
|
|
|
|
|
v HTTP (X-API-Key)
|
|
MT5Bridge (C# .NET 8, your existing project)
|
|
|
|
|
v MtApi5 client (port 8228)
|
|
MtApi5 EA on MT5 chart
|
|
|
|
|
v
|
|
MetaTrader 5
|
|
```
|
|
|
|
## Limitations & Caveats
|
|
|
|
- **Not a real exchange** — MT5 is OTC/CFD. `exchange.type == "swap"`.
|
|
- **No WebSocket** — all data is pulled via polling. Use `fetch_ticker` / `fetch_ohlcv` in a loop.
|
|
- **No order book / Level 2** — MT5 doesn't expose this via MtApi5.
|
|
- **Cancel/modify/close are async** — see above.
|
|
- **Single account** — MT5Bridge exposes one account at a time. The wrapper does not implement `fetchAccounts`.
|
|
- **Markets are not auto-discovered** — provide them via the `symbols` config.
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|
|
|
|
## Related
|
|
|
|
- [my-Mt5Bridge](https://code.aifunny.ltd/gavindiaz/my-Mt5Bridge) — the C# HTTP service this wraps
|
|
- [CCXT](https://github.com/ccxt/ccxt) — the standard library this implements
|
|
- [MtApi5](https://github.com/siliverwind/mt5-api) — C# library used by MT5Bridge
|