openapi: 3.2.0
info:
  title: Bitculator Data Prices API
  description: 'Programmatic access to Bitculator market data: coins, prices, history, exchanges, trust scores, tickers, pairs, wallets, sentiment, technical indicators, liquidations, editorial content, and calculators.'
  version: 1.0.0
servers:
- url: https://bitculator.com
security:
- default: []
tags:
- name: Prices
  description: 'The lightweight price hot path — current price, marketcap, 24h volume and recent

    changes for a requested set of coins. `/prices` requires a selector (ids, slugs or

    symbols); `/prices/{slug}` targets one coin. Optionally `convert` into a fiat

    currency (crypto prices refresh ~every minute, fiat FX ~twice daily). Prices and

    marketcap are decimal strings.'
paths:
  /api/v1/prices:
    get:
      summary: Get prices
      operationId: getPrices
      description: 'Prices for a requested set of coins. Pass at least one selector — `ids`, `slugs`

        or `symbols` (up to 100 combined). `meta.currency` echoes the conversion target

        (USD unless `convert` is set).'
      parameters:
      - in: query
        name: ids
        description: Coin ids to price (CSV). At least one of ids, slugs or symbols is required; the three lists cap at 100 selectors combined. This field is required when none of <code>slugs</code> and <code>symbols</code> are present. Must not be greater than 1000 characters.
        example: 38,39
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Coin ids to price (CSV). At least one of ids, slugs or symbols is required; the three lists cap at 100 selectors combined. This field is required when none of <code>slugs</code> and <code>symbols</code> are present. Must not be greater than 1000 characters.
          example: 38,39
      - in: query
        name: slugs
        description: Coin slugs to price (CSV). At least one of ids, slugs or symbols is required. This field is required when none of <code>ids</code> and <code>symbols</code> are present. Must not be greater than 2000 characters.
        example: bitcoin,ethereum
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Coin slugs to price (CSV). At least one of ids, slugs or symbols is required. This field is required when none of <code>ids</code> and <code>symbols</code> are present. Must not be greater than 2000 characters.
          example: bitcoin,ethereum
      - in: query
        name: symbols
        description: Coin symbols to price (CSV, case-insensitive). At least one of ids, slugs or symbols is required. This field is required when none of <code>ids</code> and <code>slugs</code> are present. Must not be greater than 1000 characters.
        example: BTC,ETH
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Coin symbols to price (CSV, case-insensitive). At least one of ids, slugs or symbols is required. This field is required when none of <code>ids</code> and <code>slugs</code> are present. Must not be greater than 1000 characters.
          example: BTC,ETH
      - in: query
        name: convert
        description: Convert prices/marketcap into an active fiat currency by symbol (default USD). FX rates refresh ~twice daily.
        example: EUR
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Convert prices/marketcap into an active fiat currency by symbol (default USD). FX rates refresh ~twice daily.
          example: EUR
          enum:
          - USD
          - EUR
          - JPY
          - BGN
          - CZK
          - DKK
          - GBP
          - HUF
          - PLN
          - RON
          - SEK
          - CHF
          - ISK
          - NOK
          - HRK
          - RUB
          - TRY
          - AUD
          - BRL
          - CAD
          - CNY
          - HKD
          - IDR
          - ILS
          - INR
          - KRW
          - MXN
          - MYR
          - NZD
          - PHP
          - SGD
          - THB
          - ZAR
          - ARS
          - DZD
          - MAD
          - TWD
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                  - id: 38
                    slug: bitcoin
                    symbol: BTC
                    name: Bitcoin
                    rank: 1
                    price: '63520.780763913'
                    marketcap: 1264646594448.5
                    volume_24h: 5345161962
                    change_24h: 1.35
                    change_7d: 4.98
                    change_rank_24h: 0
                    change_rank_7d: 0
                    last_updated: '2026-06-27T10:34:17+00:00'
                  - id: 39
                    slug: ethereum
                    symbol: ETH
                    name: Ethereum
                    rank: 2
                    price: '1672.4623100248'
                    marketcap: 203243220990.49
                    volume_24h: 69585141532
                    change_24h: 1.42
                    change_7d: 7.56
                    change_rank_24h: 0
                    change_rank_7d: 0
                    last_updated: '2026-06-12T09:32:14+00:00'
                  meta:
                    currency: USD
                    count: 2
                properties:
                  data:
                    type: array
                    example:
                    - id: 38
                      slug: bitcoin
                      symbol: BTC
                      name: Bitcoin
                      rank: 1
                      price: '63520.780763913'
                      marketcap: 1264646594448.5
                      volume_24h: 5345161962
                      change_24h: 1.35
                      change_7d: 4.98
                      change_rank_24h: 0
                      change_rank_7d: 0
                      last_updated: '2026-06-27T10:34:17+00:00'
                    - id: 39
                      slug: ethereum
                      symbol: ETH
                      name: Ethereum
                      rank: 2
                      price: '1672.4623100248'
                      marketcap: 203243220990.49
                      volume_24h: 69585141532
                      change_24h: 1.42
                      change_7d: 7.56
                      change_rank_24h: 0
                      change_rank_7d: 0
                      last_updated: '2026-06-12T09:32:14+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 38
                        slug:
                          type: string
                          example: bitcoin
                        symbol:
                          type: string
                          example: BTC
                        name:
                          type: string
                          example: Bitcoin
                        rank:
                          type: integer
                          example: 1
                        price:
                          type: string
                          example: '63520.780763913'
                        marketcap:
                          type: number
                          example: 1264646594448.5
                        volume_24h:
                          type: integer
                          example: 5345161962
                        change_24h:
                          type: number
                          example: 1.35
                        change_7d:
                          type: number
                          example: 4.98
                        change_rank_24h:
                          type: integer
                          example: 0
                        change_rank_7d:
                          type: integer
                          example: 0
                        last_updated:
                          type: string
                          example: '2026-06-27T10:34:17+00:00'
                  meta:
                    type: object
                    properties:
                      currency:
                        type: string
                        example: USD
                      count:
                        type: integer
                        example: 2
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: validation
                    message: The request parameters are invalid.
                    details:
                      errors:
                        ids:
                        - 'Pass at least one selector: ids, slugs or symbols.'
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation
                      message:
                        type: string
                        example: The request parameters are invalid.
                      details:
                        type: object
                        properties:
                          errors:
                            type: object
                            properties:
                              ids:
                                type: array
                                example:
                                - 'Pass at least one selector: ids, slugs or symbols.'
                                items:
                                  type: string
      tags:
      - Prices
  /api/v1/prices/{slug}:
    parameters:
    - in: path
      name: slug
      description: The coin slug.
      example: bitcoin
      required: true
      schema:
        type: string
    get:
      summary: Get a coin price
      operationId: getACoinPrice
      description: 'Single-coin price snapshot. Optionally `convert` into an active fiat currency by

        symbol (default USD).'
      parameters:
      - in: query
        name: convert
        description: Active fiat currency symbol to price in (default USD).
        example: EUR
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Active fiat currency symbol to price in (default USD).
          example: EUR
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 38
                    slug: bitcoin
                    symbol: BTC
                    name: Bitcoin
                    rank: 1
                    price: '63520.780763913'
                    marketcap: 1264646594448.5
                    volume_24h: 5345161962
                    change_24h: 1.35
                    change_7d: 4.98
                    change_rank_24h: 0
                    change_rank_7d: 0
                    last_updated: '2026-06-27T10:34:17+00:00'
                  meta:
                    currency: USD
                    count: 1
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 38
                      slug:
                        type: string
                        example: bitcoin
                      symbol:
                        type: string
                        example: BTC
                      name:
                        type: string
                        example: Bitcoin
                      rank:
                        type: integer
                        example: 1
                      price:
                        type: string
                        example: '63520.780763913'
                      marketcap:
                        type: number
                        example: 1264646594448.5
                      volume_24h:
                        type: integer
                        example: 5345161962
                      change_24h:
                        type: number
                        example: 1.35
                      change_7d:
                        type: number
                        example: 4.98
                      change_rank_24h:
                        type: integer
                        example: 0
                      change_rank_7d:
                        type: integer
                        example: 0
                      last_updated:
                        type: string
                        example: '2026-06-27T10:34:17+00:00'
                  meta:
                    type: object
                    properties:
                      currency:
                        type: string
                        example: USD
                      count:
                        type: integer
                        example: 1
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  error:
                    code: not_found
                    message: Coin not found.
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: Coin not found.
      tags:
      - Prices
  /api/v1/historical-price:
    get:
      summary: Historical price
      operationId: historicalPrice
      description: 'The coin''s USD price on a given date, read from the daily history (exact day,

        ±3-day fallback — the same resolver the portfolio uses). Crypto only: fiat rows

        have no daily history.'
      parameters:
      - in: query
        name: slug
        description: The coin's slug identifier.
        example: bitcoin
        required: true
        schema:
          type: string
          description: The coin's slug identifier.
          example: bitcoin
      - in: query
        name: date
        description: date The lookup date (after 2008-12-31, not in the future).
        example: '2021-04-14'
        required: true
        schema:
          type: string
          description: date The lookup date (after 2008-12-31, not in the future).
          example: '2021-04-14'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    slug: bitcoin
                    symbol: BTC
                    date: '2021-04-14'
                    price: '63109.7'
                    currency: USD
                properties:
                  data:
                    type: object
                    properties:
                      slug:
                        type: string
                        example: bitcoin
                      symbol:
                        type: string
                        example: BTC
                      date:
                        type: string
                        example: '2021-04-14'
                      price:
                        type: string
                        example: '63109.7'
                      currency:
                        type: string
                        example: USD
      tags:
      - Prices
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: Create a Data API key in your <a href="/user/developer/api">developer console</a> — keys are Bearer-only and carry the <code>data-api</code> ability. Keep them server-side; they are never meant for client-side embedding.