CoinGraph Discover API

openapi: 3.2.0
info:
  title: CoinGraph Discover API
  version: 1.0.0
  summary: 'Provable crypto data for AI agents: market, on-chain, whale, contract and sanctions data in one call.'
  description: 'Humans read it, agents call it. Every response carries where the data came from (sources) and when it was true (as_of); anything unmeasured is "unassessed". CoinGraph never executes, custodies or advises — the caller decides.


    Phase: hackathon. Discover and Trust calls are free. Data calls (state, history, market) are free for 25 calls a day, then 1 credit. Premium calls (sized checks, fresh briefs, questions, address lookups, monitors, most agents) are 5 credits; Pro agents are 25. With an API key, calls spend credits; without one, paid calls answer 402 with x402 payment details.'
  contact:
    name: CoinGraph
    url: https://coingraph.ai
    email: support@coingraph.ai
  x-mcp-server: https://coingraph.ai/mcp
servers:
- url: https://coingraph.ai/api/v1
  description: Production
tags:
- name: Discover
  description: Find what CoinGraph covers and whether it is healthy. Free.
paths:
  /tokens:
    get:
      tags:
      - Discover
      operationId: tokens
      summary: List the 100 tokens we track
      description: Ids, symbols, contract addresses per chain, rank, price, changes, categories, open signals, latest headline. Use `q` to search 21,000+ coins by name, symbol or contract. Free.
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        example: chainlink
      responses:
        '200':
          description: The tracked universe
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: token_list
                  id:
                    type:
                    - string
                    - 'null'
                  as_of:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/TokenList'
                  sources:
                    type: array
                    items:
                      $ref: '#/components/schemas/Source'
                required:
                - object
                - as_of
                - data
                - sources
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /status:
    get:
      tags:
      - Discover
      operationId: status
      summary: Is CoinGraph healthy right now?
      description: Pipeline health, data freshness, coverage, prices and the payment address.
      responses:
        '200':
          description: Service status
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: service_status
                  id:
                    type:
                    - string
                    - 'null'
                  as_of:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/ServiceStatus'
                  sources:
                    type: array
                    items:
                      $ref: '#/components/schemas/Source'
                required:
                - object
                - as_of
                - data
                - sources
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TokenList:
      type: object
      additionalProperties: true
    ServiceStatus:
      type: object
      additionalProperties: true
    Source:
      type: object
      properties:
        provider:
          type: string
        endpoint:
          type: string
        as_of:
          type:
          - string
          - 'null'
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment (signed Cardano transaction, base64). Paid endpoints answer 402 with a PAYMENT-REQUIRED header describing the payment.
    apiKey:
      type: http
      scheme: bearer
      description: Account API key (cg_live_…) from https://coingraph.ai/account/keys. Paid calls spend credits (data 1, premium 5, pro 25; 1,000 free a month) instead of an x402 payment; responses carry x-credits-charged and x-credits-remaining. 401 invalid_key, 402 out_of_credits.
    partner:
      type: http
      scheme: bearer
      description: 'Design-partner key (cg_…) issued by hand: used instead of paying per call.'