API & MCP

Wallet Reputation API

The Wallet Reputation API lets exchanges, DeFi protocols, compliance teams and AI agents query a wallet's risk score, entity attribution and sanctions status programmatically. It reads ChainHint's own database of 54M+ labeled addresses, so it answers in milliseconds and is designed for real-time screening at deposit, withdrawal or payment time.

Free tier — no key, no signup

Call the endpoint with no credentials and you get 3 checks per IP per 24 hours. The response carries "tier": "free" and standardX-RateLimit-Limit / Remaining / Reset headers.

bash

curl "https://kjiwfwymnuzxriokhcjk.supabase.co/functions/v1/wallet-reputation?address=0x47666fab8bd0ac7003bce3f5c3585383f09486e2&chain=ethereum"

API key — 10,000 requests per day

Agency plan keys start with ch_live_ and are created in Settings → API Keys (up to 5 per account). Pass the key as a Bearer token or in X-Api-Key.

bash

curl "https://kjiwfwymnuzxriokhcjk.supabase.co/functions/v1/wallet-reputation?address=0x47666fab8bd0ac7003bce3f5c3585383f09486e2&chain=ethereum" \
  -H "Authorization: Bearer ch_live_YOUR_KEY"

Response

json

{
  "address": "0x47666fab8bd0ac7003bce3f5c3585383f09486e2",
  "chain": "ethereum",
  "risk_score": 85,
  "risk_level": "critical",
  "category": "hacker",
  "entity": {
    "name": "Bybit Hack Exploiter",
    "category": "hacker",
    "subcategory": null,
    "verified": false
  },
  "labels": ["Hacker/Exploiter", "Bybit Hack Exploiter"],
  "sanctions": { "hit": false },
  "restricted_assets": [],
  "agent": null,
  "is_contract": false,
  "found_in_db": true,
  "sources": ["chainhint:manual"],
  "checked_at": "2026-09-02T16:20:00.000Z",
  "tier": "free"
}

risk_level is one of clean · low · medium · high · critical · sanctioned.restricted_assets lists crypto-assets the wallet holds that are themselves prohibited (EU Annex LIII — A7A5), matched by contract and valued at par, each with a summary such as “holds EU-restricted asset A7A5 (Reg. (EU) 2025/2033 Art. 5ba)”; [] = checked, none; null = the chain could not be read. A holding is a property of the asset, never a sanctions hit on the holder. agent is the agent-infrastructure overlay: { is_agent, kind, framework, label, summary, source_url } when the address is in ChainHint's registry of known autonomous-agent infrastructure — kind is one of launchpad · factory · router · facilitator · known_agent (agent-token launchpads, deployer factories, routers, payment facilitators, known agent wallets; is_agent is true only for known_agent) — else null. It is a registry fact you can check against the named contract at source_url, not a behavioural classification, and it does not move risk_score. When the free quota is used up, an autonomous agent can pay per call via x402: the endpoint answers 402 Payment Required with the terms — $0.10 USDC on Base — the agent re-requests with a signed X-PAYMENT header (EIP-3009), the payment is settled through a facilitator and the check runs. One payment, one call, no signup. Without a payment it falls back to 429 with anupgrade link and reset_at. Full reference, error shapes and Python / Node examples: WALLET_REPUTATION_API.md.

Access	Limit	Who
No key	3 checks / IP / 24h	Anyone — try it, wire it into an agent
Pay-per-call (x402)	$0.10 USDC / call on Base, no signup	AI agents past the free tier
Agency key	10,000 / day per key, 100 / min burst	Exchanges, protocols, compliance teams
Enterprise	Custom	Contact us

MCP Server

chainhint-mcp is an MCP (Model Context Protocol) server that gives Claude Desktop, Claude Code, Cursor or any MCP-compatible agent three ChainHint tools. It runs straight from npm and needs no API key to start — every tool has a free allowance.

Available Tools

Tool	What it returns	Without a key	With an Agency key
check_wallet_risk	Risk score & level, entity, labels, sanctions hit — fast, database-only	3 / day	10,000 / day
lookup_address	Deep report: risk factors, GoPlus flags, counterparty exposure by category, balance, tx count	10 / day	100 / hour
get_trace_status	Public hack incident: loss, hops, where funds went (exchange / mixer / bridge / defi), attacker exposure	Unlimited	Unlimited

Setup (Claude Desktop / Cursor / Claude Code)

json

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
// Cursor: .cursor/mcp.json       Claude Code: claude mcp add chainhint -- npx -y chainhint-mcp
{
  "mcpServers": {
    "chainhint": {
      "command": "npx",
      "args": ["-y", "chainhint-mcp"]
    }
  }
}

To lift the free limits add "env": { "CHAINHINT_API_KEY": "ch_live_…" } to the entry. Get a key from Settings → API Keys (Agency plan).

What the agent sees

Ask "Is 0x47666fab… a known hacker?" and the model calls check_wallet_risk:

bash

## Wallet Risk Report: 0x47666f...9486e2
**Chain:** ethereum
**Risk Score:** 85/100 — **CRITICAL**
**Entity:** Bybit Hack Exploiter (hacker)
**Labels:** Hacker/Exploiter, Bybit Hack Exploiter
**In ChainHint DB:** yes (sources: chainhint:manual)
Free tier: 2 of 3 checks left today — set CHAINHINT_API_KEY for 10,000/day.

Ask "Where did the CoinEx hack funds go?" and it calls get_trace_status:

bash

## Fund Trace: CoinEx
**Status:** TRACED · **Loss:** $55.00M · **Date:** 2023-09-12
### Trace Graph
**Hops traced:** 4 · **Addresses:** 124 · **Transfers:** 244
### Where the funds went (122 endpoints, $12.32M tracked)
- **unknown**: $10.21M (82.9%) across 46 address(es) — Forta: Attacker, Cult DAO
- **defi**: $2.09M (17.0%) across 72 address(es) — uniswap, Uniswap V3, Uniswap V2
- **exchange**: $19.9K (0.2%) across 4 address(es) — KuCoin deposit, OKX deposit
🔗 View full trace: https://chainhint.com/incident/9a1964d8-…

Installation

No install step — the config above runs the server from npm via npx. Source: github.com/seomarlboro/chainhint-mcp (MIT). To build locally:

bash

git clone https://github.com/seomarlboro/chainhint-mcp
cd chainhint-mcp
npm install && npm run build