TS MT5 API - developer guide

A hosted REST and WebSocket API for MetaTrader 5 accounts. Plain HTTPS and JSON, from any language. Demo and live accounts both work - on a live account every order is real.

1. Get started

1. Log in and open the TS MT5 API page. Start your free 7-day trial (one per user).
2. Copy three things: your API key (shown only once - it cannot be shown again), your base URL, and your two account ids.
3. An account id looks like t1a2b3c4d5e6f7a8b-1. It is not your MT5 login number: it is a slot that holds one MT5 login. Your ids stay the same if you get a new key, and they are listed under "Your access" on that page.
4. Lost the key? Revoke it on that page and get a new one. Revoking ends every session the key opened at once, so stop your strategy first. A new trial key keeps your trial's end date and what is left of its 300-order allowance, and it can use the MT5 logins you already added.

Examples below use https://API_HOST; when you are signed in, this page fills in your base URL. Fields not described here are diagnostic and may change or disappear - do not depend on them.

2. Quickstart

# 1. Add your MT5 login under one of your account ids (once). Send login as a string.
curl -s -X PUT https://API_HOST/accounts/ACCOUNT_ID \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"login": "12345678", "password": "your-mt5-password", "server": "Broker-Server"}'

# 2. Open a session (answers 201). Check session_ready before trading (section 5).
curl -s -X POST https://API_HOST/connect \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"account_id": "ACCOUNT_ID", "magic": 1001, "label": "my-strategy"}'
# -> {"token": "...", "account_id": "ACCOUNT_ID", "expires_in": 900, "session_ready": {...}, "trial": {...}, ...}

# 3. Use the session token for trading, market data and account calls
export TOK=SESSION_TOKEN
curl -s https://API_HOST/symbols/resolve/XAUUSD -H "Authorization: Bearer $TOK"   # -> the broker's name, e.g. XAUUSD_l
curl -s https://API_HOST/quote/XAUUSD_l -H "Authorization: Bearer $TOK"
curl -s -X POST https://API_HOST/orders -H "Authorization: Bearer $TOK" \
  -H 'Idempotency-Key: order-0001' -H 'Content-Type: application/json' \
  -d '{"symbol": "XAUUSD_l", "operation": 0, "lots": 0.01, "sl": 4400.0, "tp": 4600.0}'
curl -s https://API_HOST/positions -H "Authorization: Bearer $TOK"

The same in Python (any HTTP client works; this uses requests):

import uuid, requests
BASE, KEY, ACCT = "https://API_HOST", "YOUR_KEY", "ACCOUNT_ID"

c = requests.post(f"{BASE}/connect", headers={"X-API-Key": KEY},
                  json={"account_id": ACCT, "magic": 1001}, timeout=60)
c.raise_for_status()                             # 401/422/429/503: see section 13 - do not loop
s = c.json()
H = {"Authorization": f"Bearer {s['token']}"}
if not s.get("session_ready", {}).get("trade", True):
    raise SystemExit("connected, but orders are not accepted yet - see section 5")

res = requests.get(f"{BASE}/symbols/resolve/XAUUSD", headers=H, timeout=30)
res.raise_for_status()                           # 404 lists candidates: pick your broker's name
sym = res.json()["name"]
r = requests.post(f"{BASE}/orders", timeout=90,
                  headers={**H, "Idempotency-Key": str(uuid.uuid4())},
                  json={"symbol": sym, "operation": 0, "lots": 0.01})
if r.status_code == 201:
    ticket = r.json()["position"]["ticket"]      # use this ticket to modify or close
elif r.status_code == 409 and r.json().get("error") == "not_confirmed":
    pass                                         # do NOT resend - see section 11

3. Keys and sessions

POST /connect

Body: account_id (one of yours), magic (required, any whole number, 0 allowed) and optional label. Optional "fresh": true forces a new login to your broker (see below), and optional "otp" carries a one-time password for brokers that ask for one. It answers 201 with token, account_id, magic, expires_in (idle seconds), reused, capabilities, investor (true = read-only, every write answers 403 investor_mode), session_ready and trial. Connecting can take tens of seconds: use a client timeout of at least 60 s.

