tickerall-com Accounts API

openapi: 3.2.0
info:
  title: TickerAll Accounts API
  version: 1.0.0
  description: 'Hosted MetaTrader 5 & MT4 broker API. Connect a broker account, then place trades, pull historical candles, read positions and closed-trade history, and manage your accounts — from your own code, with no local MetaTrader terminal (runs on Linux, macOS, containers, anywhere).


    Live market data streams over a WebSocket at `wss://api.tickerall.com/v1/stream`, authenticated with the same bearer token (an `Authorization: Bearer ` header on the upgrade, or `?token=` for browser clients).


    **Authentication:** every endpoint except the public demo feed takes an `Authorization: Bearer ` header. Get an API key at https://tickerall.com.


    **Error codes:**

    - `UNAUTHORIZED` (401): Missing, malformed, or invalid Authorization header / API key.

    - `VALIDATION_ERROR` (400): The request body or params failed validation. A details array lists the offending fields.

    - `BROKER_AUTH_FAILED` (401): The broker rejected the login — wrong account number, password, or server. Returned by POST /v1/sessions and POST /v1/accounts/:id/reconnect. Fix the detail and retry.

    - `BROKER_UNREACHABLE` (503): Could not reach the broker (network/endpoint down). Retry shortly. (A wrong password no longer maps here — see BROKER_AUTH_FAILED.)

    - `BROKER_ACCOUNT_NOT_HOT` (409): The connection cooled. Call POST /v1/sessions with credentials to reconnect.

    - `BROKER_REJECTED` (422): The broker refused the order/close/modify. The reason is in message (e.g. bad volume, market closed, stop level).

    - `TICKET_NOT_FOUND` (404): The position ticket is not open on this account.

    - `BROKER_ACCOUNT_NOT_FOUND` (404): No broker account with that id belongs to your key.

    - `BROKER_ACCOUNT_ALREADY_LINKED` (409): That broker account is already linked to another TickerAll customer.

    - `FREE_TIER_LIVE_REJECTED` (403): Live account on Free outside the Terminal, or a second one at once. API live starts at Trader.

    - `DEMO_ACCOUNT_RESERVED` (403): That broker account is reserved by TickerAll for the public demo and cannot be attached.

    - `TIER_ACCOUNT_CAP_REACHED` (403): You hit your plan’s broker-account cap. Upgrade, or contact us for Enterprise.

    - `BROKER_NOT_FOUND` (422): The server name could not be resolved — it is not a known MT4/MT5 server. Use the exact name your terminal shows (MT5 servers are usually "Broker-MT5…"). No account row is left behind by a failed attempt.

    - `BROKER_ACCOUNT_INVALID` (422): The broker refused the account itself (disabled, archived, expired). Fix it in your broker portal; retrying will not help.

    - `DISCOVERY_UNAVAILABLE` (503): Broker lookup is temporarily paused after upstream errors. Your server name was NOT rejected — retry in a few minutes. Never a verdict on the name.

    - `SYMBOL_CATALOG_UNAVAILABLE` (503): The account is connected but its instrument list could not be read (a TickerAll-side gap, not an empty account). GET /symbols and /symbol-specs return this instead of an empty list, so an empty array never masquerades as "no symbols". Retry; if it persists, contact support with the broker and account type.

    - `ALWAYS_HOT_TIER_REQUIRED` (403): Always-hot needs a paid plan: Trader ($0.99/mo per connection) or Pro / Enterprise (included).

    - `VAULT_PURGE_PENDING` (503): DELETE /v1/accounts/:id could not yet destroy the account’s remembered password, so the account was not removed. Retry shortly.

    - `REMEMBER_PRO_REQUIRED` (403): Remembered credentials (server-side password storage, opt-in) are available on the Pro and Enterprise plans.

    - `rate_limited` (429): Too many requests for this API key this minute. Budgets per key: 300/min order writes (a bulk call counts once), 600/min candles and history, 120/min POST /v1/sessions, 2000/min everything else. Wait Retry-After seconds; every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for its budget.

    - `INTERNAL_ERROR` (500): Unexpected server error. Safe to retry idempotent calls.'
  contact:
    name: TickerAll
    url: https://tickerall.com
    email: hello@tickerall.com
  x-providerName: tickerall.com
  x-origin:
  - format: openapi
    version: '3.0'
    url: https://tickerall.com/openapi.json
  x-logo:
    url: https://tickerall.com/tickerall-social-logo-v4.png
