# Accounts > Connect MetaTrader 4 and 5 accounts, follow their status while the terminal starts, read their figures, reconnect them after a lapse and disconnect them. An account is one MetaTrader 4 or MetaTrader 5 broker account you have connected. Each one runs in its own terminal, a MetaTrader instance in our cloud. Copiers use accounts as masters and followers. Reading accounts needs the `accounts:read` scope. Connecting, reconnecting and disconnecting them needs `accounts:write`. ## Connect an account [#connect-an-account] ```bash curl https://api.algotradertools.com/v1/accounts \ -H "Authorization: Bearer $ATT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "platform": "mt5", "server": "ICMarketsSC-Demo", "login": 51239876, "password": "", "credential_kind": "master", "nickname": "Funded #2" }' ``` | Field | Required | Description | | ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `platform` | Yes | `mt4` or `mt5` | | `server` | Yes | The broker server, exactly as MetaTrader shows it in its login window, up to 64 characters | | `login` | Yes | The account number, as an integer | | `password` | Yes | The account's master (trading) or investor (read-only) password | | `credential_kind` | Yes | Which of the two you sent: `master` or `investor` | | `nickname` | No | A name of up to 64 characters, shown instead of the account number | | `proxy_address` | No | A proxy for the account's terminal, as `host:port`. See [Connect through a proxy](#connect-through-a-proxy) | | `proxy_type` | No | `socks5` (the default), `socks4` or `http` | | `proxy_username`, `proxy_password` | No | The proxy's login, if it needs one | A field that accounts don't have is refused with `validation_failed` and the field code `unknown_field`. Read-only fields such as `id` are ignored. The password is stored encrypted with the terminal that will run the account, and it is never returned. The response is `201 Created` with the account in `connecting`. Its terminal now starts and logs in to the broker, which takes two to three minutes. Poll `GET /v1/accounts/{account_id}` every 15 seconds or less often until `status` is `connected` or `error`. Connecting an account takes one of your plan's account slots. When all of them are in use, or you don't have a plan yet, connecting fails with `403 plan_limit_reached`. ### Master or investor password [#master-or-investor-password] | `credential_kind` | Can be a master | Can be a follower | | ----------------- | --------------- | -------------------------------------------- | | `investor` | Yes | No: the investor password can't place trades | | `master` | Yes | Yes | The account's `can_trade` field tells you which password it was connected with. To turn an investor account into one that can follow, [disconnect](#disconnect-an-account) it and connect it again with its master password. Keep in mind that disconnecting deletes its stored history. ### Connect through a proxy [#connect-through-a-proxy] Some prop firms don't allow several traders on one IP address. Without a proxy, your terminal reaches the broker from our servers, whose IP addresses other traders use too. With `proxy_address`, the terminal reaches the broker through your own proxy instead, and the broker sees the proxy's IP address. ```bash curl https://api.algotradertools.com/v1/accounts \ -H "Authorization: Bearer $ATT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "platform": "mt5", "server": "FTMO-Server", "login": 51239877, "password": "", "credential_kind": "master", "proxy_type": "socks5", "proxy_address": "198.51.100.10:1080", "proxy_username": "", "proxy_password": "" }' ``` `proxy_address` takes only the host and port. A whole URL such as `socks5://user:pass@host:port` is refused with `validation_failed`. Put the type, username and password in their own fields. We try the proxy before the terminal starts. If nothing can be reached through it, connecting fails with `400 proxy_unreachable` and no account is created. The proxy's username and password are handled like the account's password. They are stored encrypted with the terminal and never returned. The account shows `proxy_type` and `proxy_address`. You can't change the proxy of a connected account. To change it, disconnect the account and connect it again, which deletes its stored history. ### When connecting fails [#when-connecting-fails] | Error | What to do | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `400 validation_failed` with `login`: `already_connected` | You already connected this account. List your accounts to find it | | `400 validation_failed` with `login`: `account_released` | You connected it before and its terminal was released. [Reconnect](#reconnect-after-a-lapse) it instead | | `400 invalid_credentials` | The broker rejected the login and password. Check for the right password and account number | | `400 server_not_found` | No broker server with that name. Copy it exactly as MetaTrader shows it | | `400 already_connected` | That MetaTrader account is already connected | | `400 proxy_unreachable` | Nothing could be reached through the proxy. Check its type, host and port, username and password | | `400 connect_rejected` | The account was refused for another reason, given in `detail` | | `403 plan_limit_reached` | Every account slot of your plan is in use | | `429 rate_limited` | More than 5 connects, reconnects or disconnects in a minute. Wait `Retry-After` seconds | | `503 connect_unavailable` | New accounts can't be connected right now. Try again later | | `502 terminal_unreachable`, `503 terminal_unavailable`, `504 terminal_timeout` | The terminal host didn't answer in time. Retry with backoff; a retry that finds the account already connected fails with `already_connected` | Retrying a connect is safe: if the first attempt went through, the second fails with `already_connected` instead of connecting the account twice. ## Status [#status] | `status` | Meaning | | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `connecting` | The terminal is starting and logging in | | `connected` | The terminal is logged in. Copiers can use the account | | `error` | The terminal couldn't log in or stopped working; `error` says why | | `disconnected` | The account isn't connected to its broker any more; `error` says why when it's known. Released accounts are `disconnected` too | Only `connected` accounts can be added to a copier, as a master or a follower. ## The account object [#the-account-object] ```json { "id": "9b2e7d4c-1a3f-4c8e-b5d6-7e8f9a0b1c2d", "object": "account", "name": "Funded #2", "nickname": "Funded #2", "platform": "mt5", "server": "ICMarketsSC-Demo", "login": 51239876, "credential_kind": "master", "can_trade": true, "status": "connected", "error": null, "released": false, "proxy_type": null, "proxy_address": null, "role": "follower", "figures": { "balance": 5000.0, "equity": 5031.2, "profit": 31.2, "margin": 96.0, "free_margin": 4935.2, "margin_level": 5240.83, "currency": "USD", "open_positions": 1, "as_of": "2026-10-25T14:21:15.880Z", "source": "live" }, "created_at": "2026-10-25T14:03:52.917Z" } ``` | Field | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `id` | The account's ID, a UUID | | `name` | The nickname, or the platform and login, such as `MT5 51239876` | | `nickname` | The nickname, or `""` | | `platform`, `server`, `login` | The MetaTrader account | | `credential_kind` | `master` or `investor`: which password it was connected with | | `can_trade` | `true` if it was connected with its master password, so it can be a follower | | `status` | See [Status](#status) | | `error` | Why the account is in `error` or `disconnected`, or `null` | | `released` | `true` once its terminal was released after a lapsed subscription. See [Reconnect after a lapse](#reconnect-after-a-lapse) | | `proxy_type`, `proxy_address` | The proxy its terminal reaches the broker through, or `null` for a direct connection | | `role` | `master` when a copier copies it, `follower` when it copies a copier's master, otherwise `null` | | `figures` | The latest figures, or `null` until there are any | | `created_at` | When it was connected | ### Figures [#figures] | Field | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `balance`, `equity` | In the account's currency | | `profit` | Floating profit or loss of the open positions | | `margin`, `free_margin` | Margin in use and margin still free | | `margin_level` | Equity as a percentage of margin, or `null` while no margin is in use | | `currency` | As the broker reports it, such as `USD`, `EUR` or `USC` (US cents) | | `open_positions` | The number of open positions | | `as_of` | When the terminal reported these figures | | `source` | `live` while the copier engine receives live updates from the account (figures at most about 30 seconds old). Otherwise `snapshot`: the last stored figures, saved every few minutes | ## List and read accounts [#list-and-read-accounts] `GET /v1/accounts` lists your accounts, newest first, in the [list format](/docs/limits#pagination). `GET /v1/accounts/{account_id}` returns one. An ID that belongs to someone else's account returns `404 not_found`, the same as an ID that doesn't exist. ```bash curl https://api.algotradertools.com/v1/accounts \ -H "Authorization: Bearer $ATT_API_KEY" | jq '.data[] | {name, status, role}' ``` ## Reconnect after a lapse [#reconnect-after-a-lapse] When a subscription lapses and isn't paid, the terminals of its accounts are released. Each account stays, with its stored history and `released: true`, and no longer takes an account slot. Once your plan is active again, reconnect the account to start a new terminal for it. Send the password again. It was stored with the released terminal and deleted with it: ```bash curl https://api.algotradertools.com/v1/accounts/9b2e7d4c-1a3f-4c8e-b5d6-7e8f9a0b1c2d/reconnect \ -H "Authorization: Bearer $ATT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "password": "", "credential_kind": "master" }' ``` The response is `200 OK` with the account back in `connecting`. You can send the other kind of password than the first time. `credential_kind` says which one you sent. An account with a proxy keeps it. If the proxy needs a login, send `proxy_username` and `proxy_password` again, since they went with the old terminal too. To change the proxy, send a new `proxy_address` (and `proxy_type`). An empty `proxy_address` connects directly. Reconnecting an account that still has its terminal fails with `409 account_not_released`, and the [connect errors](#when-connecting-fails) apply as well. ## Disconnect an account [#disconnect-an-account] ```bash curl -X DELETE https://api.algotradertools.com/v1/accounts/9b2e7d4c-1a3f-4c8e-b5d6-7e8f9a0b1c2d \ -H "Authorization: Bearer $ATT_API_KEY" ``` Disconnecting stops the account's terminal and deletes the account with its stored history. The response is `204 No Content`, and the account slot is free again. You can't disconnect an account that a copier uses. The request fails with `409 account_in_use`. First [delete the copier](/docs/copiers#delete-a-copier) it is the master of, or [remove the follower](/docs/followers#remove-a-follower). If the terminal can't be stopped, the request fails with `disconnect_failed` (`502`, `503` or `504`) and the account is kept. Try again shortly.