openapi: 3.1.0
info:
  title: CoinDesk Data API (CCData) Asset Spot API
  description: 'The CoinDesk Data API (formerly CCData / CryptoCompare data-api) is the modern, institutional-grade replacement for the legacy min-api. It exposes a consolidated surface across Spot markets (latest tick, instrument metadata, historical OHLCV, trades, order book L1), CoinDesk Indices and Reference Rates (CADLI, CCIX, CCIXBE), Futures and Options derivatives, Asset metadata and overview, On-chain data, News articles, and Polling / On-demand exports. Authentication uses an API key supplied either as the api_key query parameter or as `Authorization: Apikey {apiKey}`. The base URL is https://data-api.cryptocompare.com.'
  version: '1.0'
  contact:
    name: CoinDesk Data Support
    url: https://developers.coindesk.com/support
    email: data@cryptocompare.com
  termsOfService: https://data.coindesk.com/terms
  license:
    name: CoinDesk Data API Terms
    url: https://data.coindesk.com/terms
servers:
- url: https://data-api.cryptocompare.com
  description: Production Server
security:
- apiKeyQuery: []
- apiKeyHeader: []
tags:
- name: Spot
  description: Spot market data including latest tick, historical OHLCV, trades, order book L1, and instrument metadata.
paths:
  /spot/v1/latest/tick:
    get:
      operationId: getSpotLatestTick
      summary: Get Spot Latest Tick
      description: Returns the latest tick (trade or top-of-book update) for one or more spot instruments on a given market.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      - $ref: '#/components/parameters/InstrumentsParam'
      - $ref: '#/components/parameters/GroupsParam'
      responses:
        '200':
          description: Latest tick envelope per instrument.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpotTickResponse'
  /spot/v2/markets:
    get:
      operationId: getSpotMarketsList
      summary: List Spot Markets
      description: Returns the list of integrated spot exchanges and their status.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      responses:
        '200':
          description: Markets list envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketsListResponse'
  /spot/v1/markets/instruments:
    get:
      operationId: getSpotInstrumentMetadata
      summary: Get Spot Instrument Metadata
      description: Returns reference metadata for spot instruments on a given market including base/quote symbols, tick sizes, status, and mapping.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      - $ref: '#/components/parameters/InstrumentsParam'
      responses:
        '200':
          description: Instrument metadata envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstrumentMetadataResponse'
  /spot/v1/historical/days:
    get:
      operationId: getSpotHistoricalDaily
      summary: Get Spot Historical Daily OHLCV
      description: Returns daily OHLCV candles for a single spot instrument on a given market, ordered ascending. Up to 2000 candles per call.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      - $ref: '#/components/parameters/InstrumentParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ToTsParam'
      - $ref: '#/components/parameters/AggregateParam'
      - $ref: '#/components/parameters/FillParam'
      - $ref: '#/components/parameters/ApplyMappingParam'
      responses:
        '200':
          description: Historical daily OHLCV envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalOHLCVResponse'
  /spot/v1/historical/hours:
    get:
      operationId: getSpotHistoricalHourly
      summary: Get Spot Historical Hourly OHLCV
      description: Returns hourly OHLCV candles for a single spot instrument.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      - $ref: '#/components/parameters/InstrumentParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ToTsParam'
      - $ref: '#/components/parameters/AggregateParam'
      responses:
        '200':
          description: Historical hourly OHLCV envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalOHLCVResponse'
  /spot/v1/historical/minutes:
    get:
      operationId: getSpotHistoricalMinute
      summary: Get Spot Historical Minute OHLCV
      description: Returns minute OHLCV candles for a single spot instrument.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      - $ref: '#/components/parameters/InstrumentParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ToTsParam'
      - $ref: '#/components/parameters/AggregateParam'
      responses:
        '200':
          description: Historical minute OHLCV envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalOHLCVResponse'
  /spot/v1/historical/trades:
    get:
      operationId: getSpotHistoricalTrades
      summary: Get Spot Historical Trades
      description: Returns raw historical trade prints for a single spot instrument.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      - $ref: '#/components/parameters/InstrumentParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ToTsParam'
      responses:
        '200':
          description: Trades envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradesResponse'
  /spot/v1/latest/orderbook/l1/top:
    get:
      operationId: getSpotOrderbookL1Top
      summary: Get Spot Order Book L1 Top
      description: Returns the top of the order book (best bid and best ask) for one or more spot instruments. Updated continuously.
      tags:
      - Spot
      parameters:
      - $ref: '#/components/parameters/MarketParam'
      - $ref: '#/components/parameters/InstrumentsParam'
      responses:
        '200':
          description: L1 top of book envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderbookL1TopResponse'
