HitBTC Candles API

openapi: 3.2.0
info:
  title: Hitbtc Candles API
  version: ''
  description: 'Operations tagged Candles across 4 of this provider''s published API definitions: hitbtc-api-v2-spec.yaml, hitbtc-api-v3-spec.yaml, hitbtc-openapi.yml, hitbtc-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/2
- url: /api/3
- url: https://api.hitbtc.com/api/3
  description: Production; the served spec declares the relative server /api/3 and the docs at api.hitbtc.com name this host
- url: https://api.demo.hitbtc.com/api/3
  description: Demo Environment (Sandbox), per api.hitbtc.com docs
- url: https://api.hitbtc.com/api/2
  description: Production; the served spec declares the relative server /api/2 and the docs at api.hitbtc.com name this host
tags:
- name: Candles
paths:
  /public/candles:
    get:
      tags:
      - Candles
      summary: Get candles
      description: Returns candles for all or multiple symbols.
      parameters:
      - $ref: '#/components/parameters/marketData_symbolsQuery'
      - $ref: '#/components/parameters/marketData_sortAsc'
      - $ref: '#/components/parameters/marketData_periodQuery'
      - $ref: '#/components/parameters/marketData_from'
      - $ref: '#/components/parameters/marketData_till'
      - $ref: '#/components/parameters/marketData_limit10'
      - $ref: '#/components/parameters/marketData_offset'
      - $ref: '#/components/parameters/marketData_pool'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/marketData_Candle'
                example:
                  BTCUSDT:
                  - timestamp: '2021-07-01T20:00:00.000Z'
                    open: '33079.93'
                    close: '33236.53'
                    min: '33079.93'
                    max: '33295.73'
                    volume: '146.86223'
                    volumeQuote: '4877838.3025063'
                  ETHBTC:
                  - timestamp: '2021-07-01T20:00:00.000Z'
                    open: '0.063420'
                    close: '0.063767'
                    min: '0.063403'
                    max: '0.063782'
                    volume: '866.6776'
                    volumeQuote: '55.2132903904'
        '400':
          $ref: '#/components/responses/marketData_BadRequestError'
      security: []
      operationId: getPublicCandles
      x-operation-id-source: derived
    servers:
    - url: /api/2
  /public/candles/{symbol}:
    get:
      tags:
      - Candles
      summary: Get candles for a specific symbol
      description: Returns candles for a specific symbol.
      parameters:
      - $ref: '#/components/parameters/marketData_symbolPath'
      - $ref: '#/components/parameters/marketData_sortAsc'
      - $ref: '#/components/parameters/marketData_periodQuery'
      - $ref: '#/components/parameters/marketData_from'
      - $ref: '#/components/parameters/marketData_till'
      - $ref: '#/components/parameters/marketData_limit100'
      - $ref: '#/components/parameters/marketData_offset'
      - $ref: '#/components/parameters/marketData_pool'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/marketData_Candle'
        '400':
          $ref: '#/components/responses/marketData_BadRequestError'
      security: []
      operationId: getPublicCandlesBySymbol
      x-operation-id-source: derived
    servers:
    - url: /api/2
  /public/converted/candles:
    get:
      tags:
      - Candles
      summary: Get a rate candle
      description: 'Returns OHLCV data regarding the last price converted to the target currency for all symbols.


        ⚠️ This call produces the same output as `GET /public/converted/candles` except all values in quote currency are converted to the target currency.


        ℹ️ Conversion from the symbol quote currency to the target currency is the mean of "best" bid price and "best" ask price in the order book. If there is no "best" bid of ask price, the last price is returned.


        **Permission**: None


        **IP limit**: 30/50'
      parameters:
      - $ref: '#/components/parameters/marketData_TargetCurrency'
      - $ref: '#/components/parameters/marketData_Symbols'
      - $ref: '#/components/parameters/marketData_SortDesc'
      - $ref: '#/components/parameters/marketData_Period'
      - $ref: '#/components/parameters/marketData_From'
      - $ref: '#/components/parameters/marketData_Till'
      - $ref: '#/components/parameters/marketData_Limit10'
      - $ref: '#/components/parameters/marketData_Pool'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/marketData_ConvertedCandles'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/marketData_InstrumentNotFound'
                - $ref: '#/components/schemas/marketData_Validation'
        '404':
          $ref: '#/components/responses/marketData_404'
      security: []
      operationId: getPublicConvertedCandles
      x-operation-id-source: derived
    servers:
    - url: /api/3
  /public/converted/candles/{symbol}:
    get:
      tags:
      - Candles
      summary: Get rate candles
      description: 'Returns OHLCV data regarding the last price converted to the target currency for a symbol.


        ⚠️ This call produces the same output as `GET /public/converted/candles` except all values in quote currency are converted to the target currency.


        ℹ️ Conversion from the symbol quote currency to the target currency is the mean of "best" bid price and "best" ask price in the order book. If there is no "best" bid of ask price, the last price is returned.


        **Permission**: None


        **IP limit**: 30/50'
      parameters:
      - $ref: '#/components/parameters/marketData_TargetCurrency'
      - $ref: '#/components/parameters/marketData_SymbolPath'
      - $ref: '#/components/parameters/marketData_SortDesc'
      - $ref: '#/components/parameters/marketData_Period'
      - $ref: '#/components/parameters/marketData_From'
      - $ref: '#/components/parameters/marketData_Till'
      - $ref: '#/components/parameters/marketData_Limit100'
      - $ref: '#/components/parameters/marketData_Offset'
      - $ref: '#/components/parameters/marketData_Pool'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/marketData_ConvertedCandle'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/marketData_InstrumentNotFound'
                - $ref: '#/components/schemas/marketData_Validation'
        '404':
          $ref: '#/components/responses/marketData_404'
      security: []
      operationId: getPublicConvertedCandlesBySymbol
      x-operation-id-source: derived
    servers:
    - url: /api/3
