Make your
first connection.

Your first request.

Open the mt2api app for account access. Send MT4 requests to https://mt4.mt2api.com and MT5 requests to https://mt5.mt2api.com. The app host is separate from the API.

1. Prepare your environment. Install Python and requests. Set MTAPI_API_KEY on your backend. The example uses the MT5 API host.
2. Create a session. Use ConnectEx with a demo account and the broker’s exact server name.
3. Read your account. Store the returned token as MTAPI_SESSION_TOKEN and make the read-only request below.

import os
import requests

# Public MT5 API. Use mt4.mt2api.com for MT4.
# Keep credentials on your backend, not in browser code.
gateway = "https://mt5.mt2api.com"
headers = {"X-Api-Key": os.environ["MTAPI_API_KEY"]}
token = os.environ["MTAPI_SESSION_TOKEN"]

response = requests.get(
    f"{gateway}/AccountSummary",
    headers=headers,
    params={"id": token},
    timeout=30,
    allow_redirects=False,
)
if response.status_code != 200 or response.headers.get("X-MtApi-Error-Code"):
    raise RuntimeError("Account request failed; verify session and API status.")

account = response.json()
if not isinstance(account, dict) or not {"equity", "currency"} <= account.keys():
    raise RuntimeError("Unexpected account response.")
print(account["equity"], account["currency"])

For MT4, use https://mt4.mt2api.com/AccountSummary. Amounts use the returned currency; do not assume USD.

Two credentials. Different jobs.

The public API selects the platform by hostname: https://mt4.mt2api.com/AccountSummary or https://mt5.mt2api.com/AccountSummary. For a self-hosted gateway serving both platforms, use explicit /mt4 and /mt5 prefixes unless your deployment routes them by hostname.

• Keep API keys, passwords, and tokens on your backend. Use HTTPS or a controlled local connection.
• Compatibility login parameters contain the password in the query. Disable query logging, automatic redirects, and URL echoes in errors.
• Encode parameters with your HTTP client. Arrays use repeated keys, not comma-separated strings.
• Parameter names are case-sensitive. For example, expertID and stoploss must be spelled exactly.
• MT5 identifiers are int64. Use a lossless JSON parser when handling IDs outside JavaScript’s safe integer range.

Connect once. Keep the token.

ConnectEx accepts a trading account login, password, and server name. Success returns a plain-text token, not a JSON object. Reuse it as id for account, quote, and trading calls.

# Requires: pip install requests
import os
import requests

gateway = "https://mt5.mt2api.com"
response = requests.get(
    f"{gateway}/ConnectEx",
    headers={"X-Api-Key": os.environ["MTAPI_API_KEY"]},
    params={
        "user": os.environ["MTAPI_LOGIN"],
        "password": os.environ["MTAPI_PASSWORD"],
        "server": os.environ["MTAPI_SERVER"],
        "connectTimeoutSeconds": 60,
    },
    timeout=75,
    allow_redirects=False,
)
if response.status_code != 200 or response.headers.get("X-MtApi-Error-Code"):
    raise RuntimeError("Connection failed; inspect a redacted server error.")
token = response.text.strip()  # Keep private; do not log.
if not token or "text/plain" not in response.headers.get("Content-Type", ""):
    raise RuntimeError("Unexpected connection response.")

Repeated ordinary connections can create multiple terminal sessions. Manage concurrency in your application and call Disconnect when finished.

Find your next request.

Core endpoints for connections, accounts, quotes, orders, history, and streaming. Select a platform or search by endpoint, parameter, or topic. All ordinary operations listed below use GET; WebSocket endpoints upgrade an authenticated GET request.

Parameters shown cover the common integration surface. Optional aliases and advanced compatibility methods are not exhaustively listed. Platform-specific behavior in this guide takes precedence over assumptions based on a similar method name.

Subscribe. Then stream.

Call Subscribe or SubscribeMany over HTTP, then connect to wss://mt5.mt2api.com/OnQuote?id=… using WebSocket. Use wss: for a gateway served over HTTPS.

The handshake requires X-Api-Key. Native browser WebSocket cannot set that header; connect from your backend with a client such as Node.js ws. Do not place the API key in the URL to work around this.

