openapi: 3.0.1
info:
  title: Amberdata DeFi Spot API
  description: Amberdata's institutional-grade digital asset and blockchain data API. Provides spot market data (prices, OHLCV, tickers, trades, order books), derivatives across futures and options (funding rates, open interest, liquidations, implied volatility, Greeks), DeFi (DEX and lending), and on-chain blockchain data (blocks, transactions, addresses, tokens). Every request requires the x-api-key header. An optional api-version header selects a dated API version.
  termsOfService: https://www.amberdata.io/terms-of-service
  contact:
    name: Amberdata Support
    url: https://www.amberdata.io/contact
  version: '1.0'
servers:
- url: https://api.amberdata.com
  description: Amberdata REST API
security:
- apiKeyAuth: []
tags:
- name: Spot
  description: Spot market data across supported exchanges.
paths:
  /markets/spot/exchanges/reference:
    get:
      operationId: getSpotExchangesReference
      tags:
      - Spot
      summary: Spot exchanges reference
      description: Returns reference information for all supported spot exchanges and the instruments (pairs) available on each.
      parameters:
      - $ref: '#/components/parameters/Exchange'
      - $ref: '#/components/parameters/Pair'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /markets/spot/prices/{pair}/latest:
    get:
      operationId: getSpotPriceLatest
      tags:
      - Spot
      summary: Latest spot price for a pair
      description: Returns the latest price for the specified spot pair (e.g. eth_usd).
      parameters:
      - $ref: '#/components/parameters/PairPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /markets/spot/ohlcv/{pair}/historical:
    get:
      operationId: getSpotOhlcvHistorical
      tags:
      - Spot
      summary: Historical spot OHLCV
      description: Returns historical OHLCV (open/high/low/close/volume) time series for the specified spot pair.
      parameters:
      - $ref: '#/components/parameters/PairPath'
      - $ref: '#/components/parameters/Exchange'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      - $ref: '#/components/parameters/TimeInterval'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /markets/spot/tickers/{pair}:
    get:
      operationId: getSpotTickers
      tags:
      - Spot
      summary: Spot tickers
      description: Returns historical and live best bid and best ask (top of book) for the specified spot instrument.
      parameters:
      - $ref: '#/components/parameters/PairPath'
      - $ref: '#/components/parameters/Exchange'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /markets/spot/trades/{pair}:
    get:
      operationId: getSpotTrades
      tags:
      - Spot
      summary: Historical spot trades
      description: Returns historical (time series) trade data for the specified spot pair or instrument.
      parameters:
      - $ref: '#/components/parameters/PairPath'
      - $ref: '#/components/parameters/Exchange'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /markets/spot/order-book-snapshots/{pair}:
    get:
      operationId: getSpotOrderBookSnapshots
      tags:
      - Spot
      summary: Spot order book snapshots
      description: Returns order book snapshots for the specified spot pair with granularity from 1 minute to 1 day.
      parameters:
      - $ref: '#/components/parameters/PairPath'
      - $ref: '#/components/parameters/Exchange'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
components:
  parameters:
    TimeInterval:
      name: timeInterval
      in: query
      required: false
      description: Time resolution of the returned series (e.g. minutes, hours, days).
      schema:
        type: string
    Pair:
      name: pair
      in: query
      required: false
      description: Filter by trading pair (e.g. eth_usd, btc_usd).
      schema:
        type: string
    StartDate:
      name: startDate
      in: query
      required: false
      description: Start of the time range (ISO 8601 timestamp or milliseconds epoch).
      schema:
        type: string
    Exchange:
      name: exchange
      in: query
      required: false
      description: Filter by exchange (e.g. binance, coinbase, deribit).
      schema:
        type: string
    PairPath:
      name: pair
      in: path
      required: true
      description: The trading pair (e.g. eth_usd, btc_usd).
      schema:
        type: string
    EndDate:
      name: endDate
      in: query
      required: false
      description: End of the time range (ISO 8601 timestamp or milliseconds epoch).
      schema:
        type: string
  schemas:
    ApiResponse:
      type: object
      description: Standard Amberdata API envelope. The requested data is returned under the payload property, alongside the HTTP status and a status message.
      properties:
        status:
          type: integer
          description: HTTP-style status code echoed in the response body.
          example: 200
        title:
          type: string
          description: Human-readable status message.
          example: OK
        description:
          type: string
          description: Additional context about the response.
        payload:
          type: object
          description: The response payload. Shape varies by endpoint; time series endpoints typically return metadata plus a data array.
          properties:
            metadata:
              type: object
              description: Metadata describing the payload (columns, request params, etc.).
            data:
              type: array
              description: The array of records for the requested resource.
              items:
                type: object
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Unique, user-specific API key. Required on every REST request via the x-api-key header.