Chuẩn tích hợp EA ↔ fxconsoleEA ↔ fxconsole integration standard

Applies to: every new MT5 EA that connects to fxconsole (remote config, hot-reload, telemetry, realtime link).

Keyword conventions:

• MUST / MUST NOT: mandatory. An EA that violates them may not go to production.
• SHOULD: strongly recommended. Doing otherwise requires a reason recorded in the build history.
• MAY: optional.

flowchart LR
  ADM(["Admin"])
  subgraph FX["fxconsole (Laravel)"]
    PAGE["/admin/easupported/{slug}"]
    CFG[("ea_config (MySQL)")]
    PUB["Redis PUBLISH ea:link:cfg"]
    HB["/easupported/{slug}/api/tmap/heartbeat"]
  end
  BRK["EaLinkBroker :9607 (Node)"]
  EA["EA on MT5<br/>(each chart = 1 inst)"]
  ADM --> PAGE --> CFG --> PUB --> BRK
  BRK -- "TLS: cfg signal, no values" --> EA
  EA -- "HTTPS (real cert)" --> HB
  HB -- "values + hot_keys" --> EA

Config values only travel along the HTTPS heartbeat path; EaLinkBroker only says “something changed”.

Two channels:

1. The admin opens /admin/easupported → Add EA (“Thêm EA”): enter a name → a unique slug is suggested → a secret token is generated.
2. Copy the URL https://fxconsole.gamelau.uk/easupported/{slug} and the Secret token into the EA's .set.
3. Run the EA → the first heartbeat creates the account in the list, with the Schema column = Reported.

The EA MUST use exactly the input names below, so that .set files, operating docs and deploy tooling (vps-agent key/value injection) work the same for every EA.

Code comments are kept in Vietnamese as in the source. They read: InpCloudSyncEnable — enable heartbeat / remote config (live only); InpCloudBearerToken — the EA product's secret token; InpCloudSyncIntervalSec — heartbeat cycle in seconds, 5–60; “Multi-node” group — only when the EA supports leader election (§10); InpCloudNodePriority — 1 = highest; InpCloudNodeId — empty = auto; InpLinkHost — empty = host of InpCloudMyApiDomain.

MT5: the host in InpCloudMyApiDomain (and InpLinkHost if different) MUST be listed in Tools → Options → Expert Advisors → Allow WebRequest for listed URL. MQL5 sockets share this same list.

• An account on the server is identified by (ea_id, composite_id, magic).
• composite_id MUST use exactly the slugify function below (the same as AccountStatusUpdater); otherwise the account will not match mt5_accounts:

The comment on EA_Slugify reads: lowercase, [a-z0-9], every run of other characters collapses into a single -.

Base URL: InpCloudMyApiDomain + /api/tmap/<endpoint>. The headers MUST include:

• Error codes: 401 wrong token · 404 slug does not exist · 422 invalid data ({"message","errors"}) · -1 from WebRequest = network error or host not in Allow WebRequest.
• JSON strings MUST be escaped: \, " and every character < 0x20 (broker/account names sometimes contain control characters).

An EA that does not use leader election MUST still send node_id and priority (use auto-... and 100).

• Config keys appear only while an override exists for that account, already typed as JSON according to the schema's type.
• hot_keys is a CSV of the keys currently overridden. It is the source of truth: for any key not in hot_keys the EA MUST return to its input value. "hot_keys":"" means no override remains → revert everything.
• On a successful parse the EA MUST record the time of the OK heartbeat (used by the panel and EA Link, see §9.5).

→ {"ok":true,"count":N} (or "skipped":true when the map is unchanged; the server skips the DB write).

GET /load?magic=&account= → {"ok":true,"magic","account","entries":[...]} · DELETE /clear?magic=&account= → {"ok":true,"deleted":N}.

• Only the leader may save/clear (§10).
• The EA SHOULD NOT send save every cycle when the map is unchanged. The EA SHOULD compare before sending.

Ticket map storage and recovery in detail: TMap disaster recovery.