Token lifetime

• A token ends after 15 minutes without a request or 12 hours of age, and it can end earlier (for example during maintenance or when your key is revoked). Any request, or an open stream, keeps it alive.
• On 401 no_session: call POST /connect once, then continue. If that connect answers 401 key_expired, or 401 with no error code, stop: your key no longer works. 401 login_refused is different - your broker needs something extra (for example an otp); its reason says what.
• Open one session and reuse its token. POST /connect and the /accounts calls share a small budget (section 14), so never connect per request.
• If a session is already open on the account, a new connect shares that broker login ("reused": true). After you change a saved password, connect with "fresh": true: it first ends every other session on that MT5 login (their tokens then answer 401 no_session), then logs in again. If that new login fails, those sessions stay ended.
• POST /disconnect ends the session ({"closed": true}). Positions and orders are not touched. Idempotency keys belong to a session and are forgotten when it ends.

4. Your accounts

• Saving does not check the login. A wrong login, password or server shows up at POST /connect, usually as 503 broker_closed_session. Fix it with PUT and connect again with "fresh": true. Do not retry a failing login in a loop - repeated wrong passwords can get your MT5 account locked by your broker.
• If the save reply contains "server_known": false, we do not recognise that server yet and POST /connect will answer 422 unknown_server. Check the spelling; if it is right, email us your broker's name and the exact server name. You do not need to add the account again.
• A re-save replaces the whole credential: send login, password and server (and role, if not master) every time. A session already open keeps the old login until you reconnect with "fresh": true.
• Connecting to an id with nothing saved answers 400 bad_request.
• 409 on PUT: that MT5 login on that server is already added under an id that is not yours. Contact us if the login is yours. You may add the same login under both of your own ids; they then share one connection.
• You can list and remove your saved accounts until your key stops working, including during the wind-down after a trial ends (section 14). Adding or changing one (including a password change) stops at expiry.
• Deleting an account also clears its one-time setup, so re-adding the same login may need that setup again (section 5). While a session on that login is still open, POST /connect keeps sharing it even after a delete - disconnect first.
• To change a password, re-save with PUT - do not delete and re-add. Do not move a login between your two ids; contact us if you need to.
• server_address is not accepted from your key (422 server_address_not_allowed): if we do not know your broker yet, contact us and we add it.

5. Can the session trade yet?

A successful connect does not by itself mean orders will be accepted. Read session_ready in the connect reply (also on GET /connection, together with connected):

• read: true - your balance and positions have loaded.
• trade: true - orders can be accepted. When false, new orders answer 409 not_tradable and nothing is sent to your broker; closing and stop changes may still work.

Right after connecting this can take a few seconds. Some brokers need a one-time setup on our side before a newly added account works fully. Until then reads can be incomplete too - check read and book_read (section 7) before you treat the account as flat. Once the setup is done, an open session does not pick it up: connect again with "fresh": true (your other sessions on that account end, so connect them again too). If trade stays false for more than a few minutes, email us your account id. Each refused order still uses one unit of your new-order allowance, so never retry in a loop.

trade: true while read is false means trading is not yet proven: wait for read: true. trade: true also does not override a read-only account - see investor in the connect reply.

6. Symbols and prices

Symbol names differ by broker

Always trade the name returned by GET /symbols/resolve/{base} (e.g. XAUUSD -> XAUUSD_l). XAUUSD_l in these examples is one broker's name. If resolve answers 404, its candidates list shows what your broker calls the instrument (for example GOLD) - pick one and use it exactly. Order, quote and stream calls also map a base name for you (POST /orders returns requested_symbol, GET /quote returns requested), but the ?symbol= filter on /orders and /history needs the broker's exact name.

URL-encode symbol names in paths and queries: names can contain #, + or . (#AAPL becomes %23AAPL; XAUUSD+ in a query becomes XAUUSD%2B).

For a symbol you hold, when no tick arrives /quote can return the position's mark price: source is position_mark, bid equals ask (not a tradable spread) and there may be no time. age_seconds and max_age_ms measure when we received a price, not when it traded.