components:
  parameters:
    marketData_pool:
      name: exclude_pool
      in: query
      description: Flag indicating whether to return trades for a single broker.
      schema:
        type: boolean
    marketData_from:
      name: from
      in: query
      description: Interval initial value.
      schema:
        type: string
        format: date-time
    marketData_periodQuery:
      name: period
      in: query
      description: "History time period:\n  * *M\\** — minutes;\n  * *H\\** — hours;\n  * *D\\** — days;\n  * *1M* — one month.\n"
      schema:
        type: string
        default: M30
        enum:
        - M1
        - M3
        - M5
        - M15
        - M30
        - H1
        - H4
        - D1
        - D7
        - 1M
    marketData_offset:
      name: offset
      in: query
      description: 'The number of items to skip before starting to collect the result set. Offset can range between *0* and *100000*.

        '
      schema:
        maximum: 100000
        minimum: 0
        type: integer
        default: 0
    marketData_till:
      name: till
      in: query
      description: Interval end value.
      schema:
        type: string
        format: date-time
    marketData_sortAsc:
      name: sort
      in: query
      description: "Sort order:\n * Ascending, from A to Z.\n * Descending, from Z to A.\n"
      schema:
        type: string
        default: ASC
        enum:
        - DESC
        - ASC
    marketData_symbolPath:
      name: symbol
      in: path
      required: true
      description: Symbol code.
      schema:
        type: string
    marketData_limit100:
      name: limit
      in: query
      description: 'The number of items to return. The limit can range between *1* and *1000*.

        '
      schema:
        maximum: 1000
        minimum: 1
        type: integer
        default: 100
    marketData_symbolsQuery:
      name: symbols
      in: query
      style: form
      explode: false
      description: A comma-separated list of symbol codes.
      schema:
        type: array
        items:
          type: string
    marketData_limit10:
      name: limit
      in: query
      description: 'The number of items to return. The limit can range between *1* and *1000*.

        '
      schema:
        maximum: 1000
        minimum: 1
        type: integer
        default: 10
    marketData_Symbols:
      name: symbols
      in: query
      style: form
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/marketData_SymbolCommon'
      description: A comma-separated list of symbol codes.
    marketData_Limit100:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
      description: The number of items to return.
    marketData_Limit10:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 10
      description: The number of items to return.
    marketData_Pool:
      name: exclude_pool
      in: query
      schema:
        type: boolean
      description: Flag indicating whether to return trades for a single broker.
    marketData_Till:
      name: till
      in: query
      schema:
        allOf:
        - $ref: '#/components/schemas/marketData_TimestampCommon'
        - default: 1000
      description: Interval end value.
    marketData_SymbolPath:
      name: symbol
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/marketData_SymbolCommon'
    marketData_Period:
      name: period
      in: query
      schema:
        type: string
        enum:
        - M1
        - M3
        - M5
        - M15
        - M30
        - H1
        - H4
        - D1
        - D7
        - 1M
        default: M30
      description: "History time period.\n\nValues:\n  * `M*`—minutes;\n  * `H*`—hours;\n  * `D*`—days;\n  * `1M`—one month.\n"
    marketData_SortDesc:
      name: sort
      in: query
      schema:
        type: string
        enum:
        - DESC
        - ASC
        default: DESC
      description: "Sort order.\n\nValues:\n  * `ASC`—ascending;\n  * `DESC`—descending.\n"
    marketData_Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 100000
        default: 0
      description: The number of items to skip before starting to collect the result set.
    marketData_TargetCurrency:
      name: target_currency
      in: query
      required: true
      schema:
        allOf:
        - $ref: '#/components/schemas/marketData_CurrencyCommon'
        - description: Target currency for conversion.
    marketData_From:
      name: from
      in: query
      schema:
        allOf:
        - $ref: '#/components/schemas/marketData_TimestampCommon'
        - default: 1
      description: Interval start value.
  schemas:
    marketData_Candle:
      required:
      - close
      - max
      - min
      - open
      - timestamp
      - volume
      - volumeQuote
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          example: '2021-07-01T20:00:00.000Z'
          description: Candle timestamp.
        open:
          type: string
          example: '33079.93'
          description: Open price.
        close:
          type: string
          example: '33236.53'
          description: Closing price.
        min:
          type: string
          example: '33079.93'
          description: The lowest price for the period.
        max:
          type: string
          example: '33295.73'
          description: The highest price for the period.
        volume:
          type: string
          example: '146.86223'
          description: Volume in base currency.
        volumeQuote:
          type: string
          example: '4877838.3025063'
          description: Volume in quote currency.
    marketData_Error:
      required:
      - error
      type: object
      properties:
        error:
          required:
          - code
          - message
          type: object
          properties:
            code:
              type: integer
              format: int
            message:
              type: string
            description:
              type: string
    marketData_CandleBase:
      title: Candle
      type: object
      required:
      - timestamp
      - open
      - close
      - min
      - max
      properties:
        timestamp:
          type: string
          format: date-time
          example: '2024-03-22T15:04:05.590Z'
          description: Candle timestamp.
        open:
          type: string
          example: '0.063420'
          description: Open value.
        close:
          type: string
          example: '0.063767'
          description: Closing value.
        min:
          type: string
          example: '0.063403'
          description: The lowest value for the period.
        max:
          type: string
          example: '0.063782'
          description: The highest value for the period.
    marketData_Candle_2:
      allOf:
      - $ref: '#/components/schemas/marketData_VolumeBase'
      - $ref: '#/components/schemas/marketData_CandleBase'
    marketData_VolumeBase:
      title: Volume
      type: object
      required:
      - volume
      - volume_quote
      properties:
        volume:
          type: string
          description: Total trading volume in base currency.
          example: '1706.80119'
        volume_quote:
          type: string
          description: 'Total trading volume in quote currency.


            ℹ️ Volume of each trade is the trade quantity multiplied by its price.

            '
          example: '51792032.6885613'
    marketData_SymbolCommon:
      title: Symbol
      type: string
      description: Symbol code.
    marketData_CandleMap:
      title: Candles
      type: object
      additionalProperties:
        x-additionalPropertiesName: symbol
        type: array
        items:
          $ref: '#/components/schemas/marketData_Candle_2'
      example:
        BTCUSDT:
        - timestamp: '2024-06-26T12:32:01.636Z'
          open: '30320.16'
          close: '30289.45'
          min: '30269.59'
          max: '30370.84'
          volume: '1706.80119'
          volume_quote: '51792032.6885613'
    marketData_TimestampCommon:
      title: Timestamp
      oneOf:
      - title: ISO 8601
        type: string
        format: date-time
        description: 'Format: ISO 8601

          '
        example: '2024-03-22T15:04:05.590Z'
      - title: UNIX seconds
        type: integer
        description: 'Format: UNIX timestamp in seconds

          '
        example: 1687778487
      - title: UNIX milliseconds
        type: integer
        description: 'Format: UNIX timestamp in milliseconds

          '
        example: 1687778556151
    marketData_ConvertedCandles:
      title: Converted candle
      type: object
      required:
      - target_currency
      - data
      properties:
        target_currency:
          allOf:
          - $ref: '#/components/schemas/marketData_CurrencyCommon'
          - description: Target currency for conversion.
        data:
          $ref: '#/components/schemas/marketData_CandleMap'
    marketData_ConvertedCandle:
      title: Converted candle
      type: object
      required:
      - target_currency
      - data
      properties:
        target_currency:
          allOf:
          - $ref: '#/components/schemas/marketData_CurrencyCommon'
          - description: Target currency for conversion.
        data:
          type: array
          items:
            $ref: '#/components/schemas/marketData_Candle_2'
    marketData_Error_2:
      type: object
      required:
      - timestamp
      - error
      - path
      - requestId
      properties:
        timestamp:
          type: string
          format: date-time
          description: Request timestamp.
        error:
          type: object
          required:
          - description
          - code
          - message
          properties:
            description:
              type: string
              description: Error description.
            code:
              type: integer
              format: int
              description: Error code.
            message:
              type: string
              description: Error description.
        path:
          type: string
          description: Request path.
        requestId:
          type: string
          description: Request identifier.
    marketData_InstrumentNotFound:
      title: Instrument not found
      $ref: '#/components/schemas/marketData_Error_2'
      type: object
      description: Provided currency or symbol not found.
      example:
        timestamp: '2024-03-22T15:04:05.590Z'
        error:
          description: Try get /public/INSTRUMENT, to get list of all available INSTRUMENT.
          code: 2002
          message: 'No such INSTRUMENT: PARAMETER'
        path: /api/3/public/PATH
        requestId: 0cdf39b4-28499640
    marketData_Validation:
      $ref: '#/components/schemas/marketData_Error_2'
      type: object
      description: "Any of:\n  * missing required parameter;\n  * invalid value of a numeric parameter.\n"
      example:
        timestamp: '2024-03-22T15:04:05.590Z'
        error:
          description: Validation error. Please, check request parameters and try again.
          code: 10001
          message: Bad request parameter [PARAMETER] ISSUE
        path: /api/3/public/PATH
        requestId: 0cdf39b4-28499640
    marketData_CurrencyCommon:
      title: Currency
      type: string
      description: Currency code.
      example: USDT
    marketData_Candle_3:
      allOf:
      - $ref: '#/components/schemas/marketData_VolumeBase'
      - $ref: '#/components/schemas/marketData_CandleBase'
    marketData_CandleMap_2:
      title: Candles
      type: object
      additionalProperties:
        x-additionalPropertiesName: symbol
        type: array
        items:
          $ref: '#/components/schemas/marketData_Candle_3'
      example:
        BTCUSDT:
        - timestamp: '2024-06-26T12:32:01.636Z'
          open: '30320.16'
          close: '30289.45'
          min: '30269.59'
          max: '30370.84'
          volume: '1706.80119'
          volume_quote: '51792032.6885613'
    marketData_ConvertedCandle_2:
      title: Converted candle
      type: object
      required:
      - target_currency
      - data
      properties:
        target_currency:
          allOf:
          - $ref: '#/components/schemas/marketData_CurrencyCommon'
          - description: Target currency for conversion.
        data:
          type: array
          items:
            $ref: '#/components/schemas/marketData_Candle_3'
    marketData_Error_3:
      type: object
      required:
      - timestamp
      - error
      - path
      - requestId
      properties:
        timestamp:
          type: string
          format: date-time
          description: Request timestamp.
        error:
          type: object
          required:
          - description
          - code
          - message
          properties:
            description:
              type: string
              description: Error description.
            code:
              type: integer
              format: int
              description: Error code.
            message:
              type: string
              description: Error description.
        path:
          type: string
          description: Request path.
        requestId:
          type: string
          description: Request identifier.
    marketData_InstrumentNotFound_2:
      title: Instrument not found
      $ref: '#/components/schemas/marketData_Error_3'
      type: object
      description: Provided currency or symbol not found.
      example:
        timestamp: '2024-03-22T15:04:05.590Z'
        error:
          description: Try get /public/INSTRUMENT, to get list of all available INSTRUMENT.
          code: 2002
          message: 'No such INSTRUMENT: PARAMETER'
        path: /api/3/public/PATH
        requestId: 0cdf39b4-28499640
    marketData_Validation_2:
      $ref: '#/components/schemas/marketData_Error_3'
      type: object
      description: "Any of:\n  * missing required parameter;\n  * invalid value of a numeric parameter.\n"
      example:
        timestamp: '2024-03-22T15:04:05.590Z'
        error:
          description: Validation error. Please, check request parameters and try again.
          code: 10001
          message: Bad request parameter [PARAMETER] ISSUE
        path: /api/3/public/PATH
        requestId: 0cdf39b4-28499640
  responses:
    marketData_BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/marketData_Error'
    marketData_404:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            required:
            - timestamp
            - path
            - status
            - error
            - message
            - requestId
            properties:
              timestamp:
                type: string
                format: date-time
                description: Request timestamp.
                example: '2024-03-22T15:04:05.590Z'
              path:
                type: string
                description: Request path.
                example: /api/3/public/PATH
              status:
                type: integer
                description: Error status.
                example: 404
              error:
                type: string
                description: Error description.
                example: Not Found
              message:
                type: string
                nullable: true
                enum:
                - null
                description: Error message.
              requestId:
                type: string
                description: Request identifier.
                example: 0cdf39b4-28499640
  securitySchemes:
    wallet_BasicAuth:
      type: http
      description: You should use public API key as username and secret API key as password to authorize.
      scheme: basic
    wallet_BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    trading_BasicAuth:
      type: http
      description: You should use public API key as username and secret API key as password to authorize.
      scheme: basic
    trading_BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- hitbtc-api-v2-spec.yaml
- hitbtc-api-v3-spec.yaml
- hitbtc-openapi.yml
- hitbtc-v2-openapi.yml