The EA declares its own list of editable configs and sends it in every heartbeat. The server renders the UI from the schema; nothing is hardcoded.

Rules:

1. A released key MUST NOT be renamed or change type. If a change is needed, create a new key and retire the old one.
2. A released enum value MUST NOT be renumbered or reused for another meaning, even on a different build branch of the same slug. Example: Auto = 3 is taken by the b22+ test line, so Pause in b21.1 had to use 4.
3. Every value present in the schema MUST be accepted by the parser. A value the schema offers but the parser rejects is a bug (see §17: b28 declares Auto = 3 but its parser only accepts 0–2).
4. An out-of-range value → the EA MUST keep its current value and Print a warning; it must not crash or reset to 0.
5. The schema is stored per product, not per account. When several builds with different schemas run on one slug, the web shows the schema of the account with the most recent heartbeat. Builds on the same slug therefore SHOULD keep compatible schemas.
6. The schema JSON string MUST be valid: commas between objects, no comma after the last object.

• An array of { "name": string, "data": string }; both are strings. Numbers use DoubleToString.
• Array order = display order on /admin/easupported/{slug}/account/{id}.
• The server keeps only the latest snapshot (overwritten on every heartbeat).
• Rows that MUST be present: Build (build tag), Balance, Equity. Rows that SHOULD be present: Floating P/L, Buy, Sell, Net lot, Leader, Hot Reload, Link.
• An EA with an info panel SHOULD push the panel content verbatim (capturing each line as it is drawn) so the admin sees exactly what the trader sees.
• The payload MUST NOT contain tokens, passwords or personal data other than the account name.

MQL5 input values are immutable at runtime, so every hot-reloadable config MUST have one global variable:

input InpX (immutable) ──OnInit──► g_x (global) ──logic reads every tick──► behaviour
                                      ▲
                  heartbeat parse ────┘  (not in hot_keys → g_x = InpX)

• Logic MUST read g_x and MUST NOT read InpX (except on the declaration line and the initialisation line).

Changing a config only affects future decisions; it does not undo positions already open. For example, turning hedge off only stops new hedges from opening.

Comments in the code, translated: EA_ApplyHotConfig is a PURE function of the JSON response string and does not touch leader state. Step 1 — a key that is present is written to its global (with a range check; the PrintFormat says “manual_init=%d is invalid, keeping %d”). Step 2 — hot_keys is authoritative → revert keys that are absent; a response without hot_keys reverts nothing. Step 3 — build the panel line "Hot Reload: ..." from the keys currently applied.

• Key lookups in hot_keys SHOULD be wrapped in commas (",key,") so that lot does not falsely match lot_balance_trigger.
• Keep ApplyHotConfig separate from leader handling: one function that only takes the JSON string and applies config is easy to call again and easy to test.

1. Declare the global g_foo.
2. OnInit: g_foo = InpFoo;.
3. Replace every place where logic reads InpFoo with g_foo (keep the input line and the init line).
4. Parse it in EA_ApplyHotConfig (with a range check).
5. Revert it when absent from hot_keys + add it to the panel line.
6. Add an entry to config_schema (§6). For group B, recreate the handle in step 4.
7. Bump the build tag (§14).

The server and the web need no changes.

Let the EA know immediately when an admin applies/clears config, instead of waiting for the next heartbeat.

• The channel only carries the signal {"t":"cfg","rev"}. On receiving it → the EA calls the HTTPS heartbeat (§5) to fetch the values.
• Reason: MT5 SocketTlsHandshake does not verify the certificate (the broker uses a self-signed one). A man in the middle could impersonate the broker, so the socket MUST NOT carry config values, tokens or trade commands.
• If Link is lost the EA still receives config through the periodic heartbeat (P8).

