Order payloads: receiver reference

Trader feature · Last updated 4 October 2026

On Trader, the Trade Architect can send your plan to a receiver you run (an MT4/MT5 Expert Advisor, a cTrader cBot, your own script) as a broker-side pending order. This page is for whoever writes that receiver.

What ForexFin does and doesn't do

• Side, entry, stop, target, order type and risk % are yours, as typed in the Trade Architect. ForexFin sizes the position from your risk rule and checks your own send rules (time window, correlated open trades, tilt guard). It does not pick trades, move levels or time anything.
• One payload per send. It's a pending order: your broker's price feed triggers it, not ours.
• ForexFin never holds broker credentials. Your receiver places the order on your account.

Request

POST to your receiver URL, Content-Type: application/json. Headers you use:

Delivery runs through AgentDelivery, which retries on timeouts and non-2xx answers, so the same payload can arrive more than once. Other headers from the delivery service may be present; ignore them. Answer 2xx once you have stored or acted on the payload.

Payload (forexfin.order.v2)

{
  "schema": "forexfin.order.v2",
  "event": "order.plan",
  "id": "ffo_Xr3…",                         // ForexFin order id
  "idempotency_key": "u14:plan:8f3a…",      // dedupe on this
  "created_at": "2026-10-05T09:12:00.000Z",
  "valid_until": "2026-10-05T17:12:00.000Z",// refuse after this; also use as the order's expiry
  "account_label": "FTMO 100k",             // or null
  "symbol": "EURUSD",                       // canonical
  "broker_symbol": "EURUSD.pro",            // your platform's name when your journal knows it, else null
  "side": "buy",                            // buy | sell
  "order_type": "buy_limit",                // buy_limit | sell_limit | buy_stop | sell_stop
  "entry": 1.0845,
  "stop_loss": 1.0815,
  "take_profit": 1.0905,                    // or null
  "volume_lots": 0.33,                      // standard lots (100,000 units), rounded down
  "units": 33000,
  "guard": {
    "reference_price": 1.0845,              // = entry
    "max_deviation_pips": 2,
    "max_deviation_points": 20,             // 5-digit / 3-digit quotes
    "refuse_if_triggered": true
  },
  "risk": { "balance": 10000, "account_ccy": "USD", "risk_pct": 1, "risk_amount": 99, "stop_pips": 30 },
  "rules_checked": ["session_window", "max_correlated_open", "tilt_guard"],
  "source": { "app": "trade-architect", "sizing_rates": "ECB reference rates" },
  "note": "your note, or null"
}

order.test carries only schema, event, id, idempotency_key, created_at and note. Verify the signature, answer 2xx, place nothing.

Sizing uses ECB reference rates for the currency conversion (exact when the account currency is the pair's base or quote). Check volume_lots against your broker's minimum and step before placing.

What your receiver must check

1. Signature: compute the HMAC over the raw body bytes before parsing JSON, compare in constant time, and reject a t more than 5 minutes from your clock.
2. Duplicates: if you have seen the idempotency_key, answer 2xx and do nothing.
3. Expiry: refuse when now is past valid_until.
4. Already triggered: for a buy limit / sell stop, the market is through the entry when ask ≤ entry (buy limit) or bid ≤ entry (sell stop); for a buy stop / sell limit when ask ≥ entry (buy stop) or bid ≥ entry (sell limit). With refuse_if_triggered: true, refuse. With false, you may fill at market only if the price is within max_deviation_pips of the entry; otherwise refuse.
5. Place the pending order with the stop, target and an expiry of valid_until.

MT4/MT5 can't receive HTTP directly. The usual setup is a small HTTPS service that stores payloads and an EA that polls it with WebRequest; that service is where the checks above run.

Signature check, Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, sig)

Signature check, Node.js

const crypto = require("crypto");

function verify(rawBody, header, secret, tolerance = 300) {
  const parts = Object.fromEntries(String(header).split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > tolerance) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex");
  const a = Buffer.from(mac), b = Buffer.from(String(parts.v1 || ""));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Price-alert webhooks (forexfin.alert.v2)

Price alerts set to webhook delivery use the same envelope, headers and signature. X-ForexFin-Event is alert.triggered. Each alert fires once, so the idempotency key is per alert. The signing secret is per account, separate from the order receiver's; it is shown once when you create your first webhook alert, and Alerts → Delivery → new signing secret replaces it.

{
  "schema": "forexfin.alert.v2",
  "event": "alert.triggered",
  "id": "ffa_123",
  "idempotency_key": "u14:alert:123",
  "created_at": "2026-10-05T16:03:01.000Z",
  "symbol": "EURUSD",
  "broker_symbol": null,
  "asset_class": "forex",
  "direction": "above",
  "threshold": 1.12,
  "trigger_price": 1.1201,
  "current_price": 1.1203,
  "triggered_at": "2026-10-05T16:03:01.000Z",
  "note": null
}

Prices are the latest quote at the 60-second check, not a tick feed.

Set-up and limits

• Receiver URL: https, public host. Set it in the Trade Architect under Send as pending order. The signing secret is shown once; you can make a new one there.
• Pairs between the eight major currencies (USD, EUR, GBP, JPY, CHF, AUD, CAD, NZD); account currency one of the same eight.
• Up to 30 sends per hour. Sends blocked by your rules are logged with the reason.
• Your send rules: a daily time window, a limit on open journal trades that are the same bet (correlation ≥ 0.7 over 30 sessions, ECB), and an opt-in tilt guard. Overriding the tilt guard is a deliberate click and is logged.

Terms for this feature: Terms of Use, section 4. Data handling: Privacy Policy.