// Node.js; install the ws package. Do not run in a browser.
import WebSocket from 'ws';
const { MTAPI_API_KEY, MTAPI_SESSION_TOKEN } = process.env;
const gateway = 'https://mt5.mt2api.com';
const subscribe = new URL('/Subscribe', gateway);
subscribe.searchParams.set('id', MTAPI_SESSION_TOKEN);
subscribe.searchParams.set('symbol', 'EURUSD'); // Use your broker's symbol.
const response = await fetch(subscribe, {
  headers: { 'X-Api-Key': MTAPI_API_KEY },
  redirect: 'error',
  signal: AbortSignal.timeout(30_000),
});
if (response.status !== 200 || response.headers.has('X-MtApi-Error-Code')) {
  throw new Error('Subscription failed.');
}
const url = new URL('/OnQuote', gateway);
url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
url.searchParams.set('id', MTAPI_SESSION_TOKEN);
const socket = new WebSocket(url, {
  headers: { 'X-Api-Key': MTAPI_API_KEY },
});
socket.on('message', (raw) => {
  try {
    const event = JSON.parse(raw.toString());
    if (event.type === 'Quote' && event.data) {
      console.log(event.data.symbol, event.data.bid, event.data.ask);
    } else {
      console.warn('Non-quote event; inspect and resynchronize as needed.');
    }
  } catch {
    console.warn('Invalid event; resynchronize before continuing.');
  }
});
socket.on('error', () => console.error('Stream error; check session.'));
socket.on('close', () => console.warn('Stream closed; resynchronize before reconnecting.'));
// On shutdown, close the socket AND call UnSubscribe or Disconnect.

{
  "type": "Quote",
  "id": "<SESSION_TOKEN>",
  "timestampUTC": 0,
  "data": {
    "symbol": "<BROKER_SYMBOL>",
    "bid": 0,
    "ask": 0,
    "time": "<BROKER_TIME>"
  }
}

Zeros above illustrate field types, not actual quotes. timestampUTC is the gateway’s frame-send time in Unix milliseconds. data.time is the broker quote time and may have different timezone semantics.

• Each socket has a bounded 512-event queue; a slow consumer can be disconnected.
• Order events are sampled snapshots. Intermediate states can be missed; there is no replay or sequence-offset guarantee.
• After a disconnect, refresh accounts, positions, pending orders, and relevant history before resuming.
• Closing the socket does not remove explicit symbol subscriptions. Call UnSubscribe or Disconnect when finished.

Respect the platform differences.

• Opening size uses volume; closing size uses lots. lots=0 closes all current volume.
• Slippage is in points, not pips. Validate lot size and increments against the actual broker symbol.
• For modifications, submit existing stop-loss and take-profit values if preserving them. Zero clears them.
• MT5 Task and Safe methods do not provide durable idempotency. OrderSendSafe does not accept expertID.
• MT5 current position tickets, position identifiers, pending-order tickets, and deal tickets are different concepts. Use the current ticket for closing and the position identifier for deal lookup.
• A successful response may reflect a partial fill. Reconcile requested volume, current positions, and deals.

Check more than the status code.

Ordinary API errors default to HTTP 201 and carry X-MtApi-Error-Code. A successful-looking HTTP status or MT5 code: 0 does not establish success. Inspect the error header, HTTP status, error-shaped body, and expected success structure.

HTTP/1.1 201 Created
Content-Type: text/json
X-MtApi-Error-Code: TRADE_RESULT_UNKNOWN

{
  "message": "<REDACTED_ERROR_MESSAGE>",
  "stackTrace": null,
  "nodeName": "<NODE>",
  "user": 0,
  "code": 0
}

MT4 ordinary error bodies contain message, stackTrace, code. MT5 additionally includes nodeName, user. Log only redacted context. An empty history result after a connection failure does not prove a trade was never executed.

Build against verified behavior.

Core demo workflows have been exercised on IC Markets MT4 and MT5. IG MT4 has read-only connection evidence, while trading was rejected in documented tests. That does not establish support for every broker, instrument, account mode, or parameter combination.

• /healthz checks gateway liveness. /readyz checks terminal configuration; it does not prove a broker login or trading permission.
• /capabilities describes deployment limits. Declared routes and static implementation coverage are not acceptance evidence.
• MT5 timestamps may carry Z without full broker-time normalization. Use explicit, verified broker-calendar ranges for history.
• MT4 history is limited to loaded terminal history. MT5 history depends on broker and SDK availability. ClosedOrders is not a full reconciliation source.
• OTP/certificate login, general proxy support, broker account creation, and several statistics and timezone functions remain incomplete.
• The self-hosted implementation requires MetaTrader terminal templates inside Docker. Connection capacity depends on infrastructure and workload.