Update README with full documentation
This commit is contained in:
@@ -1,3 +1,203 @@
|
||||
# mt5bridge-ccxt
|
||||
|
||||
CCXT-compatible wrapper for MT5Bridge HTTP API. Use MetaTrader 5 with any CCXT-aware framework.
|
||||
[](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
|
||||
|
||||
Reference in New Issue
Block a user