7. Positions, orders and history

History may answer 501 or 503 when your broker does not send it in time; you never get a partial history. Retry once after a few seconds, with a shorter range if you asked for a long one.

8. Placing orders

POST /orders        (session token, Idempotency-Key recommended)
{"symbol": "XAUUSD_l", "operation": 0, "lots": 0.01, "sl": 4400.0, "tp": 4600.0, "deviation": 50}

• Size. lots is sent exactly as given - never rounded, capped or raised. Read min_lots, max_lots and lot_step from GET /symbols/{name} and send a multiple of lot_step between them. An off-grid or too-small size is refused by your broker (422 rejected, retcode 10014) and still counts toward your allowance.
• Price. Market orders (0, 1) need no price. Types 2-7 need price; 6 and 7 also need stop_limit_price (price is the stop that triggers; stop_limit_price is the limit order placed once it triggers). Prices, SL and TP are rounded to the symbol's tick, so levels you read back can differ slightly.
• SL/TP. For a BUY put sl below and tp above the price; mirror this for a SELL. Levels closer than the symbol's stop distance are refused (422 rejected, retcode 10016).
• Slippage. deviation is the most slippage you accept, in points (0-10000). The default is 1000 points, which is large on some symbols - set your own.
• Fill policy. Optional fill_policy: fok, ioc or return; leave it out to use the symbol's own. Pending orders accept only return.
• Expiry (pending orders). expiration_type: gtc (default), today, specified or specified_day, with expiration as a future ISO-8601 UTC time (a time with no zone is read as UTC) - required for specified/specified_day, refused for gtc/today. The expiration you read back from GET /orders is in broker server time. Also send server_utc_offset_minutes (from serverTimeZone in GET /account/details). Any expiry on a market order is refused (422 expiration_on_market).
• Comment. comment is accepted but ignored: orders reach your broker without one. Identify orders by their ticket.
• Check GET /symbols/{name}/session-state first: an order sent outside trading hours may end in 409 not_confirmed.
• Netting accounts: close a position with the close endpoints (section 9), not with an opposite-side order. An opposite order that flattens the position can answer 409 not_confirmed even though it filled - check GET /positions.
• With fill_policy: "ioc" a market order can fill only part of the size and still answer 201: read position.lots.
• Deviation, fill policy, expiry and moving pending orders are newer options: try them on a demo account before relying on them live.

The reply

• Success is 201. A market order is answered only once the new position shows on your account: the reply carries position. Use position.ticket to modify or close it (a top-level ticket can be 0). On a netting account position is the whole combined position and netting.filled_lots is what this order added.
• A pending order (2-7) is answered as soon as your broker accepts it. If its ticket is 0, read GET /orders (and GET /positions, in case it already filled) before sending it again.
• Timing. A market order usually takes a few seconds but can take up to about a minute, longer if another call on the same account is in progress (calls on one account run one at a time). Set your client timeout to at least 90 seconds for orders and closes, and always send an Idempotency-Key.

9. Changing and closing

The realised result of a closed position is in GET /history/positions?position=TICKET (profit, commission, swap, fee, net).

10. Idempotency

• Send a unique Idempotency-Key per intended order or close (POST /orders, POST /positions/{ticket}/close, POST /positions/close). Never reuse a key across different requests.
• Same key, same body, first call finished: you get the original result again, and no second order. Repeats do not use your allowance (they do count toward the 2-per-second order rate).
• Same key while the first call is still running (for example after a client timeout): 409 with detail.error = "idempotency_in_progress" and Retry-After. Nothing new was sent - wait, then repeat the same request.
• Same key after the first call ended in 409 not_confirmed (or an unexpected error): you get 409 not_confirmed again and nothing is sent. Check your positions (section 11).
• Same key after the first call was refused before reaching the broker (e.g. 422 rejected, 403 quota_exhausted, 409 not_tradable): the key is free again.
• Same key with a different body: 409 with only {"detail": "...already used with different parameters"} - a bug in your code. Do not retry; check positions before sending the corrected order under a new key.
• Keys are remembered for 10 minutes, under the session token they were sent with. They are forgotten when the session ends, are not recognised under a new token, and do not survive a service restart.