sequenceDiagram
  participant A as Admin
  participant F as fxconsole
  participant R as Redis
  participant B as EaLinkBroker port 9607
  participant E as EA (MT5)
  E->>B: TLS connect
  B->>E: challenge (nonce, server_t)
  E->>B: hello (slug, composite_id, magic, node_id, inst, sig)
  B->>F: POST /api/internal/ea-link/key (X-Broker-Secret)
  F-->>B: sha256(secret_token)
  B->>E: hello_ok (hb_sec 20)
  Note over E,B: hb / hb_ok every 20s, closed after 60s of silence
  A->>F: Apply or Clear
  F->>R: PUBLISH ea:link:cfg (slug, targets, rev)
  R-->>B: PSUBSCRIBE *ea:link:cfg
  B->>E: cfg (rev)
  Note over E: debounce, at most 1 pull per second
  E->>F: HTTPS POST /easupported/slug/api/tmap/heartbeat
  F-->>E: values + hot_keys
  E->>B: cfg_ack (rev, ok)

The handshake followed by one Apply. Only the HTTPS step carries config values.

NDJSON UTF-8, 1 JSON per line, 8 KiB maximum.

Authentication (the raw token never crosses the socket):

The comment on key reads: a 64-character hex string; the WHOLE string is used as the HMAC key.

Isolation: topic = ea/{slug}/{composite_id}/{magic}; within a topic every connection has the key {node_id}#{inst}. Reconnecting with the same key replaces the old connection (superseded); a different inst coexists and also receives signals.

Full details and broker operations: monitor/EaLinkBroker/README.md · Realtime brokers.

Behaviour built into the include: connect timeout 2s; send/recv timeout 2s; the handshake must finish within 10s; backoff 2→4→8…60s with ±20% jitter, reset after 30s of stable UP; bad_sig/unknown_ea wait 5 minutes; errors are logged the first time and every 10th time.

Comments and log strings in the code, translated: g_hbOkSeq — incremented on every successful heartbeat parse; OnInit — “… compute g_compositeId, first heartbeat …”; the Print “[EaLink] TẮT: cần …” means “Link OFF: needs InpCloudMyApiDomain …/easupported/{slug} + InpCloudBearerToken”; EA_HeartbeatPulse() — periodic heartbeat on InpCloudSyncIntervalSec (measured with GetTickCount64); EA_SendHeartbeat() — HTTPS, applies config via EA_ApplyHotConfig; the PrintFormat reads “cfg rev=… applied (“đã áp”) / pull FAILED (“kéo LỖI”) in (“trong”) N ms”.

In the heartbeat parse function, on success: g_hbOkSeq++; g_hbOkMs = GetTickCount64();.

• A new frame type (e.g. realtime telemetry, commands) MUST update this section + monitor/EaLinkBroker/README.md before any code is written.
• Control frames (commands) MUST keep principle P3: the socket only announces "there is command id=N"; the EA fetches the details over HTTPS before executing.

Used when running the same account + magic on several terminals/VPSes for redundancy. An EA running a single node MAY skip this section (it still sends node_id + priority).

• Leader = the alive node with the lowest priority (on a tie, the alphabetically smaller node_id). Alive = heartbeat within timeout_sec.
• Only the leader may open/close orders and save/clear the ticket map. Followers only sync and observe.
• Heartbeats failing continuously for > 2 × InpCloudHeartbeatTimeoutSec → the EA SHOULD take leadership itself so positions are not abandoned.
• Never received a successful heartbeat → leader by default.
• Each node MUST have a distinct priority; InpCloudNodeId SHOULD be set explicitly (the auto ID changes when the terminal folder changes).
• InpCloudHeartbeatTimeoutSec MUST be ≥ 3 × InpCloudSyncIntervalSec.

The lines below MUST be present when InpCloudSyncEnable = true. The panel content SHOULD be pushed verbatim into payload.

The heartbeat age on the Server line SHOULD be measured with GetTickCount64() so it does not freeze while the market is closed.

• WebRequest is synchronous: each call can block for up to InpCloudWebTimeoutMs. It MUST NOT be called inside order scan/close loops; important events (e.g. a partial close) SHOULD only set a "needs sync" flag and let OnTimer send.
• Network calls MUST NOT be retried continuously every tick/second on failure; use backoff or wait for the next cycle.
• The "last sent" time SHOULD only be updated after a successful send, or updated beforehand with an explicit backoff. Avoid both failure modes: retry spam, or a whole silent cycle after a single failure.
• OnDeinit SHOULD send at most 1 final heartbeat/save, not a chain of requests (MT5 may kill the EA if deinit takes too long).

