Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: CoinGraph Understand 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: Understand
description: Everything CoinGraph knows, as data.
paths:
/state/{token}:
get:
tags:
- Understand
operationId: state
summary: Everything we know about a token right now
description: 'Sections: identity, market, liquidity, derivatives, onchain, supply, security (contract risk via GoPlus), context, signals, brief. Each section carries its own sources and as_of. **Data tier:** 25 free calls a day, then 1 credits per call with an API key, or pay per call with x402 (402 Payment Required → pay → retry with PAYMENT-SIGNATURE).'
parameters:
- name: token
in: path
required: true
description: Token id (coingecko id), symbol or contract address.
schema:
type: string
example: chainlink
- name: sections
in: query
required: false
description: 'Comma-separated list of sections to return. Default: all. Valid: identity, market, liquidity, derivatives, onchain, supply, security, context, signals, brief.'
schema:
type: string
- name: detail
in: query
required: false
description: full adds the top 10 bids and asks of the primary order book to liquidity.
schema:
type: string
enum:
- full
responses:
'200':
description: Unified token state
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: state
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/State'
sources:
type: array
items:
$ref: '#/components/schemas/Source'
proof:
$ref: '#/components/schemas/ResponseProof'
required:
- object
- as_of
- data
- sources
- proof
'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'
security:
- apiKey: []
- partner: []
- x402: []
/history/{token}:
get:
tags:
- Understand
operationId: history
summary: What happened to a token over time
description: 'Series (price, candles, open interest, funding, long/short, exchange net flow, reserves, TVL) and events (large transfers, liquidations, signals, headlines, briefs). Default window: 24h events, 14 days series. Series are downsampled to `resolution` buckets (last value per bucket per venue). Limits: `since` reaches back 90 days at most (earlier values are clamped and reported in `window.since_clamped_to`), `raw` is served for windows up to 48 hours, and every series stays under 2,000 points per venue by widening the bucket (`resolution` and `notes` in the answer say so). **Data tier:** 25 free calls a day, then 1 credits per call with an API key, or pay per call with x402 (402 Payment Required → pay → retry with PAYMENT-SIGNATURE).'
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: series
in: query
required: false
description: Comma list of series to include.
schema:
type: string
- name: resolution
in: query
required: false
description: 'Bucket width: 15m, 1h, 6h, raw (every row) or auto (15m up to 2 days, 1h up to 30 days, 6h beyond).'
schema:
type: string
enum:
- auto
- 15m
- 1h
- 6h
- raw
default: auto
- name: venue
in: query
required: false
description: 'Exchange for candles, e.g. okx. Default: the primary venue.'
schema:
type: string
- name: market_type
in: query
required: false
description: 'Market for candles: spot or swap (perpetuals).'
schema:
type: string
enum:
- spot
- swap
default: spot
- name: by
in: query
required: false
description: chain splits exchange_net_flow by chain.
schema:
type: string
enum:
- chain
responses:
'200':
description: Series and events
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: history
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/History'
sources:
type: array
items:
$ref: '#/components/schemas/Source'
proof:
$ref: '#/components/schemas/ResponseProof'
required:
- object
- as_of
- data
- sources
- proof
'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'
security:
- apiKey: []
- partner: []
- x402: []
/market:
get:
tags:
- Understand
operationId: market
summary: The whole market at a glance
description: 'Sections: overview, sectors, breadth, sentiment, flows, chains, venues, rankings, events, pulse. **Data tier:** 25 free calls a day, then 1 credits per call with an API key, or pay per call with x402 (402 Payment Required → pay → retry with PAYMENT-SIGNATURE).'
parameters:
- name: sections
in: query
required: false
description: 'Comma-separated list of sections to return. Default: all. Valid: overview, sectors, breadth, sentiment, flows, chains, venues, rankings, events, pulse.'
schema:
type: string
responses:
'200':
description: Market-wide state
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: market
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/MarketState'
sources:
type: array
items:
$ref: '#/components/schemas/Source'
proof:
$ref: '#/components/schemas/ResponseProof'
required:
- object
- as_of
- data
- sources
- proof
'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'
security:
- apiKey: []
- partner: []
- x402: []
/inspect/{chain}/{address}:
get:
tags:
- Understand
operationId: inspect
summary: Who owns an address?
description: Label (exchange, contract, burn or unlabelled), type, balances, transaction count, recent large moves. Fetched live from the chain through NOWNodes. **Premium tier:** 10 free calls a day, then 5 credits per call with an API key, or pay per call with x402 (402 Payment Required → pay → retry with PAYMENT-SIGNATURE).
parameters:
- name: chain
in: path
required: true
schema:
type: string
enum:
- eth
- bsc
- btc
- sol
- ada
- name: address
in: path
required: true
schema:
type: string
responses:
'200':
description: Address profile
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: address_profile
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AddressProfile'
sources:
type: array
items:
$ref: '#/components/schemas/Source'
proof:
$ref: '#/components/schemas/ResponseProof'
required:
- object
- as_of
- data
- sources
- proof
'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'
security:
- apiKey: []
- partner: []
- x402: []
components:
schemas:
AddressProfile:
type: object
additionalProperties: true
ResponseProof:
type: object
description: 'Makes this response provable: it shows this exact response existed at this time, not that the answer is correct. CoinGraph keeps the exact response for 30 days (GET /verify/{id} returns it) and the fingerprint for good, so keep the response to recompute it later.'
properties:
id:
type: string
description: Same as the envelope id. Pass it to GET /verify/{id}.
sha256:
type: string
description: 'sha256(canonical({ as_of, data })): only these two fields of the response, as you received them. Canonical: keys sorted at every level, no whitespace, written as JavaScript''s JSON.stringify writes it.'
verify_url:
type: string
format: uri
status:
type: string
const: queued
description: Fixed when the response is issued. GET /verify/{id} gives the current status.
required:
- id
- sha256
- verify_url
- status
History:
type: object
properties:
token:
type: object
window:
type: object
resolution:
type: string
enum:
- 15m
- 1h
- 6h
- raw
description: The bucket actually used.
resolution_requested:
type: string
enum:
- auto
- 15m
- 1h
- 6h
- raw
notes:
type: array
items:
type: string
description: Present when a parameter was clamped (since, resolution).
series:
type: object
events:
type: object
Source:
type: object
properties:
provider:
type: string
endpoint:
type: string
as_of:
type:
- string
- 'null'
format: date-time
State:
type: object
description: token + one key per section; each section has as_of and sources; unmeasured values are the string "unassessed".
additionalProperties: true
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
MarketState:
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.'