tickerall-com Sessions API

openapi: 3.2.0
info:
  title: TickerAll Sessions 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: Sessions
paths:
  /v1/sessions:
    post:
      tags:
      - Sessions
      summary: Connect a broker account
      description: 'Connect a broker account. We authenticate and warm a live connection, then hand back an accountId — the handle for THIS broker connection. One API key can hold several broker accounts, so the id lives in this response (and in GET /v1/accounts), NOT in the key. Use it in every later /v1/accounts/:id call. By default your password is held in memory only while the connection is live, never saved to disk; the one exception is the opt-in remembered-credentials setting (Pro and Enterprise, PATCH /v1/remember-password), which stores it encrypted solely to restore the connection after a restart.


        - On Free, demo accounts plus one live account in the Terminal; a live account via the API, SDKs or MCP returns FREE_TIER_LIVE_REJECTED.

        - The connection stays warm for a while (see expiresAt). If it cools, calls return BROKER_ACCOUNT_NOT_HOT — just POST /v1/sessions again to reconnect.'
      operationId: postV1Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                broker:
                  type: string
                  enum:
                  - mt4
                  - mt5
                  description: Which platform your broker server runs.
                server:
                  type: string
                  description: Broker server name, e.g. "Exness-MT5Trial14".
                account:
                  type: number
                  description: Your numeric broker login — the account number your broker assigns (e.g. 12345678). NOT your TickerAll email.
                password:
                  type: string
                  description: Broker (investor or master) password. Used once to authenticate; never persisted unless you have opted in to remembered credentials (Pro and Enterprise), in which case it may be omitted on reconnect.
                terminalType:
                  type: string
                  enum:
                  - MOBILE
                  - WEB
                  description: Which client the connection presents AS — MOBILE (default) or WEB. Both expose the full surface (account, quotes, positions, history). Omit for MOBILE. Choosing WEB (or CLIENT) requires a Pro or Enterprise plan.
                webTerminalUrl:
                  type: string
                  description: The broker’s web-terminal URL, e.g. https://mt5.yourbroker.com. REQUIRED when terminalType is "WEB" — web terminals are per-broker-domain, so the URL must be supplied. Ignored for MOBILE.
                webEndpoint:
                  type: string
                  description: 'Advanced, optional: an explicit WebSocket endpoint override (e.g. wss://host/path) for the rare broker whose WS host/path differs from the webTerminalUrl derivation. Ignored for MOBILE.'
              required:
              - broker
              - server
              - account
              - password
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                accountId: acc_8Kd3...
                isDemo: true
                status: connected
                expiresAt: '2026-05-22T18:42:10.000Z'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/sessions/{accountId}:
    delete:
      tags:
      - Sessions
      summary: Disconnect a broker account and release its connection
      description: Disconnect a broker account and release its connection. Returns no body.
      operationId: deleteV1SessionsAccountId
      parameters:
      - name: accountId
        in: path
        required: true
        description: The accountId returned by POST /v1/sessions.
        schema:
          type: string
      responses:
        '204':
          description: 204 No Content
        '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>`.'