1. Per-product tokens: every EA product has its own secret. If a leak is suspected, click Regenerate on /admin/easupported and update the .set on every terminal.
2. Never expose the token: do not Print it, do not put it in the payload, do not commit a .set containing it (commit only sample .set files with InpCloudBearerToken left empty).
3. The socket carries no secrets: EA Link sends only an HMAC signature, never the token; the broker only holds sha256(token).
4. Control values over HTTPS only: config and commands always come from a certificate-verified HTTPS endpoint (P3).
5. Internal endpoints (/api/internal/*) are for brokers only, authenticated with X-Broker-Secret, and fail closed when the server has no secret configured.
6. Range-check every config received from the server before applying it (§6 rule 4).

• #property version "X.YY" MUST change when features are added; #define <EA>_BUILD_TAG "bN" MUST be bumped on every code change.
• Every build MUST add one history line at the top of the file: build, what it was forked from, what changed, what stayed the same.
• The panel title and the Build row in the payload MUST show the build tag. The file name is not enough to know the build.
• Branching from an old build (e.g. a hotfix off production) MUST record the lineage in the build history and in RELEASES.md ("forked from b21.1, no b22–b28 features").
• Several builds on one slug: follow §6 rules 2–5.
• Deploying a new .ex5: remove the EA from the chart and drag it back on (F7 while the EA is attached does not load the new binary). MT5 LiveUpdate dialog → choose Later.
• Update RELEASES.md when the production/test build changes (see Builds & releases).

Broker ports: 9600/9601 TickBroker · 9602/9603 AccountStatusBroker · 9605/9606 VpsStreamBroker · 9607 EaLinkBroker.

• /admin/easupported/{slug}: account list (Online when the heartbeat is < 120s old, Link/HTTP badge); select several accounts → Apply Hot config / Clear config (rendered from the schema).
• /admin/easupported/{slug}/account/{id}: two-column payload table.

• ☐ Input names exactly as in §3.2; InpCloudMyApiDomain in the form https://host/easupported/{slug}.
• ☐ composite_id uses exactly the slugify function from §4; magic is sent as a string.
• ☐ No token in source or in a committed .set.

• ☐ Heartbeat runs in OnTimer, cycle measured with GetTickCount64, ≤ 60s.
• ☐ Sends config_schema + payload (with Build, Balance, Equity).
• ☐ Config parsing separated from leader state; hot_keys reverts correctly; values range-checked.
• ☐ No network calls in the tester.

• ☐ Keys/types/enum values unchanged from builds already released on the same slug.
• ☐ The parser accepts every value in the schema.

• ☐ Uses Include/EaLink.mqh; InpLinkMode defaults to HYBRID.
• ☐ Poll() in a 200ms OnTimer; heavy work gated to 1s.
• ☐ cfg → HTTPS pull (1s debounce) → cfg_ack; hello_ok → catch-up pull.
• ☐ inst = ChartID(); Close() in OnDeinit.
• ☐ Link: line on the panel and in the payload.

• ☐ Version/build tag bumped + history line + lineage.
• ☐ MetaEditor compile with 0 errors.
• ☐ Host listed in Allow WebRequest on every terminal.
• ☐ Demo test: panel shows Server: CONNECTED, Link: UP; Apply 1 config → EA log shows it applied within ≤ 2s; Clear → reverts; broker stopped → EA keeps running over HTTP.
• ☐ RELEASES.md updated.

New EAs MUST NOT copy the points below. GoldenRobber will fix them gradually in later builds.

This standard replaces the earlier "EA ↔ fxconsole Hot-Reload Standard" (GoldenRobber 1.41.4 b16). When the contract changes: update this file first, then the EA / fxconsole / broker code.