11. When the outcome is unknown

1. If you still have the same token and are within 10 minutes, repeat the exact request with the same Idempotency-Key and body: you get the original result, idempotency_in_progress (wait and repeat), or not_confirmed again. Later than that, or after a restart, the key is forgotten and a repeat is a new request - go to step 2 instead. After your key's expiry a repeat answers 403 trial_ended: go to step 2.
2. Read GET /positions and trust an empty list only when book_read is true. Look for a position on that symbol and side opened after your request (opened_at), and check GET /history?days=1 for a fill that already closed. For pending orders read GET /orders.
3. If you find it, use its ticket. If there is nothing and book_read is true, nothing was filled: send the order again with a new key.
4. For a close: read GET /positions with book_read: true. If the ticket is gone, it is closed. If it is still there, compare its lots with what you expected: after a partial close the position stays open with fewer lots, so close again only the part that is still missing (with a new key). For an SL/TP change: read the position's sl/tp and send the PATCH again if needed. For a cancel: read GET /orders.
5. After any reconnect, check before resending: idempotency keys do not carry over to a new token.

A 429 is the opposite case: nothing was sent, so retrying after Retry-After is correct.

12. Streaming

Open a WebSocket to wss://API_HOST/stream and send the first message - a JSON object with your session token - within 10 seconds. The token goes in the message, never in the URL.

-> {"token": "SESSION_TOKEN", "symbols": ["XAUUSD_l"], "interval_ms": 500}
<- {"type": "subscribed", "symbols": ["XAUUSD_l"], "account_id": "ACCOUNT_ID", "interval_ms": 500, ...}
<- {"type": "quote", "symbol": "XAUUSD_l", "bid": 4507.82, "ask": 4508.24, "time": "...", "age_seconds": 0.4, "source": "tick"}
<- {"type": "position_opened", "ticket": 555, "symbol": "XAUUSD_l", "lots": 0.01, ...}

• Options (first message only - later messages are ignored; to change, close and reopen): symbols (a list of strings, up to 50; base names are mapped, subscribed.symbols lists the broker names used, sorted, and events carry only broker names - so resolve names first), interval_ms (0-60000, default 0: the minimum gap between price updates; you always get the newest price, never a backlog), ohlc (timeframes M1 up to D1, e.g. ["M1","M5"]: bars built from bid ticks, sent with closed: false while forming and closed: true when done; events give the timeframe as minutes, e.g. 5 for M5; the first bar can be partial, and closed: true arrives with the first tick of the next period, not exactly at the boundary) and profit: true (floating P&L updates, sent on price ticks - so subscribe the symbols you hold).
• Events: subscribed, quote, position_opened, position_changed (lots, SL or TP changed, with was), position_closed, order_update, ohlc, profit, heartbeat (every 15 s when quiet), lagged (events were dropped: re-read GET /positions), error (e.g. a symbol your account does not have - it stays in subscribed.symbols and the error repeats, so resolve names first), session_closed (connect again, then reopen), and reconnecting/reconnected/reconnect_failed (the link to your broker; after reconnect_failed, connect again with "fresh": true). Ignore types you do not use.
• The stream reports changes, not state. Positions already open when you subscribe are not announced. Wait until GET /positions shows book_read: true, open the stream, then read GET /positions again and apply events on top, matched by ticket. Re-read after lagged, reconnected or a drop of your own connection.
• Position events cover every position on the account, whatever symbols you chose (an empty symbols list gives trade events only). Working (pending) orders produce no events - poll GET /orders. position_closed.profit is the last floating value; the realised result is in GET /history/positions.
• If nothing at all arrives for about 45 seconds plus your interval_ms, treat the connection as dead and reopen with the same token.
• Refusals close the socket: no first message in time, or a bad one: close code 4400 (an error message may say why); invalid or expired token: an error message with no_session and code 4401 (connect again); more than 4 open streams on the account or more than 50 symbols: error rate_limited and code 4429 (check scope: for stream_symbols ask for 50 or fewer symbols and do not retry; for streams close another stream first - a just-closed stream can hold its slot for up to about 20 seconds, so back off with jitter, never retry in a tight loop). The WebSocket never says key_expired: if POST /connect then answers 401 key_expired, stop.

