# HyperMatch Bridge 1.0.0

MT5 抛单源桥接器。深色原生面板显示源账号、配对状态、待送事件、引擎已接收记录、异常复核和启停按钮。`HyperMatchBridge.ex5` 是使用 MetaEditor 实际编译的 MT5 EA；同时提供完整 MQL5 源码和 SHA-256 发布清单。

## 安装与配对

1. 在 HyperMatch 网站连接钱包，填写**准确的 MT5 账号与 broker server 名称**，创建源账号绑定并取得 device token。普通账号文本本身不是授权。
2. MT5 → File → Open Data Folder → `MQL5/Experts`，放入 `HyperMatchBridge.ex5`。在 Navigator 的 Expert Advisors 上刷新。
3. Tools → Options → Expert Advisors → 允许 WebRequest，添加 `https://hypermatch.org`。如使用预览域名，网站签发的设备 token 与 EA 的 `InpBridgeUrl` 必须指向同一部署。
4. 将 EA 挂到该源账号的任意一个图表。`InpDeviceToken` 粘贴设备 token。只挂一份即可观察该账号所有品种；不需要给每个品种挂一次。
5. 面板显示 `PAIRED / PAUSED` 后，点击 **START RELAY**。它只采集本次启动后的成交；原有仓位及历史订单不会自动补单。
6. 在网页确认事件和执行回执。EA 的 **ACCEPTED** 表示服务端已持久接收源事件，不代表链上已成交。网页路由策略、品种映射、风险限额、venue 授权和运行模式决定下一步。

EA 不下 MT5 订单，不修改源仓位，不需要交易密码、钱包私钥或 DLL 权限。它能够观察手动、其他 EA、止盈止损触发产生的新增买卖成交。提现通过网站连接的钱包和 venue 原生流程完成，EA 不管理资金。

## 面板操作

- **START RELAY**：先验证配对，再建立本次会话的实时起点，开始采集及发送。
- **PAUSE RELAY**：同时暂停采集与发送，待送文件保留。暂停期间的交易不会在恢复后补采。
- **CHECK LINK**：验证 HTTPS、设备凭证与源账号绑定，不开单、不启动抛单。
- **REVIEW**：本地事件需要人工核对，不能直接按按钮绕过。先在网站检查源仓与 venue 仓位，再处理本地保留文件。

## 可靠性与异常处理

每笔成交使用稳定事件 ID `mt5:<server>:<account>:<dealId>`。EA 先将事件持久写入共享 Files 目录，再由定时器通过 HTTPS 发送。网络超时、429 与 5xx 会按 2–30 秒退避重试同一事件。服务端负责幂等入库，避免超时后的重复执行。

数据保存在 MT5 的 `Terminal/Common/Files/HyperMatch/<account>-<endpoint-and-server-hash>/`。`*.pending` 待送，`*.sent` 已接收，`*.review` 异常。token 不写入这些日志；它由 MT5 的 EA 输入设置管理，不要导出或分享包含真实 token 的 `.set` 文件。

- 401/403：停止；重新签发与当前账号和 server 绑定的 token。
- 409：停止；原事件保留在待送队列，先解决服务端绑定/事件冲突。
- 400/404/422：隔离该事件并停止；检查 API 版本、URL、品种及事件格式。
- 过期（默认 60 秒）或未来时间异常：隔离并停止，避免恢复联网后突然追单。
- 本地写入失败、未完成文件或账号切换：停止，避免静默遗漏。

复核完成后，可在**停止 EA 的状态**下把已处理的 `.review`/损坏临时文件移到独立人工归档目录，再重新挂载。不要直接把文件改回 `.pending` 强制重放。已接收 `.sent` 文件可定期备份；其作用是本地去重与审计。

## 边界

EX5 已通过编译验证，不等于真实账户到链上成交的端到端认证。首次配对应使用独立模拟源账号验证，只有网页明确开启且完成 venue 接入与风控的执行模式才会下发真实交易。该版本不支持 MT5 Strategy Tester 的网络回放。

净持仓反转 `inout` 作为原始事件上传，由服务端进入需要映射/复核的状态；EA 不自行把它转换成开仓。成交 UTC 使用 broker 成交时间及当前 server/UTC 偏移估算，同时上传原始毫秒时间和偏移。源服务器时区或本机时钟异常需要核对。

## Rebuild

macOS with installed MetaTrader 5: `python3 mt5/compile.py` from the repository root. Windows: `python mt5/compile.py --metaeditor "C:\Program Files\MetaTrader 5\MetaEditor64.exe"`.

The build copies MetaEditor into an isolated temporary directory and requires a fresh EX5 plus `0 errors, 0 warnings` in the compiler log. It does not launch or alter the user's trading terminal. The ZIP includes source, binary, setup inputs, build result and file hashes.