API reference
REST API
Base URL https://api.mfxhub.com/v1. Every request is signed; every write carries Idempotency-Key. The full contract (OpenAPI 3.1.0) is published with each release; a Postman collection and a signing guide serve any language without an SDK.
terminals
Provision, inspect, drain and retire terminals (scope term:read / term:write)
| Method | Path | What it does |
|---|---|---|
| GET | /terminals | List the tenant's terminals, newest first (cursor pagination) |
| POST | /terminals | Provision a terminal — answered at once in state REQUESTED; the move to capacity is asynchronous idempotent |
| GET | /terminals/{id} | Inspect a terminal — state and how long it has been in it, observed conditions, build |
| PATCH | /terminals/{id} | Change a running terminal - today its refresh rate idempotent |
| DELETE | /terminals/{id} | Retire a terminal — it drains, then retires; answered with its state now idempotent |
| PUT | /terminals/{id}/instruments | Replace a terminal's instrument list in place — same terminal, same credential, same history idempotent |
| POST | /terminals/{id}/drain | Drain a terminal - it is closed gracefully and kept, holding no host and not billed, until you resume it idempotent |
| POST | /terminals/{id}/resume | Resume a drained terminal - placed and logged in again exactly as a new terminal is idempotent |
| POST | /terminals/{id}/restart | Restart a stuck terminal — governed, followed as an operation (, mock idempotent |
| GET | /terminals/{id}/operations/{operation_id} | A lifecycle operation on the terminal — its state and timeline |
| DELETE | /terminals/{id}/operations/{operation_id} | Cancel a queued operation — only while it waits idempotent |
credentials
Submit or rotate broker credentials — pass-through to Key Vault, response by reference (term:write)
| Method | Path | What it does |
|---|---|---|
| POST | /terminals/{id}/credentials | Submit or rotate credentials (master | investor) — stored in Key Vault, response by reference, never echoed idempotent |
execution
Orders and positions — signed, idempotent, per-terminal FIFO (exec:write / exec:read)
| Method | Path | What it does |
|---|---|---|
| POST | /terminals/{id}/orders | Place a market or pending order → 202 + command_id (expires_in default 10 s) idempotent |
| POST | /terminals/{id}/orders/{ticket}/cancel | Cancel a pending order (inventory gap G1 — first-class); no body, the ticket is the order idempotent |
| POST | /terminals/{id}/orders/{ticket}/modify | Amend a pending order - its price, stop loss, take profit or expiry; what is not sent stays as it is idempotent |
| POST | /terminals/{id}/positions/{ticket}/modify | Modify SL/TP — one or both idempotent |
| POST | /terminals/{id}/positions/{ticket}/close | Close a position in full idempotent |
| POST | /terminals/{id}/positions/{ticket}/close-partial | Partially close a position — the volume to close, inside the symbol's step idempotent |
| POST | /terminals/{id}/positions/{ticket}/close-by | Close a position against an opposite one in the same symbol (hedging accounts) idempotent |
| PUT | /terminals/{id}/positions/{ticket}/trailing-stop | Set or change a position's trailing stop, kept by the worker on the host idempotent |
| DELETE | /terminals/{id}/positions/{ticket}/trailing-stop | Remove a position's trailing stop; the stop stays where it is idempotent |
| GET | /commands/{id} | Command state + result — mt5_retcode, retcode_text, reason (granular), comment_raw, tickets, exec_price, exec_volume, broker_latency_ms, agent_latency_ms, terminal_state |
account
Live account state, positions, orders, deal history, the user's own spread (acct:read)
| Method | Path | What it does |
|---|---|---|
| GET | /terminals/{id}/account | Balance, equity, margin (as_of) + profile fields (currency, leverage, company, account_type, margin_mode, trade_allowed, expert_allowed) |
| GET | /terminals/{id}/positions | Open positions (as_of) — the whole snapshot, never paged |
| GET | /terminals/{id}/orders/pending | Pending orders (as_of) — the whole snapshot, never paged |
| GET | /terminals/{id}/history/deals | Deals in a window, newest first by (time, deal) |
| GET | /terminals/{id}/spread | The user's own spread per instrument, read from the user's terminal (a pool cannot serve it) |
md
Broker catalogue, servers, symbols with trade_mode, streaming subscriptions, candles (md:read / md:write)
| Method | Path | What it does |
|---|---|---|
| GET | /brokers | Supported brokers and the symbol variant their accounts use |
| GET | /brokers/{id}/servers | Server discovery — the the terminal server strings a credential can name, demo or live |
| GET | /brokers/{id}/symbols | The tenant's symbol catalogue for one server and account type — spec, trade_mode (quotable ≠ tradeable), pip_value_per_lot (G4), spec_hash (G3), trade sessions and derived status |
| GET | /brokers/{id}/symbols/{symbol} | Check that a symbol exists for this server and account type, with its spec and status |
| GET | /brokers/{id}/symbols/{symbol}/quote | The last price with its age — a snapshot from the tenant's own terminal, never a stream |
| GET | /md/subscriptions | List subscriptions, newest first |
| POST | /md/subscriptions | Streaming subscription (server, symbol, timeframes, delivery ws|redis_push) — state pending until first tick idempotent |
| DELETE | /md/subscriptions/{id} | Stop a subscription idempotent |
| GET | /md/candles | Historical candles by bar time, read through one of your own terminals on the server; at most 1000 bars per call, the newest of the window |
| GET | /md/ticks | Tick history, forward from a moment, read through one of your own terminals on the server; at most 1000 ticks per call (design/md-ticks.md) |
stream
Multiplexed WebSocket stream — md, candles, events, results
| Method | Path | What it does |
|---|---|---|
| GET | /stream | WebSocket upgrade (wss://ws.mfxhub.com/v1/stream; dev wss://ws.dev.mfxhub.com/v1/stream) — HMAC at upgrade; channels md · candles · events · results · account · ea · book; 24 h max lifetime; drop-oldest ticks per slow client |
farms
Tenant-visible, read-only view of the tenant's farms (term:read)
| Method | Path | What it does |
|---|---|---|
| GET | /farms | The farms the tenant's plan places terminals on — os, region, usages, refresh rate, instrument limit, status (read-only in S1) |
| GET | /farms/{id} | One of the farms the tenant's plan allows; any other, another tenant's included, is 404, never 403 |
usage
Quota consumption and remaining budget (billing:read)
| Method | Path | What it does |
|---|---|---|
| GET | /usage | Quota consumption and remaining budget per metric (commands/s, md msgs/s, ws conns) |
connectors
Tenant-owned Redis push delivery — reserved in v1, served from Stage 2 (md:write)
| Method | Path | What it does |
|---|---|---|
| POST | /connectors/redis-push | Tenant-owned Redis delivery configuration (endpoint credentials → Key Vault by reference) idempotent |
expert advisors
A tenant's own expert advisors: upload the source, read the verdict and the report, withdraw (ea:read / ea:write). Only for a tenant with a farm that runs customer code
| Method | Path | What it does |
|---|---|---|
| PUT | /terminals/{id}/expert-advisor | Attach an approved version of your EA to a terminal - governed, followed as an operation; a trial with trading off comes first idempotent |
| DELETE | /terminals/{id}/expert-advisor | Detach the EA from a terminal - governed; the terminal is relaunched from a fresh copy of its folder without it idempotent |
| POST | /terminals/{id}/expert-advisor/confirm | Turn on live trading for an EA on a real-money account after a green trial, with the one-time code from the trial email |
| GET | /expert-advisors | List the tenant's expert advisor versions, newest first (cursor pagination) |
| POST | /expert-advisors | Upload an expert advisor's source to be checked idempotent |
| GET | /expert-advisors/{id} | One version - its state, its verdict, each check and where it runs |
| DELETE | /expert-advisors/{id} | Withdraw a version idempotent |
| GET | /expert-advisors/{id}/report | The report of one version - the verdict, one colour for each group of rules, every finding with its lines and what to change |
| GET | /tenant/contacts | Who at your company is told about your expert advisors - the contacts and their roles |
maintenance
Planned maintenance on the tenant's terminals: what is scheduled and in progress, what is paused and until when, and where each terminal is (term:read; design/maintenance-mode.md)
| Method | Path | What it does |
|---|---|---|
| GET | /maintenance | Planned maintenance on your terminals - windows scheduled, in progress and recently ended |
| GET | /maintenance/{id}/terminals | Your terminals in one window - waiting for their batch, moving to a new machine, back - each with its own expected time |
webhooks
MFX Hub calls the tenant's own HTTPS address for the events it asks for, signed, tried again when it fails, and kept when it keeps failing (hook:read / hook:write; design/tenant-webhooks.md)
| Method | Path | What it does |
|---|---|---|
| GET | /webhooks | The tenant's webhook endpoints, each with how it is doing |
| POST | /webhooks | Register an endpoint; its signing secret is in this answer and in no other idempotent |
| GET | /webhooks/{id} | One endpoint |
| PATCH | /webhooks/{id} | Change the address or the event types, pause or resume idempotent |
| DELETE | /webhooks/{id} | Remove an endpoint and its secret |
| POST | /webhooks/{id}/rotate-secret | A new signing secret; the previous one signs beside it for a day idempotent |
| POST | /webhooks/{id}/test | Send a webhook.test event to this endpoint alone |
| GET | /webhooks/{id}/failures | What did not arrive at the first try - each event, every attempt, where it stands |
| POST | /webhooks/{id}/replay | Send again the events after a cursor of the stream, or one dead letter idempotent |