openapi: 3.1.0
info:
  title: Capital.com REST API
  description: >-
    The Capital.com REST API provides programmatic access to the Capital.com
    trading engine, including positions, working orders, deal confirmations,
    account information, account switching, transaction history, account
    preferences (leverage, hedging mode), market navigation, instruments,
    and historical price data. Authentication uses an API key plus login
    credentials to create a session that returns CST and X-SECURITY-TOKEN
    headers, which expire after ten minutes of inactivity.
  version: 'v1'
  contact:
    name: Capital.com API Support
    url: https://open-api.capital.com
externalDocs:
  description: Capital.com Public API Documentation
  url: https://open-api.capital.com
servers:
- url: https://api-capital.backend-capital.com
  description: Capital.com production REST API server
- url: https://demo-api-capital.backend-capital.com
  description: Capital.com demo (sandbox) REST API server
tags:
- name: General
  description: Server time, ping, and encryption-key utility endpoints.
- name: Session
  description: Operations for creating, switching, and ending API sessions.
- name: Accounts
  description: Account information, preferences, and demo top-up.
- name: History
  description: Account activity and transaction history.
- name: Positions
  description: Operations for opening, updating, and closing trading positions.
- name: Working Orders
  description: Operations for managing limit and stop working orders.
- name: Markets
  description: Market navigation and instrument lookup.
security:
- apiKey: []
  sessionToken: []
  securityToken: []