If your client cannot use WebSockets, the same stream is available as server-sent events: GET https://API_HOST/stream?symbols=XAUUSD_l,EURUSD&interval_ms=500 with the Authorization header. Each message is event: <type> plus data: <json>. There is no subscribed event; options are query parameters (symbols=A,B, interval_ms=, ohlc=M1,M5, profit=true); refusals arrive as ordinary HTTP errors (400/401/422/429) before the stream starts.

13. Errors

Errors are JSON with a human-readable detail. Most also carry error, a stable code to branch on; any status can come with detail only - for example a missing or unknown API key, a missing token, an account id not on your key, an Idempotency-Key reused with a different body, or a bad query parameter. Branch on the HTTP status first, then on error when present (for idempotency_in_progress it is inside detail). Many errors carry retry_safe: true means retrying is safe (after Retry-After), false means do not retry blindly. An unexpected server error answers 500 with a plain-text body, so do not assume every error body is JSON.

14. Trial, expiry and limits

Your trial

• One free trial per user: 7 days from your first key, with 300 new orders in total. A replacement key keeps the trial's end date and what is left of the allowance. A new trial cannot be started after the window ends.
• Responses to requests made with your key or session carry X-Trial-Status (active, or grace during the wind-down), X-Trial-Expires (ISO-8601 UTC), X-Trial-Seconds-Left (until expiry; 0 during the wind-down) and X-Trial-Orders-Left. POST /connect returns the same in its trial object, plus grace_until - when the wind-down ends and the key stops working.

Expiry has two steps

1. At the expiry time, opening stops: new orders answer 403 trial_ended, and adding accounts stops.
2. For the next 24 hours (until grace_until) you can still connect, read, close (POST /positions/close is the clean way to flatten), cancel and move stops, and list or delete your saved accounts.
3. After that the key stops working (401 key_expired) and every session and stream ends.

What counts as a new order

Every POST /orders that passes authentication, validation, rate limits and the trial checks uses one unit, whatever happens next: filled, refused by your broker (422 rejected), refused because the session is read-only, or 409 not_confirmed. The 422 checks made before sending (expiration_on_market, invalid_expiration, fill_policy_not_allowed and the like) count too. So do 409 not_tradable, 403 investor_mode, and a 404 or 501 from POST /orders. Not counted: 401, 422 invalid_request, 429, 403 trial_ended, 403 quota_exhausted, 409 idempotency_in_progress, a 409 for a reused key with a different body, and idempotent repeats. Closes, cancels and SL/TP changes never count.

Member keys

Team members and paid users get member keys: renewable, 30 days each (never past the membership's own end), with their own new-order allowance. They follow the same expiry, wind-down and headers as trial keys.

Rate limits

Closing has its own larger budget, so a busy order loop can never stop you reducing risk. Positions and balance update when your broker pushes a change; polling faster than every few seconds gains little - use the stream. If your broker answers "too many requests" (retcode 10024), calls on that account pause briefly and may answer 429; wait for Retry-After.

15. Times and clocks

• Broker server time (the broker's own clock, no zone applied): bar time and from/to, history from/to and deal time, quote time, symbol session times.
• Also broker server time: pending-order expiration, time_setup and time_done in GET /orders and GET /history/orders; open and close times in GET /history/positions; stream ohlc bar time. (The expiration you send is UTC.)
• UTC: pnl_at, the X-Trial-* headers, stream heartbeat and profit times, and position opened_at once your broker's time zone is known (serverTimeZone not null in GET /account/details). Until then opened_at is the broker's own clock: allow for the offset when comparing it with your request time.
• serverTimeZone in GET /account/details is the server's UTC offset in minutes. Pass it as server_utc_offset_minutes whenever you set a pending-order expiry.

16. Checklist before going live

Questions or a broker we do not recognise yet? Contact us from the TS MT5 API page.