Add MQL5 README

2026-07-08 06:42:57 +00:00
parent 5343c30087
commit 671d89383c
1 changed files with 51 additions and 0 deletions
@@ -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.