mt5bridge-ccxt/README.md

# mt5bridge-ccxt

[![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