tickerall-com Candles & History API

openapi: 3.2.0
info:
  title: TickerAll Candles & History 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: Candles & History
paths:
  /v1/accounts/{id}/candles:
    get:
      tags:
      - Candles & History
      summary: Fetch historical OHLC bars from your connected broker, for any symbol the…
      description: 'Fetch historical OHLC bars from your connected broker, for any symbol the broker streams on this account. Two modes: a look-back window (hours) returns the most-recent N hours of bars, or a date range (from + to, ISO-8601) returns the exact [from, to] window. Coarser timeframes (H4, D1, W1, MN1) reach much further back — daily bars typically cover years of history. Every response reports how much of the requested window was actually served (coverage / truncated).


        - Authed — needs your API key (same as the rest of the customer API). Works for any symbol your broker exposes on the connected account.

        - Two modes: pass hours for a look-back window, OR pass both from and to (ISO-8601) for an exact date range. When from and to are present, hours is ignored, and the response echoes from/to (the requested window) at the top level instead of hours. Supplying only one of from/to, an unparseable date, or from ≥ to returns 400 invalid_range with a message.

        - Each candle is { timestamp, open, high, low, close, bid, tickVolume, spread }. timestamp is the bar OPEN time in Unix seconds (UTC); bid mirrors close. tickVolume (tick count) and spread (price units) are present on recent bars; deep-history bars are bid-only and may omit them (null/absent) — don’t rely on a guaranteed volume.

        - Every response also reports completeness: served ({ from, to } actually returned in ISO-8601, or null when empty), count (number of candles), coverage ("complete" when the whole window was served, otherwise "floor"/"partial"), truncated (boolean — true when the whole requested window was NOT served; the authoritative completeness signal), and stopReason (why the walk stopped, e.g. "floor" = no deeper data exists, "deadline" = worth retrying, "unsupported", "error"). A note field is added when stopReason is "unsupported".

        - A range larger than the per-request cap (~5 years, or ~100,000 bars at the chosen timeframe) is rejected with 400 range_too_large ({ maxBars, estimatedBars, maxWindowDays }) — narrow the range or coarsen the timeframe.

        - Timeframes: M1, M5, M15, M30, H1, H4, D1, W1, MN1. Daily and coarser reach back years; intraday (M1–H4) covers recent months. One request returns as much history as fits in a few seconds. Deep look-backs are isolated onto a dedicated history connection — a big walk never disturbs your live tick stream.

        - If the broker returns no decodable bars for the symbol/range (e.g. an illiquid pair), the response is a 200 with an empty candles array (served null, truncated true) — never a 500.'
      operationId: getV1AccountsIdCandles
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      - name: symbol
        in: query
        required: true
        description: Broker-native symbol name, e.g. "BTCUSD". Discover names via GET /v1/accounts/:id/symbols.
        schema:
          type: string
      - name: hours
        in: query
        required: false
        description: 'Look-back mode: how many hours of data to return, counted backwards from now. Defaults to 24, capped at ~5 years. Ignored when from and to are supplied.'
        schema:
          type: number
      - name: from
        in: query
        required: false
        description: 'Date-range mode: start of the window, e.g. "2026-01-01T00:00:00Z". Pass BOTH from and to (an alternative to hours) to fetch the exact [from, to] window. Supplying only one is a 400 invalid_range.'
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        description: 'Date-range mode: end of the window. Required with from and must be after it. When both are present, hours is ignored.'
        schema:
          type: string
          format: date-time
      - name: timeframe
        in: query
        required: false
        description: Bar interval. Defaults to "M5". Coarser timeframes go back further for the same window.
        schema:
          type: string
          enum:
          - M1
          - M5
          - M15
          - M30
          - H1
          - H4
          - D1
          - W1
          - MN1
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                symbol: BTCUSD
                hours: 17520
                timeframe: D1
                candles:
                - timestamp: 1747699200
                  open: 104200.1
                  high: 107840.55
                  low: 103520
                  close: 106910.73
                  bid: 106910.73
                - timestamp: 1747785600
                  open: 106910.73
                  high: 108100
                  low: 105480.2
                  close: 107512.4
                  bid: 107512.4
                served:
                  from: '2025-05-20T00:00:00.000Z'
                  to: '2025-05-21T00:00:00.000Z'
                count: 2
                coverage: complete
                truncated: false
                stopReason: floor
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/public/candles:
    get:
      tags:
      - Candles & History
      summary: Unauthenticated read of the always-on demo feed — powers the sparklines and…
      description: 'Unauthenticated read of the always-on demo feed — powers the sparklines and chart on tickerall.com. Limited to TickerAll’s demo symbol list and only callable from tickerall.com (origin-gated). For arbitrary broker symbols from your own code, use GET /v1/accounts/:id/candles above.


        - No API key needed, but origin-gated: this endpoint accepts requests from tickerall.com only and exists to drive the public demo widgets. For programmatic access from your own code use GET /v1/accounts/:id/candles instead — it works on any symbol your broker exposes.

        - Each candle is { timestamp, open, high, low, close, bid }. timestamp is the bar OPEN time in Unix seconds (UTC); bid mirrors close.

        - Only the demo feed’s symbol list is available here. For any other symbol, connect a broker account and call GET /v1/accounts/:id/candles instead.'
      operationId: getV1PublicCandles
      parameters:
      - name: symbol
        in: query
        required: true
        description: One of the demo feed’s symbols (e.g. BTCUSD, ETHUSD, EURUSD, GOLD).
        schema:
          type: string
      - name: hours
        in: query
        required: false
        description: How many hours of data to return. Defaults to 24, capped at ~5 years.
        schema:
          type: number
      - name: timeframe
        in: query
        required: false
        description: Bar interval. Defaults to "M5". Coarser timeframes go back further for the same hours value.
        schema:
          type: string
          enum:
          - M1
          - M5
          - M15
          - M30
          - H1
          - H4
          - D1
          - W1
          - MN1
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                symbol: BTCUSD
                hours: 17520
                timeframe: D1
                candles:
                - timestamp: 1747699200
                  open: 104200.1
                  high: 107840.55
                  low: 103520
                  close: 106910.73
                  bid: 106910.73
                - timestamp: 1747785600
                  open: 106910.73
                  high: 108100
                  low: 105480.2
                  close: 107512.4
                  bid: 107512.4
        '400':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
      security: []
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>`.'