Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: CoinGraph Agents 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: Agents
description: 5 ready-made agents built on the data above. Each returns a verdict, a plain summary, sourced reasons and a proof id.
paths:
/agents:
get:
tags:
- Agents
operationId: agents
summary: List the agents
description: Every agent with its input schema, verdicts, price and an example input.
responses:
'200':
description: Agents
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: agent_list
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AgentList'
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'
/agents/{id}:
get:
tags:
- Agents
operationId: agent
summary: One agent's card
parameters:
- name: id
in: path
required: true
schema:
type: string
enum:
- trade-gatekeeper
- wallet-guard
- due-diligence-analyst
- portfolio-checkup
- daily-market-brief
responses:
'200':
description: Agent
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: agent
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AgentCard'
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'
/agents/trade-gatekeeper:
post:
tags:
- Agents
operationId: run_trade_gatekeeper
summary: 'Trade Gatekeeper: The check every trade passes before it is placed'
description: 'Give it a token, an order size and optionally your rules. It runs the CoinGraph check, measures the real on-chain price impact of your size (DEX aggregator quote) against order-book depth and daily volume, reads leverage, onchain flows and contract risk, and returns ALLOW, REDUCE (with the largest safe size) or BLOCK, with every reason sourced. Verdicts: ALLOW / REDUCE / BLOCK. Price: 5 credits with an API key, or pay per run with x402 (premium).'
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
token:
type: string
minLength: 1
maxLength: 100
description: 'Token: CoinGecko id (chainlink), symbol (LINK) or contract address'
size_usd:
default: 10000
description: Order size in USD
type: number
exclusiveMinimum: 0
maximum: 10000000000
side:
default: buy
type: string
enum:
- buy
- sell
max_impact_pct:
description: Largest acceptable price impact; default 1% for top-20 tokens, 2% otherwise
type: number
exclusiveMinimum: 0
maximum: 50
policy:
type: object
properties:
min_depth_usd:
type: number
max_top10_holder_pct:
type: number
max_funding_pct:
type: number
max_exchange_inflow_usd:
type: number
allow_mint_authority:
type: boolean
additionalProperties: false
required:
- token
- size_usd
- side
additionalProperties: false
example:
token: solana
size_usd: 5000
side: buy
responses:
'201':
description: Agent run
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: agent_run
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AgentRun'
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'
'402':
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: []
/agents/wallet-guard:
post:
tags:
- Agents
operationId: run_wallet_guard
summary: 'Wallet Guard: Checks a swap or a send before you sign it'
description: 'Before a swap, it checks the token: contract risks (honeypot, taxes, mint/freeze/blacklist powers), the real price impact of the amount, holder concentration and market conditions. Before a send, it checks the recipient live on the chain: OFAC sanctions, scam and phishing flags, burn addresses, brand-new wallets and lookalikes of known addresses (address poisoning). Returns SAFE, WARN or STOP with one plain sentence for the user. Verdicts: SAFE / WARN / STOP. Price: 5 credits with an API key, or pay per run with x402 (premium).'
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
token:
description: The token being swapped into or sent
type: string
minLength: 1
maxLength: 100
amount_usd:
description: Amount in USD
type: number
exclusiveMinimum: 0
maximum: 10000000000
to_address:
description: Recipient address (for a send)
type: string
minLength: 20
maxLength: 130
chain:
description: Chain of the recipient address
type: string
enum:
- eth
- bsc
- btc
- sol
- ada
additionalProperties: false
example:
token: chainlink
amount_usd: 5000
to_address: '0x28c6c06298d514db089934071355e5743bf21d60'
chain: eth
responses:
'201':
description: Agent run
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: agent_run
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AgentRun'
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'
'402':
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: []
/agents/due-diligence-analyst:
post:
tags:
- Agents
operationId: run_due_diligence_analyst
summary: 'Due Diligence Analyst: A full due-diligence memo on any token in one run'
description: 'Structured like exchange listing reviews (Coinbase, Kraken) and lending-risk onboarding (Aave, Gauntlet, LlamaRisk): liquidity and markets, supply and holder concentration, contract and admin powers, onchain activity, derivatives, development and community, and CoinGraph''s own track record on the token. Each measured section gets a grade with its evidence, plus red flags, strengths, an overall grade and the coverage behind it. A section that cannot apply or has no data is marked as such and never scored. Verdicts: A / B / C / D / F / UNRATED. Price: 25 credits with an API key, or pay per run with x402 (pro).'
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
token:
type: string
minLength: 1
maxLength: 100
description: 'Token: CoinGecko id (chainlink), symbol (LINK) or contract address'
required:
- token
additionalProperties: false
example:
token: cardano
responses:
'201':
description: Agent run
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: agent_run
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AgentRun'
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'
'402':
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: []
/agents/portfolio-checkup:
post:
tags:
- Agents
operationId: run_portfolio_checkup
summary: 'Portfolio Checkup: A health check for everything in a wallet, against your…'
description: 'Reads a wallet''s holdings live from the chain, runs the CoinGraph check on each tracked token, and measures concentration, how many days each position would take to exit at normal volume, and contract risks. Returns a health grade from A to F with fixes ranked by impact. Give it a policy (minimum liquidity, maximum holder concentration, maximum funding, maximum exchange inflow, mint authority, maximum exit slippage, maximum share of market cap) and it also tests every holding against every rule — exit slippage with a live DEX quote for the actual position — and flags each holding COMPLIANT or BREACH, with an overall flag and a proof id per holding, ready to attach to a governance vote. Verdicts: A / B / C / D / F. Price: 25 credits with an API key, or pay per run with x402 (pro).'
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
chain:
type: string
enum:
- eth
- bsc
- btc
- sol
- ada
description: 'Chain: eth (Ethereum), bsc (BNB Chain), btc (Bitcoin), sol (Solana), ada (Cardano)'
address:
type: string
minLength: 20
maxLength: 130
policy:
description: 'Optional: the rules every holding must pass; each is reported pass, fail or unknown per holding, with COMPLIANT / BREACH / INCOMPLETE per holding and overall'
type: object
properties:
min_depth_usd:
description: Minimum liquidity within 2% of the price, in USD
type: number
max_top10_holder_pct:
description: Maximum share of supply held by the top 10 holders, in percent
type: number
max_funding_pct:
description: Maximum futures funding rate per 8 hours, in percent
type: number
max_exchange_inflow_usd:
description: Maximum net USD moved onto exchanges in 24 hours
type: number
allow_mint_authority:
description: Whether a contract that can still mint or freeze is acceptable
type: boolean
max_exit_slippage_pct:
description: Largest acceptable price impact to sell the whole position
type: number
max_position_pct_of_market_cap:
description: Largest acceptable position as a share of the token's market cap, in percent
type: number
additionalProperties: false
required:
- chain
- address
additionalProperties: false
example:
chain: eth
address: '0x9fc3da866e7df3a1c57ade1a97c9f00a70f010c8'
responses:
'201':
description: Agent run
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: agent_run
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AgentRun'
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'
'402':
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: []
/agents/daily-market-brief:
post:
tags:
- Agents
operationId: run_daily_market_brief
summary: 'Daily Market Brief: The whole market in one readable page'
description: 'Opens with CoinGraph''s own record from the last 24 hours (what followed each check), then the market regime (risk-on or risk-off, breadth, leverage, Fear & Greed), what changed ranked by importance, stablecoin and exchange flows, the most crowded futures markets, top movers and headlines — and, if you pass your holdings, a line on each. Returned as Markdown and JSON. Verdicts: RISK_ON / RISK_OFF / NEUTRAL. Price: 5 credits with an API key, or pay per run with x402 (premium).'
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
holdings:
description: Optional tokens you hold, for a personal section
maxItems: 20
type: array
items:
type: string
minLength: 1
maxLength: 100
description: 'Token: CoinGecko id (chainlink), symbol (LINK) or contract address'
additionalProperties: false
example:
holdings:
- cardano
- chainlink
- solana
responses:
'201':
description: Agent run
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: agent_run
id:
type:
- string
- 'null'
as_of:
type: string
format: date-time
data:
$ref: '#/components/schemas/AgentRun'
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'
'402':
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:
AgentRun:
type: object
properties:
run_id:
type: string
agent:
type: string
verdict:
type: string
summary:
type: string
result:
type: object
reasons:
type: array
warnings:
type: array
hash:
type: string
verify_url:
type: string
Source:
type: object
properties:
provider:
type: string
endpoint:
type: string
as_of:
type:
- string
- 'null'
format: date-time
AgentCard:
type: object
additionalProperties: true
AgentList:
type: object
additionalProperties: true
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.'