components:
  parameters:
    ApplyMappingParam:
      name: apply_mapping
      in: query
      description: Apply asset/instrument mapping for renames.
      schema:
        type: boolean
        default: true
    MarketParam:
      name: market
      in: query
      required: true
      description: Spot or derivatives market (e.g. coinbase, kraken, binance, bitstamp, ccix).
      schema:
        type: string
    InstrumentsParam:
      name: instruments
      in: query
      required: true
      description: Comma-separated instrument identifiers (e.g. BTC-USD,ETH-USD).
      schema:
        type: string
    GroupsParam:
      name: groups
      in: query
      description: Comma-separated tick groups to return (VALUE, CURRENT_HOUR, CURRENT_DAY, MOVING_24_HOUR, LIFETIME).
      schema:
        type: string
    FillParam:
      name: fill
      in: query
      description: Fill empty periods with zero-volume candles.
      schema:
        type: boolean
        default: true
    InstrumentParam:
      name: instrument
      in: query
      required: true
      description: Single instrument identifier (e.g. BTC-USD).
      schema:
        type: string
    ToTsParam:
      name: to_ts
      in: query
      description: Upper bound timestamp in seconds.
      schema:
        type: integer
        format: int64
    LimitParam:
      name: limit
      in: query
      description: Number of data points to return.
      schema:
        type: integer
        default: 30
        maximum: 2000
    AggregateParam:
      name: aggregate
      in: query
      description: Time-period aggregation factor.
      schema:
        type: integer
        default: 1
  schemas:
    TradesResponse:
      type: object
      properties:
        Data:
          type: array
          items:
            type: object
            properties:
              TYPE:
                type: string
              MARKET:
                type: string
              INSTRUMENT:
                type: string
              MAPPED_INSTRUMENT:
                type: string
              SIDE:
                type: string
                enum:
                - BUY
                - SELL
                - UNKNOWN
              ID:
                type: string
              TIMESTAMP:
                type: integer
                format: int64
              TIMESTAMP_NS:
                type: integer
              RECEIVED_TIMESTAMP:
                type: integer
                format: int64
              QUANTITY:
                type: number
              PRICE:
                type: number
              QUOTE_QUANTITY:
                type: number
              CCSEQ:
                type: integer
                format: int64
    OrderbookL1TopResponse:
      type: object
      properties:
        Data:
          type: object
          additionalProperties:
            type: object
            properties:
              TYPE:
                type: string
              MARKET:
                type: string
              INSTRUMENT:
                type: string
              BEST_BID:
                type: number
              BEST_BID_QUANTITY:
                type: number
              BEST_ASK:
                type: number
              BEST_ASK_QUANTITY:
                type: number
              BEST_BID_LAST_UPDATE_TS:
                type: integer
                format: int64
              BEST_ASK_LAST_UPDATE_TS:
                type: integer
                format: int64
    MarketsListResponse:
      type: object
      properties:
        Data:
          type: object
          additionalProperties:
            type: object
            properties:
              TYPE:
                type: string
              EXCHANGE_STATUS:
                type: string
              MAPPED_INSTRUMENTS_TOTAL:
                type: integer
              UNMAPPED_INSTRUMENTS_TOTAL:
                type: integer
              INSTRUMENT_STATUS:
                type: object
              TOTAL_TRADES_SPOT:
                type: integer
              HAS_ORDERBOOK_L2_MINUTE_SNAPSHOTS_ENABLED:
                type: boolean
    HistoricalOHLCVResponse:
      type: object
      properties:
        Data:
          type: array
          items:
            $ref: '#/components/schemas/HistoricalOHLCVRow'
        Err:
          type: object
    SpotTick:
      type: object
      properties:
        TYPE:
          type: string
        MARKET:
          type: string
        INSTRUMENT:
          type: string
        CCSEQ:
          type: integer
          format: int64
        PRICE:
          type: number
        PRICE_LAST_UPDATE_TS:
          type: integer
          format: int64
        VOLUME:
          type: number
        QUOTE_VOLUME:
          type: number
        VOLUME_TOP_TIER:
          type: number
        QUOTE_VOLUME_TOP_TIER:
          type: number
        CURRENT_HOUR_VOLUME:
          type: number
        CURRENT_HOUR_QUOTE_VOLUME:
          type: number
        CURRENT_HOUR_OPEN:
          type: number
        CURRENT_HOUR_HIGH:
          type: number
        CURRENT_HOUR_LOW:
          type: number
        CURRENT_HOUR_CHANGE:
          type: number
        CURRENT_HOUR_CHANGE_PERCENTAGE:
          type: number
        CURRENT_DAY_OPEN:
          type: number
        CURRENT_DAY_HIGH:
          type: number
        CURRENT_DAY_LOW:
          type: number
        CURRENT_DAY_CHANGE:
          type: number
        CURRENT_DAY_CHANGE_PERCENTAGE:
          type: number
        MOVING_24_HOUR_VOLUME:
          type: number
        MOVING_24_HOUR_QUOTE_VOLUME:
          type: number
        MOVING_24_HOUR_OPEN:
          type: number
        MOVING_24_HOUR_HIGH:
          type: number
        MOVING_24_HOUR_LOW:
          type: number
        MOVING_24_HOUR_CHANGE:
          type: number
        MOVING_24_HOUR_CHANGE_PERCENTAGE:
          type: number
        LIFETIME_FIRST_TRADE_TS:
          type: integer
          format: int64
        LIFETIME_HIGH:
          type: number
        LIFETIME_LOW:
          type: number
    SpotTickResponse:
      type: object
      properties:
        Data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SpotTick'
        Err:
          type: object
    InstrumentMetadataResponse:
      type: object
      properties:
        Data:
          type: object
          additionalProperties:
            type: object
            properties:
              METADATA_VERSION:
                type: integer
              INSTRUMENT_STATUS:
                type: string
              INSTRUMENT:
                type: string
              HISTO_SHARD:
                type: string
              MAPPED_INSTRUMENT:
                type: string
              INSTRUMENT_MAPPING:
                type: object
              HAS_TRADES_SPOT:
                type: boolean
              FIRST_TRADE_SPOT_TIMESTAMP:
                type: integer
                format: int64
              LAST_TRADE_SPOT_TIMESTAMP:
                type: integer
                format: int64
              TOTAL_TRADES_SPOT:
                type: integer
    HistoricalOHLCVRow:
      type: object
      properties:
        UNIT:
          type: string
          enum:
          - MINUTE
          - HOUR
          - DAY
        TIMESTAMP:
          type: integer
          format: int64
        TYPE:
          type: string
        MARKET:
          type: string
        INSTRUMENT:
          type: string
        MAPPED_INSTRUMENT:
          type: string
        BASE:
          type: string
        QUOTE:
          type: string
        OPEN:
          type: number
        HIGH:
          type: number
        LOW:
          type: number
        CLOSE:
          type: number
        FIRST_TRADE_TIMESTAMP:
          type: integer
          format: int64
        LAST_TRADE_TIMESTAMP:
          type: integer
          format: int64
        FIRST_TRADE_PRICE:
          type: number
        HIGH_TRADE_PRICE:
          type: number
        LOW_TRADE_PRICE:
          type: number
        LAST_TRADE_PRICE:
          type: number
        VOLUME:
          type: number
        QUOTE_VOLUME:
          type: number
        VOLUME_BUY:
          type: number
        QUOTE_VOLUME_BUY:
          type: number
        VOLUME_SELL:
          type: number
        QUOTE_VOLUME_SELL:
          type: number
        TOTAL_TRADES:
          type: integer
        TOTAL_TRADES_BUY:
          type: integer
        TOTAL_TRADES_SELL:
          type: integer
        TOTAL_TRADES_UNKNOWN:
          type: integer
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      name: api_key
      in: query
      description: API key supplied as the api_key query parameter.
    apiKeyHeader:
      type: apiKey
      name: Authorization
      in: header
      description: 'API key supplied as `Authorization: Apikey {apiKey}`.'
externalDocs:
  description: CoinDesk Data API Documentation
  url: https://developers.coindesk.com/documentation/data-api/introduction