paths:
  /api/v1/time:
    get:
      operationId: getServerTime
      summary: Get Server Time
      description: Returns the current Capital.com server time.
      tags:
      - General
      responses:
        '200':
          description: Server time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/ping:
    get:
      operationId: ping
      summary: Ping the Service
      description: Returns a simple OK response to verify connectivity.
      tags:
      - General
      responses:
        '200':
          description: Service is reachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/session/encryptionKey:
    get:
      operationId: getEncryptionKey
      summary: Get Encryption Key
      description: Returns the public encryption key used to encrypt the session password.
      tags:
      - Session
      responses:
        '200':
          description: Encryption key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/session:
    get:
      operationId: getSession
      summary: Get Session Details
      description: Returns details of the currently active API session.
      tags:
      - Session
      responses:
        '200':
          description: Session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSession
      summary: Create New Session
      description: Authenticates with API key and login credentials to create a new session.
      tags:
      - Session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: switchAccount
      summary: Switch Active Account
      description: Switches the active account associated with the current session.
      tags:
      - Session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Account switched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    delete:
      operationId: logOutSession
      summary: Log Out Session
      description: Terminates the current API session.
      tags:
      - Session
      responses:
        '200':
          description: Session terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/accounts:
    get:
      operationId: listAccounts
      summary: List Accounts
      description: Returns all accounts available to the authenticated client.
      tags:
      - Accounts
      responses:
        '200':
          description: A list of accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/accounts/preferences:
    get:
      operationId: getAccountPreferences
      summary: Get Account Preferences
      description: Returns account preferences, including leverage and hedging mode.
      tags:
      - Accounts
      responses:
        '200':
          description: Account preferences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    put:
      operationId: updateAccountPreferences
      summary: Update Account Preferences
      description: Updates account preferences such as leverage or hedging mode.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Preferences updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/accounts/topUp:
    post:
      operationId: topUpDemoAccount
      summary: Adjust Demo Account Balance
      description: Adjusts the balance of a demo account for testing.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Demo balance adjusted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/history/activity:
    get:
      operationId: getActivityHistory
      summary: Get Activity History
      description: Returns the account activity history.
      tags:
      - History
      responses:
        '200':
          description: Activity history records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/history/transactions:
    get:
      operationId: getTransactionsHistory
      summary: Get Transactions History
      description: Returns the account transactions history.
      tags:
      - History
      responses:
        '200':
          description: Transactions history records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/confirms/{dealReference}:
    get:
      operationId: getDealConfirmation
      summary: Get Deal Confirmation
      description: Returns the position or order confirmation for a given deal reference.
      tags:
      - Positions
      parameters:
      - name: dealReference
        in: path
        required: true
        description: The deal reference identifier.
        schema:
          type: string
      responses:
        '200':
          description: Deal confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/positions:
    get:
      operationId: listPositions
      summary: List All Positions
      description: Returns all open positions for the active account.
      tags:
      - Positions
      responses:
        '200':
          description: A list of positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    post:
      operationId: createPosition
      summary: Create Position
      description: Opens a new trading position.
      tags:
      - Positions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Position created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/positions/{dealId}:
    get:
      operationId: getPosition
      summary: Get Position
      description: Returns details for a single open position.
      tags:
      - Positions
      parameters:
      - name: dealId
        in: path
        required: true
        description: The deal ID for the position.
        schema:
          type: string
      responses:
        '200':
          description: Position details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updatePosition
      summary: Update Position
      description: Updates an existing position (e.g., stops, limits).
      tags:
      - Positions
      parameters:
      - name: dealId
        in: path
        required: true
        description: The deal ID for the position.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Position updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    delete:
      operationId: closePosition
      summary: Close Position
      description: Closes the specified open position.
      tags:
      - Positions
      parameters:
      - name: dealId
        in: path
        required: true
        description: The deal ID for the position to close.
        schema:
          type: string
      responses:
        '200':
          description: Position closed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/workingorders:
    get:
      operationId: listWorkingOrders
      summary: List Working Orders
      description: Returns all working (limit/stop) orders for the active account.
      tags:
      - Working Orders
      responses:
        '200':
          description: A list of working orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    post:
      operationId: createWorkingOrder
      summary: Create Working Order
      description: Creates a new working order (limit or stop).
      tags:
      - Working Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Working order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/workingorders/{dealId}:
    put:
      operationId: updateWorkingOrder
      summary: Update Working Order
      description: Updates an existing working order.
      tags:
      - Working Orders
      parameters:
      - name: dealId
        in: path
        required: true
        description: The deal ID for the working order.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericObject'
      responses:
        '200':
          description: Working order updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    delete:
      operationId: deleteWorkingOrder
      summary: Delete Working Order
      description: Cancels and deletes the specified working order.
      tags:
      - Working Orders
      parameters:
      - name: dealId
        in: path
        required: true
        description: The deal ID for the working order.
        schema:
          type: string
      responses:
        '200':
          description: Working order deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/marketnavigation:
    get:
      operationId: listMarketNavigation
      summary: List Top-Level Market Categories
      description: Returns the top-level market navigation categories.
      tags:
      - Markets
      responses:
        '200':
          description: A list of top-level market categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/marketnavigation/{nodeId}:
    get:
      operationId: listMarketNavigationByNode
      summary: List Sub-Nodes for Category
      description: Returns the sub-nodes (markets and child categories) under a given navigation node.
      tags:
      - Markets
      parameters:
      - name: nodeId
        in: path
        required: true
        description: The navigation node identifier.
        schema:
          type: string
      responses:
        '200':
          description: A list of sub-nodes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/markets:
    get:
      operationId: listMarkets
      summary: List Markets
      description: Returns details for a set of markets, filtered by query parameters.
      tags:
      - Markets
      responses:
        '200':
          description: A list of market details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /api/v1/markets/{epic}:
    get:
      operationId: getMarket
      summary: Get Single Market
      description: Returns details for a single market, identified by its epic.
      tags:
      - Markets
      parameters:
      - name: epic
        in: path
        required: true
        description: Market epic (instrument identifier).
        schema:
          type: string
      responses:
        '200':
          description: Market details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-CAP-API-KEY
      description: Capital.com API key required for all calls.
    sessionToken:
      type: apiKey
      in: header
      name: CST
      description: Client session token returned after creating a session.
    securityToken:
      type: apiKey
      in: header
      name: X-SECURITY-TOKEN
      description: Security token returned after creating a session.
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    GenericObject:
      type: object
      description: Generic JSON object response.
      additionalProperties: true
    Error:
      type: object
      description: Generic error response.
      properties:
        errorCode:
          type: string
        message:
          type: string
      additionalProperties: true
x-generated-from: https://open-api.capital.com
x-generated-by: claude-crawl-2026-05-08