From 733ddd01c2f11659817b5291b6da5a2d70bcffd9 Mon Sep 17 00:00:00 2001 From: gavindiaz Date: Wed, 8 Jul 2026 06:44:54 +0000 Subject: [PATCH] Update README with full documentation --- README.md | 202 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 201 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1582cbe..5159bf0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,203 @@ # mt5bridge-ccxt -CCXT-compatible wrapper for MT5Bridge HTTP API. Use MetaTrader 5 with any CCXT-aware framework. \ No newline at end of file +[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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