# On-chain Forensics API > Decision-grade on-chain forensics for AI agents. Ask the question you are actually asking: should I touch this token or wallet? Pay per call in USDC on Base via x402, no API keys, no signup. Verdict returns a letter grade and a one-line roast, so a caller gets a call to make, not a dashboard to read. ## Published grades, one page per token (free to read) 500 tokens on Ethereum and Base are graded in public: score 0-100 on transfer activity across the last 500 blocks, a letter grade A-F, the band, and the percentile against the chain median. - Directory, sortable and filterable: https://onchainforensics.dev/t/ - Ethereum: https://onchainforensics.dev/t/ethereum/ - Base: https://onchainforensics.dev/t/base/ - One token, as a page: https://onchainforensics.dev/t/ethereum/-.html e.g. https://onchainforensics.dev/t/base/usdc-833589fc.html Read the directory to choose a token worth paying to check, then call verdict for the live number inside the last 500 blocks. The pages carry the measured timestamp so a stale grade is visible. ## License the feed (wallets, bots, terminals) If your product has humans in it, do not put a payment prompt in front of them. Bulk snapshots, batch calls and a white-label endpoint: https://onchainforensics.dev/licensing.html Pilot $100 for 14 days, then $250 or $1,000 a month, paid in USDC on Base. ## Start here (cheapest path to a decision) 1. verdict, $0.02, the core call. Ends in a letter grade A to F, risk flags and a one-line roast. GET /functions/forensicsApi?endpoint=verdict&address=0x&chain=base|ethereum 2. settlesafe, $0.02, adds the settle question: is this token safe to accept right now, or is it paused, fee-trapped or clawback-capable. GET /functions/forensicsApi?endpoint=settlesafe&address=0x&chain=base|ethereum 3. mints, $0.02, answers who is adding supply and how much in the window. GET /functions/forensicsMints?token=0x&chain=base|ethereum Three calls, $0.06, and you can decide whether to trade, settle against it, or walk away. Every verdict payload already returns the next two calls with ready-to-fire URLs, so an agent never has to guess what to buy next. ## The cheap tier: $0.001 cached verdicts If you need a verdict in-path, on every trade, or thousands of times an hour, use the cached feed instead of the live scan: - `GET https://solene-fa2010da.base44.app/functions/verdictFast?address=0x&chain=base|ethereum` at **$0.001** - Same letter grade A to F, roast, risk flags and next_calls as the $0.02 live verdict. Precomputed continuously in the background, answered from a key lookup instead of a 1 to 14 second chain scan. - See exactly which tokens are in the feed for free: `?list=1` returns the whole cache with grades and timestamps. - Coverage grows every ten minutes as the builder works through the token universe. If your token is not there yet, the call costs you nothing: the call returns `cache_miss: true` with a pointer to the live route, and no payment settles. Use the cached route for volume and in-path decisions; use `/functions/forensicsApi?endpoint=verdict` ($0.02) when you need the current block. ## Try it free first Add trial=1 to verdict, settlesafe, token, wallet or any single-question read for free daily calls per IP. No payment header needed, no signup. If a free call answers your question, stop there. ## See real responses before paying Six verbatim responses captured from free trial calls, including the full grade range: USDC on Base grades A (RED_HOT), DEGEN grades D (THIN), BRETT grades F (SUSPICIOUS_THIN), plus a tokenized-equity settle screen, a wallet risk read and a mints micro read. - Rendered with grades and roasts: https://onchainforensics.dev/samples.html - Raw JSON, one file per call: https://onchainforensics.dev/openapi-samples/verdict-usdc-base.json, .../verdict-degen-base.json, .../verdict-brett-base.json, .../settlesafe-btsla.json, .../walletrisk-burn-base.json, .../mints-usdc-base.json Nothing is mocked. If a sample answers your question, you already know what the paid call looks like. ## Why this is different - Every payload states data_quality COMPLETE, PARTIAL or UNAVAILABLE. An unreadable chain is never reported as a zero, and an unattributable address is never reported as a guess. - Reads come from a dedicated provider endpoint (Alchemy) that this service controls, with public gateways only as fallback, so a rate-limited shared node cannot turn a real balance into an empty read. - No LLM in the decision path. Grades, tiers and roasts are deterministic functions of on-chain reads, so the same block gives the same answer. ## Routes and prices (all x402 v2, exact scheme, eip155:8453) Base URLs: - Gateway (directory + routing): https://solene-fa2010da.base44.app/functions/forensicsGateway - Main API: https://solene-fa2010da.base44.app/functions/forensicsApi Decision routes: - info, FREE. Service card, endpoint catalog, pricing. - verdict, $0.02. Token verdict card: verdict tier (RED_HOT/HEAVY_FIRE/ACTIVE/THIN/SUSPICIOUS_THIN/DORMANT...), activity score 0-100, transfers, unique wallets, mints/burns, concentration, flags, plain_take, letter grade, roast, next_calls. - settlesafe, $0.02. Pre-trade trust screen for tokenized equities and RWAs: counterparty plus token screen (canonical registry, freeze and clawback flags), settle-risk verdict (KNOWN_CANONICAL and friends). - trust, $0.02. One word back: TRUSTED, CAUTION, HIGH_RISK, UNVERIFIABLE or NOT_APPLICABLE, with reason codes and which checks actually ran. - deployer, $0.05. Who launched the contract and from which wallet, plus deployer wallet age, tx count and an OFAC screen. On Base it returns LAUNCH_WINDOW_ONLY with a bracketed window and data_quality PARTIAL rather than guessing. - token, $0.05. Full token profile: supply, holder concentration, top transfers, mint and burn history, whale moves. - wallet, $0.05. Wallet trust screen: counterparty flows, contract interaction risk, trust tier. - memo, $0.25 ($0.35 with counterparty screen). Composed due-diligence memo: multi-source verdict plus narrative risk assessment. - canton, $0.05. Canton Network emission and burn-mint snapshot metrics. - linea, $0.05. Linea burn-vault stats. Single-question micro reads, $0.01 to $0.02: supply, activity, holders, contract owner, pause state, registry membership, 24h mints, 24h burns, wallet age, wallet funding origin, wallet flows, wallet risk. Derivatives and equity issuance, $0.05: perp funding, open interest, option skew, tokenized-equity issuance. All 33 routes with typed schemas: https://leohoudinisanders-byte.github.io/onchain-forensics/openapi.json Chains: ERC-20s on Base and Ethereum (address plus chain params); Robinhood Chain including its 203 stock tokens; XRPL classic addresses (chain=xrp, issuer plus currency or a token alias); Solana SPL mints; Canton Network via verified entity snapshots. Tokenized-equity and RWA aliases (19, all verified on-chain): btsla bcspx bcoin bnvda aapl nvda buidl usdy ousg ustb usyc ondo qnt xlm edel rlusd gatehub-usd bitstamp-usd bitstamp-eur. ## How to pay Send any request, receive HTTP 402 with x402 v2 payment requirements (accepts[]), sign the EIP-3009 authorization with your wallet, retry with the X-PAYMENT header. Settlement on Base mainnet in USDC. Facilitator chain: CDP (Coinbase) primary, Roundhouse and PayAI fallback. ## MCP server (Claude, ChatGPT, any MCP client) - Endpoint: https://solene-fa2010da.base44.app/functions/forensicsMcp (streamable HTTP, JSON-RPC 2.0) - Tools: forensics_info (free), token_verdict ($0.02), settle_safe ($0.02), wallet_screen ($0.05), token_profile ($0.05), diligence_memo ($0.25 / $0.35 with counterparty) - Same x402 pay-per-call: a paid tools/call returns HTTP 402 with PAYMENT-REQUIRED until paid, then sign and retry with X-PAYMENT. - Also indexed in the Coinbase x402 Bazaar (type: mcp, transport: streamable-http). ## Links - Landing: https://leohoudinisanders-byte.github.io/onchain-forensics/ - OpenAPI 3.1 spec, 33 routes enriched with per-route tags and parameter examples: https://leohoudinisanders-byte.github.io/onchain-forensics/openapi.json - Sample responses: https://leohoudinisanders-byte.github.io/onchain-forensics/samples.html - Provider credibility: https://leohoudinisanders-byte.github.io/onchain-forensics/#provider - Also from this operator: Canton Swap Broker (OneSwap / Canton DEX x402 wrapper), https://leohoudinisanders-byte.github.io/canton-swap-broker/ ## Plugins (one command each, verified) - Demo + plugins: `npx -y github:leohoudinisanders-byte/forensics-agent-demo` (runs one live call, then prints the install lines) - MCP server: `npx -y github:leohoudinisanders-byte/forensics-mcp` (6 tools: verdict, mints, settlesafe, token profile, wallet profile, catalog) - elizaOS: `plugins/elizaos` in the demo repo - actions TOKEN_VERDICT and SETTLE_SAFE_CHECK - Coinbase AgentKit: `plugins/agentkit` in the demo repo - actions token_verdict and settlesafe_check Each plugin is dependency-free and calls the same HTTP API, so it works before you wire an x402 signer: with one, a call settles at $0.02; without one, the action returns the decoded challenge (price, payTo, network) instead of throwing.