diff --git a/mql5/README.md b/mql5/README.md new file mode 100644 index 0000000..7f165aa --- /dev/null +++ b/mql5/README.md @@ -0,0 +1,51 @@ +# MQL5 Helper EA + +`Mt5BridgeHelper.mq5` is an MQL5 Expert Advisor that listens for **async commands** sent by the Python `mt5bridge-ccxt` package and executes them on the MT5 side. + +## Why is this needed? + +MT5Bridge's HTTP API does not expose a synchronous cancel/modify/close endpoint. To still support these operations, the wrapper writes **GlobalVariable commands** on the MT5 side that this helper EA reads and acts on. + +## Installation + +1. Copy `Mt5BridgeHelper.mq5` to your MT5 `MQL5/Experts/` directory. +2. In MetaEditor, compile the file (F7). +3. Open **any** chart in MT5 (e.g. EURUSD M1). +4. Drag `Mt5BridgeHelper` from the Navigator onto the chart. +5. In the Inputs dialog, leave defaults (1s polling, logging on). +6. Make sure **"Allow Algo Trading"** is enabled in the MT5 toolbar. +7. Click OK. You should see `[Mt5BridgeHelper] Started` in the Experts log. + +The helper EA runs on a single chart and handles commands for **all** symbols on the account. + +## Supported Commands + +| GlobalVariable name | Action | +|------------------------------|-------------------------------------------------| +| `MT5BRIDGE_CMD_CANCEL_{id}` | Calls `OrderDelete(id)` for a pending order | +| `MT5BRIDGE_CMD_MODIFY_{id}` | Modify SL/TP/price (full payload in v0.2) | +| `MT5BRIDGE_CMD_CLOSE_{id}` | Calls `PositionClose(id)` for an open position | + +## Usage from Python + +```python +import mt5bridge_ccxt +exchange = mt5bridge_ccxt.mt5bridge({...}) + +# Send async cancel command +result = exchange.cancel_order("12345") +print(result) +# {'info': {'method': 'gvar_signal', 'command_key': 'MT5BRIDGE_CMD_CANCEL_12345', 'ticket': 12345}, +# 'id': '12345', 'status': 'canceling'} + +# Send async close command for a position +result = exchange.mql5.send_close_command(98765, volume=0.01) +``` + +## Limitations + +- **Async**: commands take up to 1s to be picked up by the EA (default poll interval). +- **No confirmation**: the wrapper returns "canceling" immediately; you must poll + `fetch_open_orders` / `fetch_positions` to confirm the operation succeeded. +- **MT5 restart**: in-flight commands stored only as GlobalVariables will be lost + if MT5 restarts before the EA processes them.