openapi: "3.1.0"
info:
  title: CryptoData API
  description: "The most comprehensive crypto data API. Market data, DeFi yields, TVL, meme coin scanner, rug analysis, on-chain data, sentiment, trending, gainers/losers, global metrics. One API for everything crypto."
  version: "2.0.0"
  contact:
    name: CryptoData API
  x-agent-Provider: CryptoData
servers:
  - url: https://cryptodata-api.datachain.workers.dev
    description: Production server (Cloudflare Workers)

paths:
  /api/price:
    get:
      operationId: getPrice
      summary: Real-time crypto prices
      description: Get real-time prices for any coins with 24h change and market cap
      parameters:
        - name: coins
          in: query
          description: "Comma-separated coin IDs (e.g. bitcoin,ethereum,solana)"
          required: true
          schema:
            type: string
            default: bitcoin,ethereum
        - name: vs
          in: query
          description: Currency
          required: false
          schema:
            type: string
            default: usd
            enum: [usd, eur, gbp, btc, eth, jpy, cny]
      x-agent-cost: 0.001
      responses:
        "200":
          description: Price data
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    example: coingecko
                  prices:
                    type: object
                    additionalProperties:
                      type: object
                  timestamp:
                    type: string
                    format: date-time

  /api/trending:
    get:
      operationId: getTrending
      summary: Trending cryptocurrencies
      description: Get the most trending coins on CoinGecko right now
      x-agent-cost: 0.001
      responses:
        "200":
          description: Trending coins
          content:
            application/json:
              schema:
                type: object
                properties:
                  trending:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        symbol:
                          type: string
                        market_cap_rank:
                          type: integer
                  timestamp:
                    type: string

  /api/top:
    get:
      operationId: getTopCoins
      summary: Top coins by market cap
      description: Get the top cryptocurrencies ranked by market capitalization
      parameters:
        - name: limit
          in: query
          description: Number of coins (max 100)
          required: false
          schema:
            type: integer
            default: 20
        - name: vs
          in: query
          description: Currency
          required: false
          schema:
            type: string
            default: usd
      x-agent-cost: 0.001
      responses:
        "200":
          description: Top coins
          content:
            application/json:
              schema:
                type: object

  /api/fear-greed:
    get:
      operationId: getFearGreed
      summary: Fear & Greed index
      description: Get the current Fear & Greed market sentiment index and historical data
      parameters:
        - name: limit
          in: query
          description: "Days of history (1-365)"
          required: false
          schema:
            type: integer
            default: 30
      x-agent-cost: 0.001
      responses:
        "200":
          description: Fear & Greed data
          content:
            application/json:
              schema:
                type: object

  /api/gas:
    get:
      operationId: getGasPrices
      summary: Ethereum gas prices
      description: Get current Ethereum gas prices (low, average, fast in Gwei)
      x-agent-cost: 0.001
      responses:
        "200":
          description: Gas prices
          content:
            application/json:
              schema:
                type: object
                properties:
                  chain:
                    type: string
                    example: ethereum
                  gas:
                    type: object

  /api/global:
    get:
      operationId: getGlobalMarket
      summary: Global crypto market data
      description: Get total market cap, 24h volume, BTC dominance, active cryptocurrencies
      x-agent-cost: 0.001
      responses:
        "200":
          description: Global data
          content:
            application/json:
              schema:
                type: object

  /api/coin/{id}:
    get:
      operationId: getCoinDetail
      summary: Detailed coin information
      description: Get comprehensive details about any cryptocurrency including price, market cap, description, and links
      parameters:
        - name: id
          in: path
          description: "Coin ID (e.g. bitcoin, ethereum, solana)"
          required: true
          schema:
            type: string
      x-agent-cost: 0.002
      responses:
        "200":
          description: Coin detail
          content:
            application/json:
              schema:
                type: object

  /api/health:
    get:
      operationId: healthCheck
      summary: Health check
      description: Check if the API is operational
      x-agent-cost: 0
      responses:
        "200":
          description: Health status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

  /api/meme/scan:
    get:
      operationId: scanMemeCoins
      summary: Scan for new meme coins
      description: "Get the latest tokens launched on DEXes. Ideal for meme coin hunting — returns new tokens with liquidity, volume, price data."
      parameters:
        - name: chain
          in: query
          description: "Chain filter: solana, ethereum, base, bsc, all"
          required: false
          schema:
            type: string
            default: all
        - name: minLiq
          in: query
          description: Minimum liquidity in USD
          required: false
          schema:
            type: integer
            default: 100
        - name: limit
          in: query
          description: Max results (1-50)
          required: false
          schema:
            type: integer
            default: 20
      x-agent-cost: 0.002
      responses:
        "200":
          description: New meme coins
          content:
            application/json:
              schema:
                type: object

  /api/meme/analyze:
    get:
      operationId: analyzeMemeCoin
      summary: Analyze a meme coin for rug risk
      description: "Deep analysis of any token: liquidity, volume, holder distribution, rug risk score. Input a token address."
      parameters:
        - name: address
          in: query
          description: "Token contract address"
          required: true
          schema:
            type: string
      x-agent-cost: 0.003
      responses:
        "200":
          description: Token analysis with rug risk score
          content:
            application/json:
              schema:
                type: object

  /api/top-gainers:
    get:
      operationId: getTopGainers
      summary: Top gainers (24h)
      description: "Coins with the highest 24h price increase"
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
        - name: vs
          in: query
          schema:
            type: string
            default: usd
      x-agent-cost: 0.002
      responses:
        "200":
          description: Top gainers

  /api/top-losers:
    get:
      operationId: getTopLosers
      summary: Top losers (24h)
      description: "Coins with the highest 24h price decrease"
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
        - name: vs
          in: query
          schema:
            type: string
            default: usd
      x-agent-cost: 0.002
      responses:
        "200":
          description: Top losers

  /api/defi/yields:
    get:
      operationId: getDefiYields
      summary: Best DeFi yields
      description: "Top yield opportunities across all DeFi protocols. Filter by chain, minimum APY."
      parameters:
        - name: minApy
          in: query
          schema:
            type: number
            default: 0
        - name: chain
          in: query
          schema:
            type: string
            default: all
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      x-agent-cost: 0.003
      responses:
        "200":
          description: Yield opportunities

  /api/defi/tvl:
    get:
      operationId: getDefiTvl
      summary: Protocol TVL rankings
      description: "Top DeFi protocols by Total Value Locked"
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 30
        - name: chain
          in: query
          schema:
            type: string
            default: all
      x-agent-cost: 0.003
      responses:
        "200":
          description: TVL rankings

  /api/defi/protocol/{slug}:
    get:
      operationId: getProtocolDetail
      summary: DeFi protocol details
      description: "Detailed info about a DeFi protocol: TVL, chains, category, description"
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      x-agent-cost: 0.003
      responses:
        "200":
          description: Protocol details

  /api/meme/trending:
    get:
      operationId: getTrendingMemeCoins
      summary: Trending meme coins
      description: "Highest volume new tokens on DEXes right now"
      parameters:
        - name: chain
          in: query
          schema:
            type: string
            default: all
        - name: limit
          in: query
          schema:
            type: integer
            default: 15
      x-agent-cost: 0.003
      responses:
        "200":
          description: Trending tokens

  /api/gas/all:
    get:
      operationId: getMultiChainGas
      summary: Gas prices across chains
      description: "Current gas prices for major blockchains"
      x-agent-cost: 0.002
      responses:
        "200":
          description: Multi-chain gas

  /api/categories:
    get:
      operationId: getCategories
      summary: Coin categories by market cap
      description: "All cryptocurrency categories ranked by market cap"
      x-agent-cost: 0.002
      responses:
        "200":
          description: Categories

  /api/summary:
    get:
      operationId: getMarketSummary
      summary: Market summary dashboard
      description: "One-call dashboard: BTC/ETH price, Fear & Greed, global market cap, top volume coins"
      x-agent-cost: 0.004
      responses:
        "200":
          description: Market summary