AIXBT Candles API

openapi: 3.2.0
info:
  title: AIXBT Public Candles API
  version: 2.0.0
  description: 'Documentation for the AIXBT public API (v2).


    Most endpoints require an API key via the `x-api-key` header. Current topics, the deprecated `/grounding` topics alias, and cluster, category, and chain metadata are public. Historical topic data and all project, intel, signal, and recipe endpoints require authentication.


    Self-serve accounts can retrieve a rolling 90 days of proprietary AIXBT history, reported in `meta.history`. The boundary applies to explicit date ranges, historical `at` snapshots, pagination, and by-ID retrieval; older requests return `403 HISTORY_WINDOW_EXCEEDED` with the same `meta.history`. Accounts with the `archive-history` entitlement are uncapped. Current Topics and published Reports are excluded, while price candles and project market metrics retain their endpoint-specific windows.


    For full usage instructions, authentication and example projects, visit the documentation: docs.aixbt.tech.'
security:
- ApiKeyAuth: []
tags:
- name: Candles
paths:
  /v2/projects/{id}/candles:
    get:
      summary: Price Candles (OHLCV)
      tags:
      - Candles
      description: 'Returns OHLCV candlestick data from TimescaleDB metric history.

        Each candle is an array: `[timestamp_ms, open, high, low, close, volume24h]`.


        `volume24h` is the rolling 24-hour volume at candle close, not per-interval volume.


        **Interval defaults and caps:**

        | Interval | Default range | Max range |

        |----------|--------------|-----------|

        | `5m` | 24 hours | 48 hours |

        | `1h` | 7 days | 14 days |

        | `1d` | 30 days | 90 days |


        If the requested range exceeds the max, `start` is clamped forward (most recent candles are returned).'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: MongoDB ObjectId of the project
      - in: query
        name: interval
        required: true
        schema:
          type: string
          enum:
          - 5m
          - 1h
          - 1d
        description: Candle interval
      - in: query
        name: start
        schema:
          type: string
          format: date-time
        description: Start timestamp (ISO 8601). Defaults to interval-dependent lookback from end.
      - in: query
        name: end
        schema:
          type: string
          format: date-time
        description: End timestamp (ISO 8601). Defaults to now.
      - in: query
        name: at
        schema:
          type: string
          format: date-time
        description: 'Historical anchor timestamp (ISO 8601). Caps `end` and shifts the default lookback.

          Must be in the past.


          When used:

          - If `end` is not provided, `at` sets the end of the window

          - If `end` is provided, `at` acts as a ceiling — `end` is capped to whichever is earlier

          - If `start` is not provided, it defaults to the interval''s default lookback before `at`

          '
        example: 2026-03-25 12:00:00+00:00
      responses:
        '200':
          description: OHLCV candle data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  meta:
                    $ref: '#/components/schemas/UpgradeMeta'
                  data:
                    type: object
                    properties:
                      projectId:
                        type: string
                        example: 507f1f77bcf86cd799439011
                      projectName:
                        type: string
                        example: Bitcoin
                      interval:
                        type: string
                        example: 1h
                      candles:
                        type: array
                        description: 'Array of candle arrays. Each inner array: [timestamp_ms, open, high, low, close, volume24h].

                          Timestamps are Unix milliseconds. volume24h is rolling 24h volume at candle close.

                          '
                        items:
                          type: array
                          minItems: 6
                          maxItems: 6
                          items:
                            type:
                            - number
                            - 'null'
                          example:
                          - 1709395200000
                          - 0.0523
                          - 0.0531
                          - 0.0519
                          - 0.0527
                          - 1234567
        '400':
          description: Invalid parameters (bad interval, project ID format, or date format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Authentication required. Provide an API key to access this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Project not found, or price candles are not available for an NFT collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Failed to fetch candle data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Price data temporarily unavailable (TimescaleDB connectivity issue)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: getV2ProjectsByIdCandles
components:
  schemas:
    Pagination:
      type: object
      required:
      - page
      - limit
      - totalCount
      - hasMore
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
        totalCount:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
    ApiError:
      type: object
      required:
      - error
      description: Error response. Middleware may include additional rate-limit or access metadata.
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
        status:
          type: integer
        data: {}
        meta:
          type: object
          additionalProperties: true
        details:
          type: object
          additionalProperties: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        limitType:
          type: string
          enum:
          - minute
          - day
          description: Rate-limit window that was exhausted.
        retryAfterMs:
          type: integer
          minimum: 0
          description: Milliseconds until the exhausted window resets.
        limits:
          type: object
          required:
          - minute
          - day
          properties:
            minute:
              $ref: '#/components/schemas/RateLimitWindow'
            day:
              $ref: '#/components/schemas/RateLimitWindow'
        issues:
          type: array
          items:
            type: object
            required:
            - path
            - message
            properties:
              path:
                type: string
              message:
                type: string
      additionalProperties: true
    UpgradeMeta:
      type: object
      description: Present on supported unauthenticated responses with an account access link.
      properties:
        upgrade:
          type: object
          properties:
            description:
              type: string
            url:
              type: string
              format: uri
              example: https://aixbt.tech/subscribe
    RateLimitWindow:
      type: object
      required:
      - limit
      - remaining
      - resetAt
      properties:
        limit:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        resetAt:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key to authorize requests