# CoinGraph

> Provable crypto data for AI agents: one call returns a sourced, timed answer about a token — never a trade.

Base URL: https://coingraph.ai/api/v1 · OpenAPI: https://coingraph.ai/api/v1/openapi.json · Reference: https://coingraph.ai/docs
Token ids are CoinGecko ids (cardano, chainlink, solana); symbols and contract addresses also work.
Every response: { object, id, as_of, data, sources }. Unmeasured values are "unassessed". State, history, market and inspect also return proof: { id, sha256, verify_url, status }, where sha256 = sha256(canonical({ as_of, data })). It shows this exact response existed at this time, not that it is correct; CoinGraph keeps the exact response for 30 days and the fingerprint for good, so keep the response to recompute it later. No key needed to start (60 requests/min).

## Discover (free)
- GET /tokens — the 100 tracked tokens; ?q= to search 21,000+ coins
- GET /status — health, freshness, coverage, prices, payment address

## Understand
- GET /state/{token} — everything known right now; ?sections=market,liquidity,derivatives,onchain,supply,security,context,signals,brief
- GET /history/{token} — series and events; ?since=ISO
- GET /market — the whole market; ?sections=overview,sectors,breadth,sentiment,flows,chains,venues,rankings,events,pulse
- GET /inspect/{chain}/{address} — who owns an address (eth, bsc, btc, sol, ada)

## Decide
- GET /evaluate/{token} — verdict proceed/caution/avoid per dimension, with reasons and sources
- POST /evaluate {token, size_usd?, policy?} — same, scored against your order size and rules
- GET /explain/{token} — latest brief (why it moved), every claim cited
- POST /explain {token, hours?} — run a fresh investigation (30–90 s)
- POST /ask {token, question | claim} — cited answer, or supported/contradicted/unknown

## Watch
- POST /monitor {tokens[], webhook_url, conditions?} — signed webhooks when signals fire, verdicts change or briefs are written

## Trust
- GET /record[/{token}] — public scorecard: every call we made and what happened next
- GET /verify/{id} — canonical object, sha256, the CoinGraph data feeds read, Chainlink CRE attestation (piloted on the CRE simulator; pending for new proofs). For data responses (st_, hs_, mk_, ad_): the response exactly as sent while stored (30 days; exact bytes at /verify/{id}/served), fingerprint, status, Merkle path and the batch's chain records

## Agents
Ready-made agents built on the data above. POST /agents/{id} with JSON input → { verdict, summary, result, reasons, run_id, verify_url }. GET /agents lists input schemas and examples.
- POST /agents/trade-gatekeeper — Trade Gatekeeper: The check every trade passes before it is placed. (ALLOW/REDUCE/BLOCK; 5 credits)
- POST /agents/wallet-guard — Wallet Guard: Checks a swap or a send before you sign it. (SAFE/WARN/STOP; 5 credits)
- POST /agents/due-diligence-analyst — Due Diligence Analyst: A full due-diligence memo on any token in one run. (A/B/C/D/F/UNRATED; 25 credits)
- POST /agents/portfolio-checkup — Portfolio Checkup: A health check for everything in a wallet, against your rules if you have them. (A/B/C/D/F; 25 credits)
- POST /agents/daily-market-brief — Daily Market Brief: The whole market in one readable page. (RISK_ON/RISK_OFF/NEUTRAL; 5 credits)

## MCP
Remote MCP server (Streamable HTTP): https://coingraph.ai/mcp — Claude Code: `claude mcp add --transport http coingraph https://coingraph.ai/mcp`
Tools: search_tokens, get_token_snapshot, get_token_timeline, check_token, get_token_brief, ask_about_token, watch_tokens, get_market_overview, lookup_address, get_track_record, get_proof, get_service_status, plus one run_<agent> tool per agent (e.g. run_trade_gatekeeper)
Prompts: pre_trade_check, wallet_safety_check, token_due_diligence

## Payments and access
Guide: https://coingraph.ai/docs/access. Developers sign in at https://coingraph.ai/signin and send an account key as Authorization: Bearer cg_live_… : paid calls spend credits (data 1, premium 5, pro 25; 500 free to start; plans and $10 top-ups at https://coingraph.ai/pricing). Agents can instead pay per call with x402 (no account). Companies hire the Coworker on Sokosumi (Masumi escrow). The MCP server at https://coingraph.ai/mcp signs users in with OAuth (or takes the same account key) and spends the same credits.
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.

CoinGraph never executes, custodies or advises. The caller decides.