tickerall-com Orders API

openapi: 3.2.0
info:
  title: TickerAll Orders 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: Orders
paths:
  /v1/accounts/{id}/orders:
    post:
      tags:
      - Orders
      summary: Place a market order (fills immediately) or a pending limit/stop order (rests…
      description: 'Place a market order (fills immediately) or a pending limit/stop order (rests until price is hit).


        - Requires an Idempotency-Key header (see Conventions). Re-sending the same key returns the original response without placing a second order.

        - Pending orders are expressed as two separate fields, not one combined name: a buy-stop is type:"stop" + side:"BUY"; a sell-limit is type:"limit" + side:"SELL". The write API does NOT accept MetaTrader-style combined names (BUY_STOP, SELL_LIMIT, …) — passing type:"BUY_STOP" is a 400 VALIDATION_ERROR. GET /v1/accounts/:id/orders reports that combined name in its own type field for readability, but that is a read-only convenience: do not echo it back here — use its orderType (LIMIT/STOP) lowercased as type, plus side.

        - status is "open" for market orders and "pending" for limit/stop orders.

        - A broker rejection (bad volume, market closed, stop-level too tight, insufficient margin) comes back as 422 BROKER_REJECTED with the broker’s reason in message.'
      operationId: postV1AccountsIdOrders
      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:
                type:
                  type: string
                  enum:
                  - market
                  - limit
                  - stop
                  description: 'The base order type — market (fills now) or limit / stop (rests until price is hit). Do NOT pass MetaTrader-style combined names like "BUY_STOP" here: those are only ever returned by GET /orders. On input, split the intent into type + side — e.g. a buy-stop is type:"stop" + side:"BUY".'
                symbol:
                  type: string
                  description: Broker-native symbol, e.g. "BTCUSD".
                side:
                  type: string
                  enum:
                  - BUY
                  - SELL
                  description: Trade direction — uppercase BUY or SELL. Combined with type it expresses the order, e.g. type:"limit" + side:"SELL" is a sell-limit.
                volume:
                  type: number
                  description: Lots, e.g. 0.10. Must be positive.
                price:
                  type: number
                  description: Trigger price. Required for limit and stop; ignored for market.
                stopLoss:
                  type: number
                  description: Stop-loss price. Omit for none.
                takeProfit:
                  type: number
                  description: Take-profit price. Omit for none.
                comment:
                  type: string
                  description: Optional strategy tag stored on the order.
              required:
              - type
              - symbol
              - side
              - volume
      responses:
        '201':
          description: 201 Created
          content:
            application/json:
              schema:
                type: object
              example:
                ticket: 4072808150
                symbol: BTCUSD
                side: BUY
                type: market
                volume: 0.1
                price: null
                stopLoss: 71000
                takeProfit: 84000
                comment: my-strategy
                status: open
                timestamp: '2026-05-22T17:55:03.000Z'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    get:
      tags:
      - Orders
      summary: List the account’s working pending orders — LIMIT and STOP orders resting until…
      description: 'List the account’s working pending orders — LIMIT and STOP orders resting until their trigger price is hit. A market order is never pending: it becomes an open position immediately (see GET /v1/accounts/:id/positions). Returns an empty list when nothing is resting.


        - Working (pending) orders only. When a pending order triggers it leaves this list and becomes an open position — find it under GET /v1/accounts/:id/positions.

        - type is one of BUY_LIMIT, SELL_LIMIT, BUY_STOP, SELL_STOP, BUY_STOP_LIMIT, SELL_STOP_LIMIT; orderType collapses that to LIMIT / STOP / STOP_LIMIT and side to BUY / SELL. ticket is a string; price is the trigger (activation) level; limitPrice is set only on STOP_LIMIT variants; expirationTime is null for good-till-cancelled.

        - This combined type (e.g. BUY_STOP) is READ-ONLY. To place or modify an order, use the split form — type (market/limit/stop) + side (BUY/SELL) — from POST /v1/accounts/:id/orders; the write API does not accept BUY_STOP-style names.

        - For live updates instead of polling, subscribe to the orders channel over the WebSocket (see the WebSocket section) — it pushes the full pending-order list on subscribe and on every change.

        - Optional ?waitMs= adds a settle window for a just-warmed connection’s first pending snapshot; omit for an immediate read.

        - Also reachable at the alias GET /v1/accounts/:id/orders/pending.'
      operationId: getV1AccountsIdOrders
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                orders:
                - ticket: '4072809988'
                  symbol: BTCUSD
                  type: BUY_LIMIT
                  side: BUY
                  orderType: LIMIT
                  volume: 0.1
                  price: 68000
                  limitPrice: null
                  stopLoss: 66000
                  takeProfit: 72000
                  setTime: '2026-08-14T09:12:44.000Z'
                  expirationTime: null
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}/orders/{ticket}:
    delete:
      tags:
      - Orders
      summary: Cancel a resting pending order (LIMIT or STOP) by its ticket
      description: 'Cancel a resting pending order (LIMIT or STOP) by its ticket.


        - Requires an Idempotency-Key header.

        - ticket is the pending order’s ticket from GET /v1/accounts/:id/orders — not a position. If the order has already triggered it is now an open position; close it with DELETE /v1/accounts/:id/positions/:ticket instead.

        - If the ticket is not a resting pending order on this account you get 404 TICKET_NOT_FOUND.

        - Pending-order management is an MT5 feature; on an account that does not support it the call returns 400.'
      operationId: deleteV1AccountsIdOrdersTicket
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      - name: ticket
        in: path
        required: true
        description: Ticket of the pending order to cancel (from GET /v1/accounts/:id/orders).
        schema:
          type: number
      - 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
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                ticket: 4072809988
                symbol: BTCUSD
                side: BUY
                cancelled: true
                timestamp: '2026-08-14T09:12:44.000Z'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      tags:
      - Orders
      summary: Modify a resting pending order’s trigger price, stop-loss or take-profit
      description: 'Modify a resting pending order’s trigger price, stop-loss or take-profit. Any field you omit is preserved at its current value.


        - Requires an Idempotency-Key header.

        - Provide at least one of price, stopLoss or takeProfit — an empty body is a 400. Omitted fields keep their current value.

        - If the ticket is not a resting pending order on this account you get 404 TICKET_NOT_FOUND.'
      operationId: patchV1AccountsIdOrdersTicket
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      - name: ticket
        in: path
        required: true
        description: Ticket of the pending order to modify (from GET /v1/accounts/:id/orders).
        schema:
          type: number
      - 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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                price:
                  type: number
                  description: New trigger (activation) price. Omit to keep the current trigger.
                stopLoss:
                  type: number
                  description: New stop-loss. Omit to keep the current SL.
                takeProfit:
                  type: number
                  description: New take-profit. Omit to keep the current TP.
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                ticket: 4072809988
                symbol: BTCUSD
                side: BUY
                price: 66000
                stopLoss: 64000
                takeProfit: 72000
                timestamp: '2026-08-14T09:12:44.000Z'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}/orders/cancel-all:
    post:
      tags:
      - Orders
      summary: Cancel every resting pending order on the account in one call, optionally…
      description: 'Cancel every resting pending order on the account in one call, optionally narrowed by symbol, side and/or type. The server lists the pending orders once and cancels the matches in parallel.


        - Requires an Idempotency-Key header.

        - Body (all fields optional): { "symbol": "EURUSD", "side": "BUY", "type": "limit" }. type is one of limit / stop / stopLimit; side is BUY / SELL.

        - Single-account cancel — for a ticket you already hold use DELETE /v1/accounts/:id/orders/:ticket; to cancel across many accounts at once use POST /v1/bulk/orders/cancel.

        - Always 200. No matching pending orders is an empty success — results: [] with summary { requested: 0, ok: 0, failed: 0 } — never a 404 or an error.

        - Partial success — each order’s outcome is in results: status "ok" (cancelled true) or "failed" (with a code and reason). summary tallies requested / ok / failed.

        - Pending-order management is an MT5 feature; on an account that does not support it the call returns 400.'
      operationId: postV1AccountsIdOrdersCancelall
      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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                symbol:
                  type: string
                  description: Only cancel pending orders on this broker-native symbol (e.g. BTCUSDm). Omit to cancel on every symbol. Case-insensitive.
                side:
                  type: string
                  description: Only cancel BUY or SELL pending orders. Omit for both sides.
                type:
                  type: string
                  description: Only cancel this order type — limit, stop or stopLimit. Omit for all types.
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                results:
                - ticket: 4072809988
                  symbol: BTCUSD
                  side: BUY
                  status: ok
                  cancelled: true
                - ticket: 4072809991
                  symbol: BTCUSD
                  side: SELL
                  status: failed
                  code: BROKER_REJECTED
                  reason: Broker rejected the cancel.
                summary:
                  requested: 2
                  ok: 1
                  failed: 1
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}/positions/{ticket}:
    delete:
      tags:
      - Orders
      summary: Close an open position
      description: 'Close an open position. Omit volume for a full close, or pass a smaller volume for a partial close.


        - Requires an Idempotency-Key header. Re-using a key with a different body or ticket is a 409 IDEMPOTENCY_KEY_REUSED — nothing is replayed or executed.

        - If the ticket is not an open position on this account you get 404 TICKET_NOT_FOUND.

        - closePrice, dealTicket, profit, swap and commission are the booked closing deal — the same values the OUT row in /deals-history carries (dealTicket is its ticket there; money in the account currency). They are null when the broker has not booked the deal by the time the response is sent (rare — read /deals-history then); 0 is a real 0. A partial close reports the deal for the closed part.

        - volume is what was actually closed. Asking for more than is open closes the whole position (the contract is unchanged) and the response then also carries requestedVolume, warningCode "VOLUME_CLAMPED" and a warning message; these three fields are absent otherwise.'
      operationId: deleteV1AccountsIdPositionsTicket
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      - name: ticket
        in: path
        required: true
        description: Ticket of the position to close (from the order response or GET /v1/accounts/:id).
        schema:
          type: number
      - 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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                volume:
                  type: number
                  description: Partial-close volume in lots. If omitted, the whole position is closed.
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                ticket: 4072808150
                symbol: BTCUSD
                side: BUY
                volume: 0.1
                closed: true
                timestamp: '2026-05-22T18:10:44.000Z'
                closePrice: 81320.15
                dealTicket: '1191098644'
                profit: -0.4
                swap: 0
                commission: 0
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      tags:
      - Orders
      summary: Modify the stop-loss and/or take-profit of an open position
      description: 'Modify the stop-loss and/or take-profit of an open position. Provide at least one of stopLoss / takeProfit.


        - Requires an Idempotency-Key header.

        - You must supply at least one of stopLoss or takeProfit; sending neither is a VALIDATION_ERROR.

        - Some brokers enforce a minimum stop distance (stop level). Too-tight values come back as 422 BROKER_REJECTED.'
      operationId: patchV1AccountsIdPositionsTicket
      parameters:
      - name: id
        in: path
        required: true
        description: accountId.
        schema:
          type: string
      - name: ticket
        in: path
        required: true
        description: Ticket of the position to modify.
        schema:
          type: number
      - 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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                stopLoss:
                  type: number
                  description: New stop-loss price. Omit to leave unchanged.
                takeProfit:
                  type: number
                  description: New take-profit price. Omit to leave unchanged.
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                ticket: 4072808150
                symbol: BTCUSD
                side: BUY
                volume: 0.1
                stopLoss: 72000
                takeProfit: 85000
                timestamp: '2026-05-22T18:12:09.000Z'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /v1/accounts/{id}/positions/close-all:
    post:
      tags:
      - Orders
      summary: Flatten the account — close every open position in one call, optionally…
      description: 'Flatten the account — close every open position in one call, optionally narrowed by symbol and/or side. The server reads the account’s open positions once and closes the matches in parallel.


        - Requires an Idempotency-Key header.

        - Body (all fields optional): { "symbol": "EURUSD", "side": "BUY" }. side is BUY / SELL.

        - Each "ok" result carries the booked closing deal (closePrice, dealTicket, profit, swap, commission), null when not yet booked — the same fields as a single DELETE.

        - Single-account flatten — for a ticket you already hold use DELETE /v1/accounts/:id/positions/:ticket; to flatten across many accounts at once use POST /v1/bulk/positions/close.

        - Always 200. No matching positions is an empty success — results: [] with summary { requested: 0, ok: 0, failed: 0 } — never a 404 or an error.

        - Partial success — each position’s outcome is in results: status "ok" (closed true) or "failed" (with a code and reason). summary tallies requested / ok / failed.

        - Each "ok" result carries the booked close deal (closePrice, dealTicket, profit, swap, commission), as on the single close; null until the broker books it.'
      operationId: postV1AccountsIdPositionsCloseall
      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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                symbol:
                  type: string
                  description: Only close positions on this broker-native symbol (e.g. BTCUSDm). Omit to close on every symbol. Case-insensitive.
                side:
                  type: string
                  description: Only close BUY or SELL positions. Omit to close both sides.
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                type: object
              example:
                results:
                - ticket: 4072808150
                  symbol: BTCUSD
                  side: BUY
                  status: ok
                  closed: true
                  closePrice: 81320.15
                  dealTicket: '1191098644'
                  profit: -0.4
                  swap: 0
                  commission: 0
                - ticket: 4072809002
                  symbol: BTCUSD
                  side: SELL
                  status: failed
                  code: BROKER_REJECTED
                  reason: Broker rejected the close.
                summary:
                  requested: 2
                  ok: 1
                  failed: 1
        '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>`.'