servers:
- url: https://api.tickerall.com
  description: TickerAll production API
security:
- bearerAuth: []
tags:
- name: Accounts
paths:
  /v1/accounts:
    get:
      tags:
      - Accounts
      summary: List every broker account attached to your API key, with connection state
      description: 'List every broker account attached to your API key, with connection state.


        - accountNumber is masked to the last 4 digits. hot=false means the connection cooled — POST /v1/sessions to re-warm it.

        - group is the broker’s own account group (e.g. demo\Standard, real\Raw-USD), the best account-type signal available. It is cached per account from the first connection or trade the broker reports it on; null only for an account that has never once been connected.

        - Each row carries group and serverTimeOffsetSeconds as last measured on the account (cached across sessions and restarts); null means never seen yet.

        - Only accounts that connected at least once are listed: a failed connection attempt (unknown server, wrong password, unreachable broker) leaves no entry and does not count toward your plan’s cap.'
      operationId: getV1Accounts
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
              - id: acc_8Kd3...
                broker: mt5
                server: Exness-MT5Trial14
                accountNumber: '****5678'
                isDemo: true
                group: demo\Standard
                status: CONNECTED
                hot: true
                alwaysHot: false
                lastHotAt: '2026-05-22T18:30:01.000Z'
                createdAt: '2026-05-20T09:11:55.000Z'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}:
    get:
      tags:
      - Accounts
      summary: Live account info — balance, equity, margin, leverage — plus the current open…
      description: 'Live account info — balance, equity, margin, leverage — plus the current open positions.


        - If the connection has cooled, you get status:"offline" with a hint instead of live data — POST /v1/sessions to reconnect.

        - Money fields (equity, margin, freeMargin, marginLevel) may be null on an MT4 account that has not yet pushed a balance frame — null is honest "not available yet", never a misleading 0.

        - credit: broker credit / deposit bonus in the account currency; null when not reported (not yet reported by any broker).

        - isCent / cent: whether the account is denominated in a cent unit. The broker reports a cent account’s deposit currency as a cent code — currency "USC" means US cents — and every money field (balance, equity, margin, profit, deal P/L) is in that unit. isCent true comes with cent: { baseCurrency: "USD", unitsPerBase: 100 } (divide by unitsPerBase for dollars); a whole-currency account reads isCent false, cent null; isCent null means the deposit currency is not known yet (no snapshot).

        - Each open position carries brokerOpenTime — the same instant as openTime in the broker’s server-local time (RFC 3339 with offset) — on this object and on GET /v1/accounts/:id/positions, whose envelope also carries serverTimeOffsetSeconds. The offset is derived from the account’s open positions as well as its closed deals, so it is known from the first session on any account holding a position.

        - serverTimeOffsetSeconds is the broker’s server-local offset from UTC (e.g. 10800 for GMT+3), measured from the broker’s own records. null means it could not be derived yet (no deal or open position on the account, or MT4); 0 means a UTC server.

        - group is the broker’s own account group (e.g. demo\Raw-USD, real\Standard) — the best account-type signal the broker exposes. The broker sends it on an account’s first connection and on trade events; TickerAll caches it per account from that point, so it is present on the account object and the WebSocket snapshot on every later session and survives reconnects and maintenance. The only time it is null is an account that has never once been connected — never a made-up value.'
      operationId: getV1AccountsId
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      responses:
        '200':
          description: '200 OK (status: "online")'
          content:
            application/json:
              schema:
                type: object
              example:
                id: acc_8Kd3...
                broker: mt5
                server: Exness-MT5Trial14
                accountNumber: '****5678'
                isDemo: true
                status: online
                account:
                  name: Demo Account 12345678
                  accountType: demo
                  group: demo\Standard
                  leverage: 500
                  balance: 9871.42
                  currency: USD
                  equity: 9863.1
                  margin: 142.5
                  freeMargin: 9720.6
                  marginLevel: 6921.5
                  credit: null
                  isCent: false
                  cent: null
                  serverTimeOffsetSeconds: 0
                positions:
                - ticket: 4072808150
                  symbol: BTCUSD
                  side: BUY
                  volume: 0.1
                  entryPrice: 77512.73
                  stopLoss: 71000
                  takeProfit: 84000
                  currentPrice: 77640.1
                  profit: 12.74
                  swap: 0
                  commission: 0
                  comment: my-strategy
                  magic: 0
                  openTime: '2026-05-22T17:55:03.000Z'
                  brokerOpenTime: '2026-05-22T17:55:03+00:00'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
      - Accounts
      summary: Remove a broker account from your roster
      description: 'Remove a broker account from your roster. We disconnect its live connection and drop it from your account list and from billing — this does NOT touch the broker account itself or any open positions. Reversible: reconnect the same login with POST /v1/sessions to re-add it.


        - Idempotent — removing an already-removed or unknown id returns the same 200 shape (a retried cleanup never fails half-way). existed tells them apart: true when a linked account was actually removed by this call, false when nothing was linked under that id (a typo, or already gone). An id that belongs to another customer is a 404.

        - If the account had always-hot enabled, that per-connection charge stops immediately; billableCount is your remaining always-hot connection count.

        - If the account has a remembered password (see /v1/remember-password), it is destroyed before the account is removed. If our vault can’t confirm that yet, you get 503 VAULT_PURGE_PENDING and the account stays linked; retry the DELETE.'
      operationId: deleteV1AccountsId
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: acc_8Kd3...
                status: DISCONNECTED
                removed: true
                existed: true
                billableCount: 0
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}/positions:
    get:
      tags:
      - Accounts
      summary: The account’s current open positions — the dedicated positions feed
      description: 'The account’s current open positions — the dedicated positions feed. Each row carries entry price, volume, live P&L and SL/TP; it is the same array GET /v1/accounts/:id embeds, with a brokerOpenTime twin per row and serverTimeOffsetSeconds on the envelope.


        - An empty positions array is valid data — it means no open positions, never an error.

        - entryPrice is the position’s actual fill price; currentPrice and profit are live and move with the market. profit is in the account’s deposit currency.

        - openTime is UTC; brokerOpenTime is the same instant in the broker’s server-local time (RFC 3339 with offset). serverTimeOffsetSeconds on the envelope is the broker’s offset from UTC (e.g. 10800 for GMT+3); null means it could not be derived yet, 0 means a UTC server.

        - The same positions are also on GET /v1/accounts/:id alongside the money fields — use this lighter call when you only need positions, and subscribe to the positions WebSocket channel for live updates.'
      operationId: getV1AccountsIdPositions
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                accountId: acc_8Kd3...
                positions:
                - ticket: 4072808150
                  symbol: BTCUSD
                  side: BUY
                  volume: 0.1
                  entryPrice: 77512.73
                  stopLoss: 71000
                  takeProfit: 84000
                  currentPrice: 77640.1
                  profit: 12.74
                  swap: 0
                  commission: 0
                  comment: my-strategy
                  magic: 0
                  openTime: '2026-05-22T17:55:03.000Z'
                  brokerOpenTime: '2026-05-22T17:55:03+00:00'
                serverTimeOffsetSeconds: 0
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}/migrate:
    post:
      tags:
      - Accounts
      summary: Switch which terminal type the account presents AS ("MOBILE" or "WEB")
      description: 'Switch which terminal type the account presents AS ("MOBILE" or "WEB"). Your open positions, pending orders and balance live on the broker account, not the connection, so they are preserved across the switch.


        - status is "noop" when the account is already on the requested transport.

        - Switching runs only when the account is idle (no in-flight trade — otherwise 409).

        - Both terminal types expose the full surface (account, quotes, positions, history).

        - The switch is zero-gap — the new transport is warmed before the old session is dropped — so open positions, orders and balance carry over untouched.'
      operationId: postV1AccountsIdMigrate
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        description: A stable key so a retried request cannot execute twice. Re-sending the same key returns the original response.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: string
                  enum:
                  - MOBILE
                  - WEB
                  description: The transport to switch to.
              required:
              - to
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: acc_8Kd3...
                terminalType: MOBILE
                status: noop
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}/always-hot:
    patch:
      tags:
      - Accounts
      summary: 'Keep one account’s connection warm 24/7: skips the idle cool-down so the…'
      description: 'Keep one account’s connection warm 24/7: skips the idle cool-down so the session stays up between your calls. Broker-side drops reconnect automatically on every account regardless; always-hot only removes the idle timeout. Off by default. Trader ($0.99/mo per connection) or Pro / Enterprise (included).


        - effective is the resolved state (this flag OR the account-wide switch, on an eligible plan). appliedLive is true when the account was warm and the change took effect on the live session immediately; a cold account applies it on its next connect.

        - What always-hot does NOT do: it does not store your password. If TickerAll itself restarts, the account returns as needs-rearm (see GET /v1/always-hot/pending) until you POST /v1/sessions again — unless you opt in to remembered credentials.

        - 403 ALWAYS_HOT_TIER_REQUIRED on the Free plan.'
      operationId: patchV1AccountsIdAlwayshot
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        description: A stable key so a retried request cannot execute twice. Re-sending the same key returns the original response.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: true to pin the connection warm, false to let it cool after the idle timeout.
              required:
              - enabled
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: acc_8Kd3...
                alwaysHot: true
                effective: true
                appliedLive: true
                billableCount: 1
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/always-hot:
    patch:
      tags:
      - Accounts
      summary: 'Account-wide always-hot: every eligible connection defaults to warm'
      description: 'Account-wide always-hot: every eligible connection defaults to warm. Same semantics as the per-account toggle, applied live to all held sessions.


        - 403 ALWAYS_HOT_TIER_REQUIRED on the Free plan.'
      operationId: patchV1Alwayshot
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: A stable key so a retried request cannot execute twice. Re-sending the same key returns the original response.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: true to keep every connection warm, false to return to per-account flags.
              required:
              - enabled
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                accountWide: true
                billableCount: 3
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/always-hot/pending:
    get:
      tags:
      - Accounts
      summary: Always-hot accounts that currently have no live connection and need a…
      description: 'Always-hot accounts that currently have no live connection and need a credentials refresh — typically after a TickerAll maintenance restart dropped the in-memory password. Empty means nothing needs attention.


        - Re-arm an account by calling POST /v1/sessions with its credentials again. The TypeScript and Python SDKs do this for you: sessions.keepAlive() / keep_alive() caches the credentials in your process and re-arms a cold account on its next call.

        - If you cannot keep credentials on your side at all, see PATCH /v1/remember-password — with it on, accounts that are always-hot re-arm themselves server-side and never appear here.'
      operationId: getV1AlwayshotPending
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                pending:
                - id: acc_8Kd3...
                  broker: mt5
                  server: Exness-MT5Trial14
                  accountNumber: '****5678'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/remember-password:
    get:
      tags:
      - Accounts
      summary: Status of remembered credentials — the one opt-in exception to TickerAll’s rule…
      description: 'Status of remembered credentials — the one opt-in exception to TickerAll’s rule of never storing broker passwords. Available on Pro and Enterprise, for customers who cannot keep credentials on their own side.


        - remembered = accounts whose password is sealed in the vault; armed = opted in but not yet captured (the password is captured on each account’s next connect, never through this endpoint).

        - eligible is false on the Free and Trader plans.'
      operationId: getV1Rememberpassword
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                accountWide: false
                eligible: true
                tier: PRO
                remembered: 0
                armed: 0
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      tags:
      - Accounts
      summary: Turn remembered credentials on or off for ALL your accounts
      description: 'Turn remembered credentials on or off for ALL your accounts. On: each account’s password is sealed in an encrypted vault (AES-256-GCM) on its next connect and used solely to restore the connection after a TickerAll restart; your consent text is recorded. Off: every stored password is purged immediately.


        - Off by default on every plan; nothing is stored until you switch it on. Turning it off returns { "accountWide": false, "forgotten": } after rotating every sealed secret to an unreadable value and clearing the flags.

        - Once on, an account that is also always-hot re-arms itself server-side after a maintenance restart — no POST /v1/sessions needed. If you can supply the password yourself on reconnect, leave it off.

        - A password you pass to POST /v1/sessions on a remembered account updates the stored one; on a remembered account you may also omit password to reconnect.

        - 403 REMEMBER_PRO_REQUIRED below Pro.'
      operationId: patchV1Rememberpassword
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: A stable key so a retried request cannot execute twice. Re-sending the same key returns the original response.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: true to opt in (account-wide), false to opt out and purge.
                consentText:
                  type: string
                  description: 'Required when enabling: the consent wording you are agreeing to (recorded for audit).'
              required:
              - enabled
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                accountWide: true
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (see the description).
            message:
              type: string
              description: Human-readable explanation.
            details:
              type: array
              items:
                type: object
              description: Optional per-field validation details.
          required:
          - code
          - message
  responses:
    Error:
      description: Error — see the `code` field and the error-code list in the API description.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your TickerAll API key, sent as `Authorization: Bearer <API_KEY>`.'