openapi: 3.1.0
info:
  title: Capital.com REST Accounts Positions 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
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
security:
- apiKey: []
  sessionToken: []
  securityToken: []
tags:
- name: Positions
  description: Operations for opening, updating, and closing trading positions.
paths:
  /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'
components:
  responses:
    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
  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.
externalDocs:
  description: Capital.com Public API Documentation
  url: https://open-api.capital.com
x-generated-from: https://open-api.capital.com
x-generated-by: claude-crawl-2026-05-08