openapi: 3.1.0
info:
  title: Overlay Market Data API
  version: v1
  description: >-
    Public, unauthenticated market-data API for the Overlay Protocol — a
    decentralized perpetual-futures protocol on BNB Smart Chain (chain id 56).
    Covers the CoinGecko/CMC-style aggregator feed, the market catalog, and the
    charts price-overview feed. All endpoints are read-only and public.
    Trading itself is executed on-chain against Overlay smart contracts (Shiva,
    OverlayV1State); this API surfaces the off-chain data/indexing layer.
  contact:
    name: Overlay Protocol
    url: https://docs.overlay.market/
  x-provenance:
    generated: '2026-07-20'
    method: searched
    source: >-
      https://docs.overlay.market/api/aggregator-market-data + live probes of
      https://api.overlay.market (2026-07-20, HTTP 200)
servers:
  - url: https://api.overlay.market
    description: Production
tags:
  - name: Aggregator
    description: CoinGecko/CMC-style aggregator market-data feed.
  - name: Markets
    description: Market catalog and metadata.
  - name: Charts
    description: Price overview and OHLC chart data.
paths:
  /data/api/aggregator/contracts:
    get:
      operationId: getAggregatorContracts
      tags: [Aggregator]
      summary: List aggregator market data for all enabled markets
      description: >-
        Returns comprehensive market data for every enabled derivative market
        (price, 24h volume, bid/ask, open interest, index price, funding rate).
        Responses are cached for 60 seconds. Unavailable markets are omitted.
      responses:
        '200':
          description: Array of market data records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AggregatorContract'
        '503':
          description: All markets failed and no cached data was available.
  /data/api/aggregator/contract_specs:
    get:
      operationId: getAggregatorContractSpecs
      tags: [Aggregator]
      summary: List contract specifications for all enabled markets
      description: Returns a contract-specification subset for each enabled market.
      responses:
        '200':
          description: Array of contract specifications.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContractSpec'
        '503':
          description: All markets failed and no cached data was available.
  /data/api/markets:
    get:
      operationId: getMarkets
      tags: [Markets]
      summary: List the market catalog keyed by chain id
      description: >-
        Returns the market catalog as an object keyed by chain id (e.g. "56"
        for BNB Smart Chain), each value an array of market metadata records
        (name, logo, currency, description/methodology).
      responses:
        '200':
          description: Market catalog keyed by chain id.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/Market'
  /bsc-charts/v1/charts/marketsPricesOverview:
    get:
      operationId: getMarketsPricesOverview
      tags: [Charts]
      summary: Price overview across markets
      description: >-
        Returns a per-market price overview — latest price, price seven days
        ago, and a series of recent prices for sparkline rendering.
      responses:
        '200':
          description: Array of per-market price overviews.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketPriceOverview'
components:
  schemas:
    AggregatorContract:
      type: object
      description: One enabled market's aggregator data record.
      properties:
        ticker_id: { type: string, example: BTC-USD-PERP, description: Market identifier. }
        contract_type: { type: string, example: vanilla }
        contract_price_currency: { type: string, example: USD }
        contract_price: { type: number, description: Optional; omitted when equal to last_price. }
        base_currency: { type: string, example: BTC }
        target_currency: { type: string, example: USD }
        last_price: { type: number, description: Current market mid price. }
        base_volume: { type: number, description: Rolling 24h volume in base units. }
        target_volume: { type: number, description: Rolling 24h volume in quote units. }
        bid: { type: number }
        ask: { type: number }
        high: { type: number, description: Rolling 24h high. }
        low: { type: number, description: Rolling 24h low. }
        product_type: { type: string, example: perpetual }
        open_interest: { type: number, description: Total open interest in base units. }
        open_interest_usd: { type: number }
        index_price: { type: number }
        index_name: { type: string, example: BTC-USD }
        index_currency: { type: string, example: USD }
        start_timestamp: { type: integer }
        end_timestamp: { type: integer, description: Response/cache timestamp. }
        funding_rate: { type: number, description: Daily funding rate as a decimal. }
        next_funding_rate: { type: number }
        next_funding_rate_timestamp: { type: integer }
      required: [ticker_id, contract_type, base_currency, target_currency, last_price]
    ContractSpec:
      type: object
      properties:
        ticker_id: { type: string, example: BTC-USD-PERP }
        contract_type: { type: string, example: vanilla }
        contract_price_currency: { type: string, example: USD }
      required: [ticker_id, contract_type, contract_price_currency]
    Market:
      type: object
      description: Market catalog metadata record.
      properties:
        _id: { type: string, example: 66d71b2f72d1c12e59686e23 }
        marketName: { type: string, example: Counter-Strike 2 Skins }
        logo: { type: string }
        currency: { type: string, example: USD }
        descriptionText: { type: string, description: What the market tracks + methodology. }
    MarketPriceOverview:
      type: object
      properties:
        marketAddress: { type: string, description: On-chain market contract address (BSC). }
        latestPrice: { type: number }
        priceSevenDaysAgo: { type: number }
        prices:
          type: array
          items: { type: number }
          description: Recent price series for sparkline rendering.