MT5 — Instance lifecycle

An instance is a managed MT5 terminal bound to one broker login. It is identified by its MT5 accountId (login number).

List instances

GET /api/external/instances

curl -s "$ATLAS_BASE_URL/api/external/instances" \
  -H "Authorization: Bearer $ATLAS_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "ci_9f8a...",
      "accountId": "5012345",
      "serverName": "ICMarketsSC-Demo",
      "brokerName": "IC Markets",
      "name": "alpha-01",
      "state": "RUNNING",
      "type": "TICKS_TRADE",
      "enabled": true,
      "lastActiveAt": "2026-05-25T10:00:00.000Z",
      "connectedAt": "2026-05-25T09:00:00.000Z",
      "errorMessage": null,
      "statusMessage": "Connected",
      "createdAt": "2026-05-01T00:00:00.000Z",
      "updatedAt": "2026-05-25T10:00:00.000Z"
    }
  ]
}

List MT5 servers

GET /api/external/servers — the MT5 broker servers Atlaas already carries. Use a serverName from here when you create an instance. A server that isn't listed is still accepted, but its terminal waits in PENDING ("Awaiting server setup...") until the Atlaas team has added that server.

curl -s "$ATLAS_BASE_URL/api/external/servers" \
  -H "Authorization: Bearer $ATLAS_API_KEY"

{
  "success": true,
  "data": [
    {
      "serverName": "ICMarketsSC-Demo",
      "brokerName": "IC Markets",
      "displayName": null,
      "serverType": "demo",
      "defaultSymbol": "EURUSD"
    }
  ]
}

List regions

GET /api/external/regions — regions that can take a new MT5 terminal right now. Only regions with free runner capacity are returned, so any id here is a valid regionId for create.

curl -s "$ATLAS_BASE_URL/api/external/regions" \
  -H "Authorization: Bearer $ATLAS_API_KEY"

{
  "success": true,
  "data": [{ "id": "reg_9f8a...", "code": "lon", "displayName": "London", "description": null }]
}

Create an instance

POST /api/external/instances

Field	Type	Required	Notes
`accountId`	string	✅	MT5 login number
`serverName`	string	✅	MT5 server name (e.g. `ICMarketsSC-Demo`), ideally from List MT5 servers
`password`	string		MT5 password (stored server-side)
`brokerName`	string		Display label
`name`	string		Display label
`type`	enum		`TICK` (default), `TICKS_TRADE`, or `TRADE`
`regionId`	string		Region `id` from List regions. Omit to place in any region

curl -s -X POST "$ATLAS_BASE_URL/api/external/instances" \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "5012345",
    "serverName": "ICMarketsSC-Demo",
    "password": "your-mt5-password",
    "name": "alpha-01",
    "type": "TICKS_TRADE"
  }'

Returns 201 with the instance object. A runner is auto-assigned; the instance starts in PENDING and transitions to RUNNING once the runner deploys it.

Errors: 400 missing fields, or a regionId that is empty, unknown or disabled · 402 not enough credits for the provisioning fee · 403 instance limit reached · 409 an instance with this accountId already exists · 503 no available runner for that server, or none with room in the chosen region.

Get an instance

GET /api/external/instances/{accountId}

curl -s "$ATLAS_BASE_URL/api/external/instances/5012345" \
  -H "Authorization: Bearer $ATLAS_API_KEY"

Start an instance

POST /api/external/instances/{accountId}/start — re-enables and queues the instance for deploy.

curl -s -X POST "$ATLAS_BASE_URL/api/external/instances/5012345/start" \
  -H "Authorization: Bearer $ATLAS_API_KEY"

Stop an instance

POST /api/external/instances/{accountId}/stop — disables and stops the terminal.

curl -s -X POST "$ATLAS_BASE_URL/api/external/instances/5012345/stop" \
  -H "Authorization: Bearer $ATLAS_API_KEY"

Delete an instance

DELETE /api/external/instances/{accountId}

curl -s -X DELETE "$ATLAS_BASE_URL/api/external/instances/5012345" \
  -H "Authorization: Bearer $ATLAS_API_KEY"