Account

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/algotradertools/json-schema/algotradertools-account-schema.json",
  "title": "Account",
  "description": "A MetaTrader 4 or 5 account, connected through its own hosted terminal.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/algotradertools-openapi.json#/components/schemas/Account",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The account's ID.",
      "format": "uuid"
    },
    "object": {
      "type": "string",
      "enum": [
        "account"
      ],
      "description": "What this object is."
    },
    "name": {
      "type": "string",
      "description": "Its nickname, or the platform and login."
    },
    "nickname": {
      "type": "string",
      "description": "Empty when none was given."
    },
    "platform": {
      "type": "string",
      "enum": [
        "mt4",
        "mt5"
      ]
    },
    "server": {
      "type": "string",
      "description": "The broker's server."
    },
    "login": {
      "type": "integer",
      "description": "The MetaTrader account number."
    },
    "credential_kind": {
      "type": "string",
      "enum": [
        "investor",
        "master"
      ],
      "description": "Which password it was connected with: `master` can trade, `investor` only reads."
    },
    "can_trade": {
      "type": "boolean",
      "description": "Whether it can place trades, so it can be a follower. Any account can be a master."
    },
    "status": {
      "type": "string",
      "enum": [
        "connecting",
        "connected",
        "error",
        "disconnected"
      ],
      "description": "`connecting` while its terminal starts and logs in (two to three minutes), `connected` once it's ready, `error` when the login failed (see `error`), `disconnected` when its terminal lost the broker or was released."
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why it's in `error` or `disconnected`, if known."
    },
    "released": {
      "type": "boolean",
      "description": "Its terminal was released after the subscription lapsed. The account and its history are kept: reconnect it to resume."
    },
    "proxy_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "socks5",
        "socks4",
        "http",
        null
      ],
      "description": "The proxy's protocol; null without one."
    },
    "proxy_address": {
      "type": [
        "string",
        "null"
      ],
      "description": "The proxy its terminal reaches the broker through, as `host:port`; null for a direct connection."
    },
    "role": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "master",
        "follower",
        null
      ],
      "description": "Whether a copier uses it, and how. An account is never both."
    },
    "figures": {
      "anyOf": [
        {
          "$ref": "#/$defs/AccountFigures"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "object",
    "name",
    "nickname",
    "platform",
    "server",
    "login",
    "credential_kind",
    "can_trade",
    "status",
    "error",
    "released",
    "proxy_type",
    "proxy_address",
    "role",
    "figures",
    "created_at"
  ],
  "$defs": {
    "AccountFigures": {
      "type": "object",
      "properties": {
        "balance": {
          "type": "number"
        },
        "equity": {
          "type": "number"
        },
        "profit": {
          "type": "number",
          "description": "Floating profit or loss of the open positions."
        },
        "margin": {
          "type": "number"
        },
        "free_margin": {
          "type": "number"
        },
        "margin_level": {
          "type": [
            "number",
            "null"
          ],
          "description": "In percent; null while no margin is used."
        },
        "currency": {
          "type": "string",
          "description": "As the broker reports it: usually ISO 4217, but also codes such as `USC` (US cents) or `USDT`."
        },
        "open_positions": {
          "type": "integer"
        },
        "as_of": {
          "type": "string",
          "description": "When the terminal reported these figures.",
          "format": "date-time"
        },
        "source": {
          "type": "string",
          "enum": [
            "live",
            "snapshot"
          ],
          "description": "`live`: streamed by the copier engine, at most 30 seconds old. `snapshot`: the last stored snapshot, taken every few minutes."
        }
      },
      "description": "The account's freshest figures.",
      "required": [
        "balance",
        "equity",
        "profit",
        "margin",
        "free_margin",
        "margin_level",
        "currency",
        "open_positions",
        "as_of",
        "source"
      ]
    }
  }
}