CoinGraph Trust API

openapi: 3.2.0
info:
  title: CoinGraph Trust 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: Trust
  description: Check CoinGraph's record and prove what you were told.
paths:
  /record:
    get:
      tags:
      - Trust
      operationId: record
      summary: Our public scorecard
      description: Every evaluation, signal and brief issued and what the price did 1h/24h/7d later. Checks are measured by how often a 5%+ drop followed each verdict within 24h (calibration.by_verdict); signals are listed, not graded; briefs are graded on their stated direction. `since` reaches back 30 days at most; earlier values are clamped and reported in `since_clamped_to`.
      parameters:
      - name: since
        in: query
        required: false
        description: ISO-8601 time. Limits events (and series) to after this time.
        schema:
          type: string
          format: date-time
      - name: kind
        in: query
        required: false
        schema:
          type: string
          enum:
          - evaluation
          - signal
          - brief
      responses:
        '200':
          description: Record
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: record
                  id:
                    type:
                    - string
                    - 'null'
                  as_of:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/Record'
                  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'
  /record/{token}:
    get:
      tags:
      - Trust
      operationId: recordToken
      summary: The scorecard for one token
      parameters:
      - name: token
        in: path
        required: true
        description: Token id (coingecko id), symbol or contract address.
        schema:
          type: string
        example: chainlink
      - name: since
        in: query
        required: false
        description: ISO-8601 time. Limits events (and series) to after this time.
        schema:
          type: string
          format: date-time
      - name: kind
        in: query
        required: false
        schema:
          type: string
          enum:
          - evaluation
          - signal
          - brief
      responses:
        '200':
          description: Record
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: record
                  id:
                    type:
                    - string
                    - 'null'
                  as_of:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/Record'
                  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'
  /verify/{id}:
    get:
      tags:
      - Trust
      operationId: verify
      summary: Proof of what you were told
      description: 'The canonical object, its sha256, the Chainlink CRE attestation (pending until the workflow has reached it) and the source calls behind it. For a data response (st_, hs_, mk_, ad_) CoinGraph stores no object: `object` is null, and the answer gives `sha256`, `status` (queued or recorded), `merkle_root`, `merkle_path`, `recomputation` and the batch''s `base_anchor` and `cardano_anchor`. Recompute sha256 from the response you kept. A match shows that exact response existed at that time, not that the answer is correct. Base is live; recording on Cardano is being added.'
      parameters:
      - name: id
        in: path
        required: true
        description: eval_…, ans_…, run_…, a brief number, or a data response's st_…, hs_…, mk_…, ad_…
        schema:
          type: string
      responses:
        '200':
          description: Proof
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: proof
                  id:
                    type:
                    - string
                    - 'null'
                  as_of:
                    type: string
                    format: date-time
                  data:
                    $ref: '#/components/schemas/Proof'
                  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:
    Record:
      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
    Proof:
      type: object
      additionalProperties: true
  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.'