openapi: 3.0.1
info:
  title: B2Trader OHLC data API
  description: |
    OpenAPI specification for B2Trader API endpoints used in the GetHistory method.
    This includes endpoints for fetching candlestick data (KLines), open interest history,
    and historical tick data from the public data archive.
  version: v4
servers:
  - url: '[md-host]'
paths:
  /marketdata/api/v4/kline:
    get:
      operationId: getKlines
      summary: Get Kline (Candlestick) Data
      description: |
        Query for historical klines (also known as candles/candlesticks).
        Charts are returned in groups based on the requested interval.
        Used for fetching bar/candle history data with resolutions from 1 minute to daily.
      tags:
        - Market
      parameters:
        - name: symbol
          in: query
          required: true
          description: Symbol name
          schema:
            type: string
          example: cfd.btc_usdt
        - name: interval
          in: query
          required: true
          description: |
            Kline interval.
            Currently only `1m` is supported. This may be expanded in the future.
          schema:
            type: string
            enum:
              - 1m
          example: 1m
        - name: start
          in: query
          required: false
          description: Start timestamp in milliseconds
          schema:
            type: integer
            format: int64
          example: 1672502400000
        - name: end
          in: query
          required: false
          description: End timestamp in milliseconds
          schema:
            type: integer
            format: int64
          example: 1672588800000
        - name: limit
          in: query
          required: false
          description: |
            Limit for data size per page. Default is 1000, maximum is 10000.
            If the provided limit exceeds 10000, the API returns only 10000 records.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          example: 1000
      responses:
        '200':
          description: Successful response with kline data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlineResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.Platform.Http.ErrorData.ErrorDetails'
              examples:
                Example 1:
                  value:
                    source: string
                    message: string
                    stackTrace: string
components:
  schemas:
    KlineResponse:
      type: object
      description: Response containing array of kline data objects.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Kline'
      example:
        items:
          - startTime: 1499040000000
            open: '0.01634000'
            high: '0.80000000'
            low: '0.01575800'
            close: '0.01577100'
    Kline:
      type: object
      description: Kline (candlestick) data object.
      properties:
        startTime:
          type: integer
          format: int64
          description: Start time of the candle (ms)
          example: 1499040000000
        open:
          type: string
          description: Open price
          example: '0.01634000'
        high:
          type: string
          description: Highest price
          example: '0.80000000'
        low:
          type: string
          description: Lowest price
          example: '0.01575800'
        close:
          type: string
          description: Close price
          example: '0.01577100'
      required:
        - startTime
        - open
        - high
        - low
        - close
    BBP.Platform.Http.ErrorData:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          $ref: '#/components/schemas/BBP.Platform.Http.ErrorData.ErrorDetails'
      additionalProperties: false
    BBP.Platform.Http.ErrorData.ErrorDetails:
      type: object
      properties:
        source:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        stackTrace:
          type: string
          nullable: true
      additionalProperties: false
tags:
  - name: Market
    description: 'Market data endpoints (KLines, Open Interest)'
  - name: Historical Data
    description: Historical tick data download from public archive
