chainhint-mcp 1.3.2 → 1.3.4

package/README.md

@@ -6,7 +6,7 @@ Crypto risk intelligence for Claude Desktop, Cursor, and any MCP-compatible AI.
 
 | Tool | Description | Limit |
 |------|-------------|-------|
-| `check_wallet_risk` | Fast risk score, entity, labels, sanctions hit (54M+ labeled addresses) | **3 / day** free · 10,000 / day with key |
+| `check_wallet_risk` | Fast risk score, entity, labels, sanctions hit — 45M+ attributed addresses across 12 chains, including 485K+ linked to illicit activity and 1,000+ sanctioned addresses across 5 authorities (OFAC, EU, AU, JP, FR) | **3 / day** free · 10,000 / day with key |
 | `lookup_address` | Deep address report — entity, risk factors, GoPlus flags, counterparty exposure, balance | **10 / day** free · 100 / hour with key |
 | `get_trace_status` | Fund-trace summary for a public hack incident — hops, endpoints by type (exchange/mixer/bridge/defi), exposure | Unlimited |
 
@@ -88,6 +88,14 @@ Free tier: 2 of 3 checks left today — set CHAINHINT_API_KEY (Agency plan, http
 
 When the address is in ChainHint's agent-infrastructure registry (agent-token launchpads, deployer factories, routers, payment facilitators, known agent wallets), the report adds an `🤖` line, e.g. *Known agent infrastructure: Virtuals launchpad* — a registry fact you can verify at its source, not a behavioural classification and not part of the risk score.
 
+Evidence and entity lines say what the finding is, never more:
+
+- `⛔ Sanctioned` only for a sanctions designation; an issuer freeze, a law-enforcement attribution, a seizure order or a blocklist each says *Not a sanctions designation.*
+- A freeze of the tokens held by a token's own contract (Tether blacklisted the USDT held by the USDT contract) prints *Tether blacklisted tokens held by this contract* — it carries no risk weight and is not a "Frozen by issuer" verdict.
+- An entity whose attribution is unconfirmed is printed as a candidate (*⚠️ Attribution unconfirmed*) and a venue that no longer operates is marked *Venue closed* or *Bankrupt*.
+
+Addresses: EVM `0x…`, Bitcoin, Solana, TRON and TON — for TON any mainnet form works (friendly `EQ…`/`UQ…`/`Ef…`/`Uf…` or raw `0:<hex>`); testnet `kQ…`/`0Q…` is not covered.
+
 ## Development (no build step)
 
 ```bash

package/dist/address.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Address input handling — pure functions, tested in test/address.test.mjs.
+ *
+ * The MCP does not validate addresses: the ChainHint API does (400 with a
+ * format hint) and resolves every spelling of an address to its stored form
+ * (main repo: backend/supabase/functions/_shared/address-canon.ts). The tools
+ * only trim and lower-case EVM hex. Anything else is passed exactly as typed:
+ * base58 chains (BTC/TRON/SOL) are case-sensitive, and TON friendly addresses
+ * (EQ…/UQ…/Ef…/Uf…) carry a checksum over their case.
+ */
+/** EVM → lower case; every other chain's address is kept as typed (trimmed). */
+export declare function normalizeAddr(addr: string): string;
+/**
+ * Shape of a TON address, no checksum: "raw" (0:/-1: + 64 hex), "friendly"
+ * (48-char mainnet EQ/UQ/Ef/Uf), "testnet" (kQ/0Q/kf/0f — ChainHint does not
+ * cover testnet), or null. Informational only; the API decides validity.
+ */
+export declare function tonAddressForm(addr: string): "raw" | "friendly" | "testnet" | null;
+/** Tool parameter text: which address spellings the tools accept. */
+export declare const ADDRESS_FORMS = "EVM 0x\u2026, Bitcoin (1\u2026/3\u2026/bc1\u2026), Solana, TRON (T\u2026), or TON \u2014 mainnet friendly EQ\u2026/UQ\u2026/Ef\u2026/Uf\u2026 or raw 0:<hex>/-1:<hex>, any form finds the same address (testnet kQ\u2026/0Q\u2026 is not covered)";

package/dist/address.js

@@ -0,0 +1,34 @@
+/**
+ * Address input handling — pure functions, tested in test/address.test.mjs.
+ *
+ * The MCP does not validate addresses: the ChainHint API does (400 with a
+ * format hint) and resolves every spelling of an address to its stored form
+ * (main repo: backend/supabase/functions/_shared/address-canon.ts). The tools
+ * only trim and lower-case EVM hex. Anything else is passed exactly as typed:
+ * base58 chains (BTC/TRON/SOL) are case-sensitive, and TON friendly addresses
+ * (EQ…/UQ…/Ef…/Uf…) carry a checksum over their case.
+ */
+/** EVM → lower case; every other chain's address is kept as typed (trimmed). */
+export function normalizeAddr(addr) {
+    const a = addr.trim();
+    return /^0x[0-9a-fA-F]{40}$/.test(a) ? a.toLowerCase() : a;
+}
+/**
+ * Shape of a TON address, no checksum: "raw" (0:/-1: + 64 hex), "friendly"
+ * (48-char mainnet EQ/UQ/Ef/Uf), "testnet" (kQ/0Q/kf/0f — ChainHint does not
+ * cover testnet), or null. Informational only; the API decides validity.
+ */
+export function tonAddressForm(addr) {
+    const a = addr.trim();
+    if (/^(0|-1):[0-9a-fA-F]{64}$/.test(a))
+        return "raw";
+    if (!/^[A-Za-z0-9_+/-]{48}$/.test(a))
+        return null;
+    if (/^(EQ|UQ|Ef|Uf)/.test(a))
+        return "friendly";
+    if (/^(kQ|0Q|kf|0f)/.test(a))
+        return "testnet";
+    return null;
+}
+/** Tool parameter text: which address spellings the tools accept. */
+export const ADDRESS_FORMS = "EVM 0x…, Bitcoin (1…/3…/bc1…), Solana, TRON (T…), or TON — mainnet friendly EQ…/UQ…/Ef…/Uf… or raw 0:<hex>/-1:<hex>, any form finds the same address (testnet kQ…/0Q… is not covered)";

package/dist/canon.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public database figures — the ChainHint canon (owner decision 2026-09-15,
+ * main repo migration 143, public/llms.txt). test/canon.test.mjs pins it and
+ * forbids the retired address / entity counts in the source and the README.
+ * Change only together with the site.
+ */
+export declare const ATTRIBUTED_ADDRESSES = "45M+";
+export declare const ILLICIT_ADDRESSES = "485K+";
+export declare const SANCTIONED_ADDRESSES = "1,000+";
+export declare const SANCTIONS_AUTHORITIES = "OFAC, EU, AU, JP, FR";
+/** "45M+ attributed addresses across 12 chains, including 485K+ …" */
+export declare const DATABASE_CANON = "45M+ attributed addresses across 12 chains, including 485K+ addresses linked to illicit activity and 1,000+ sanctioned addresses across 5 authorities (OFAC, EU, AU, JP, FR)";

package/dist/canon.js

@@ -0,0 +1,12 @@
+/**
+ * Public database figures — the ChainHint canon (owner decision 2026-09-15,
+ * main repo migration 143, public/llms.txt). test/canon.test.mjs pins it and
+ * forbids the retired address / entity counts in the source and the README.
+ * Change only together with the site.
+ */
+export const ATTRIBUTED_ADDRESSES = "45M+";
+export const ILLICIT_ADDRESSES = "485K+";
+export const SANCTIONED_ADDRESSES = "1,000+";
+export const SANCTIONS_AUTHORITIES = "OFAC, EU, AU, JP, FR";
+/** "45M+ attributed addresses across 12 chains, including 485K+ …" */
+export const DATABASE_CANON = `${ATTRIBUTED_ADDRESSES} attributed addresses across 12 chains, including ${ILLICIT_ADDRESSES} addresses linked to illicit activity and ${SANCTIONED_ADDRESSES} sanctioned addresses across 5 authorities (${SANCTIONS_AUTHORITIES})`;

package/dist/entity.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Entity wording — pure functions, tested in test/entity.test.mjs.
+ *
+ * Mirrors two optional entity fields the ChainHint API adds with migration 144
+ * (main repo: backend/supabase/functions/_shared/entity-attribution.ts,
+ * src/lib/entityCategory.ts):
+ *
+ *   attribution_unconfirmed: true — the named actor is a CANDIDATE, not a
+ *     finding (e.g. Flipside-sourced Coinbase forwarders). wallet-reputation
+ *     then answers top-level `category: "unknown"`. Shown, marked, never acted
+ *     on: not a known entity, not a freeze target, not a reason to lower risk.
+ *   operating_status: "closed" | "bankrupt" — the venue no longer operates.
+ *
+ * Both are optional: an API response without them prints exactly what 1.3.3
+ * printed.
+ */
+export interface EntityBlock {
+    name: string;
+    category?: string | null;
+    subcategory?: string | null;
+    verified?: boolean | null;
+    /** 0..1 (address-lookup). */
+    confidence?: number | null;
+    attribution_unconfirmed?: boolean | null;
+    operating_status?: string | null;
+}
+export type OperatingStatus = "closed" | "bankrupt";
+export declare function isUnconfirmedAttribution(e: EntityBlock | null | undefined): boolean;
+/** "closed" | "bankrupt" when set; unknown values are ignored (same as the backend). */
+export declare function entityOperatingStatus(e: EntityBlock | null | undefined): OperatingStatus | null;
+/** The sentences printed after the entity, in order. Empty when there is nothing to say. */
+export declare function entityMarkers(e: EntityBlock | null | undefined): string[];
+/**
+ * "**Entity:** Binance (exchange / hot_wallet, verified)" — plus the markers.
+ * An unconfirmed attribution prints its stored category as a candidate and
+ * never as verified.
+ */
+export declare function entityLine(e: EntityBlock, opts?: {
+    showVerified?: boolean;
+}): string;

package/dist/entity.js

@@ -0,0 +1,57 @@
+/**
+ * Entity wording — pure functions, tested in test/entity.test.mjs.
+ *
+ * Mirrors two optional entity fields the ChainHint API adds with migration 144
+ * (main repo: backend/supabase/functions/_shared/entity-attribution.ts,
+ * src/lib/entityCategory.ts):
+ *
+ *   attribution_unconfirmed: true — the named actor is a CANDIDATE, not a
+ *     finding (e.g. Flipside-sourced Coinbase forwarders). wallet-reputation
+ *     then answers top-level `category: "unknown"`. Shown, marked, never acted
+ *     on: not a known entity, not a freeze target, not a reason to lower risk.
+ *   operating_status: "closed" | "bankrupt" — the venue no longer operates.
+ *
+ * Both are optional: an API response without them prints exactly what 1.3.3
+ * printed.
+ */
+export function isUnconfirmedAttribution(e) {
+    return e?.attribution_unconfirmed === true;
+}
+/** "closed" | "bankrupt" when set; unknown values are ignored (same as the backend). */
+export function entityOperatingStatus(e) {
+    const s = (e?.operating_status ?? "").toLowerCase();
+    return s === "closed" || s === "bankrupt" ? s : null;
+}
+/** The sentences printed after the entity, in order. Empty when there is nothing to say. */
+export function entityMarkers(e) {
+    const out = [];
+    if (isUnconfirmedAttribution(e)) {
+        out.push("⚠️ Attribution unconfirmed — the named actor is a candidate, not a finding. Do not treat it as a known entity, a freeze target or a reason to lower risk.");
+    }
+    const status = entityOperatingStatus(e);
+    if (status === "closed")
+        out.push("Venue closed — a freeze request may not reach a compliance desk.");
+    if (status === "bankrupt")
+        out.push("Bankrupt — address the estate / trustee.");
+    return out;
+}
+/**
+ * "**Entity:** Binance (exchange / hot_wallet, verified)" — plus the markers.
+ * An unconfirmed attribution prints its stored category as a candidate and
+ * never as verified.
+ */
+export function entityLine(e, opts = {}) {
+    const unconfirmed = isUnconfirmedAttribution(e);
+    const cat = [e.category, e.subcategory].filter((p) => !!p && p.trim() !== "").join(" / ");
+    const parts = [];
+    if (cat)
+        parts.push(unconfirmed ? `candidate: ${cat}` : cat);
+    if (!unconfirmed && opts.showVerified && e.verified)
+        parts.push("verified");
+    if (!unconfirmed && e.confidence != null && Number.isFinite(e.confidence)) {
+        parts.push(`confidence ${Math.round(e.confidence * 100)}%`);
+    }
+    const head = `**Entity:** ${e.name}${parts.length ? ` (${parts.join(", ")})` : ""}`;
+    const markers = entityMarkers(e);
+    return markers.length ? `${head} — ${markers.join(" ")}` : head;
+}

package/dist/evidence.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Address evidence wording — MIRROR of the main repo's
+ * backend/supabase/functions/_shared/evidence-labels.ts (migration 129).
+ * Change both or neither; test/evidence.test.mjs pins the strings.
+ *
+ * Rule (owner decision 2026-09-14): "Sanctioned" is printed only for a
+ * sanctions designation. A law-enforcement attribution, an issuer freeze, a
+ * national seizure order and an industry blocklist each say what they are and
+ * that they are not a sanctions designation.
+ */
+export declare const EVIDENCE_CLASSES: readonly ["sanctions_designation", "law_enforcement_attribution", "issuer_freeze", "national_seizure_order", "industry_blocklist", "analyst_verified"];
+export type EvidenceClass = typeof EVIDENCE_CLASSES[number];
+export interface EvidenceItem {
+    class: EvidenceClass | string;
+    authority: string;
+    subject?: string | null;
+    document_ref?: string | null;
+    document_url?: string | null;
+    document_date?: string | null;
+    legal_basis?: string | null;
+    token?: string | null;
+    chain?: string | null;
+    first_seen_at?: string | null;
+    /**
+     * API since 2026-09-15: true only on an issuer freeze whose freezing token
+     * contract IS the looked-up address (Tether blacklisted the USDT held by the
+     * USDT contract). Scored 0 with no floor; printed as the backend's risk
+     * detail line, never as "Frozen by issuer".
+     */
+    held_by_token_contract?: boolean;
+}
+export declare const NOT_A_SANCTIONS_DESIGNATION = "Not a sanctions designation.";
+/** True for the one freeze that says nothing about the address as a counterparty. */
+export declare function isOwnTokenContractFreeze(e: Pick<EvidenceItem, "class" | "held_by_token_contract">): boolean;
+/**
+ * Same sentence as the backend's risk detail line (risk-engine.ts):
+ * "Tether blacklisted tokens held by this contract" — issuers de-duplicated.
+ */
+export declare function ownTokenContractFreezeText(items: ReadonlyArray<Pick<EvidenceItem, "authority">>): string;
+/** "⛔ Sanctioned — US OFAC · … " / "🧊 Frozen by issuer — Tether (USDT, TRON) · … Not a sanctions designation." */
+export declare function evidenceText(e: EvidenceItem): string | null;
+/**
+ * Designations first, then by strength of proof; unknown classes dropped.
+ * Freezes of tokens held by the looked-up token contract itself close the
+ * list as one line in the backend's wording — never a "Frozen by issuer" line.
+ */
+export declare function evidenceLines(items: ReadonlyArray<EvidenceItem> | null | undefined): string[];

package/dist/evidence.js

@@ -0,0 +1,111 @@
+/**
+ * Address evidence wording — MIRROR of the main repo's
+ * backend/supabase/functions/_shared/evidence-labels.ts (migration 129).
+ * Change both or neither; test/evidence.test.mjs pins the strings.
+ *
+ * Rule (owner decision 2026-09-14): "Sanctioned" is printed only for a
+ * sanctions designation. A law-enforcement attribution, an issuer freeze, a
+ * national seizure order and an industry blocklist each say what they are and
+ * that they are not a sanctions designation.
+ */
+export const EVIDENCE_CLASSES = [
+    "sanctions_designation",
+    "law_enforcement_attribution",
+    "issuer_freeze",
+    "national_seizure_order",
+    "industry_blocklist",
+    "analyst_verified",
+];
+export const NOT_A_SANCTIONS_DESIGNATION = "Not a sanctions designation.";
+const TITLES = {
+    sanctions_designation: { icon: "⛔", title: "Sanctioned" },
+    law_enforcement_attribution: { icon: "🚩", title: "Law-enforcement attribution" },
+    issuer_freeze: { icon: "🧊", title: "Frozen by issuer" },
+    national_seizure_order: { icon: "🏛️", title: "National seizure order" },
+    industry_blocklist: { icon: "⚠️", title: "Industry blocklist" },
+    analyst_verified: { icon: "🔎", title: "Analyst-verified" },
+};
+const CHAIN_NAMES = { bsc: "BSC", tron: "TRON", ton: "TON" };
+function isEvidenceClass(v) {
+    return typeof v === "string" && EVIDENCE_CLASSES.includes(v);
+}
+function chainName(chain) {
+    const c = (chain ?? "").trim().toLowerCase();
+    if (!c)
+        return "";
+    return CHAIN_NAMES[c] ?? c.charAt(0).toUpperCase() + c.slice(1);
+}
+function day(value) {
+    if (!value)
+        return null;
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(value.trim());
+    return m ? m[1] : null;
+}
+const join = (parts, sep) => parts.filter((p) => !!p && p.trim() !== "").join(sep);
+function attributionLine(e) {
+    const date = day(e.document_date);
+    let head = join([e.authority, e.document_ref], ", ");
+    if (date)
+        head = `${head} (${date})`;
+    return e.subject ? `${head}: ${e.subject}` : head;
+}
+/** True for the one freeze that says nothing about the address as a counterparty. */
+export function isOwnTokenContractFreeze(e) {
+    return e.class === "issuer_freeze" && e.held_by_token_contract === true;
+}
+/**
+ * Same sentence as the backend's risk detail line (risk-engine.ts):
+ * "Tether blacklisted tokens held by this contract" — issuers de-duplicated.
+ */
+export function ownTokenContractFreezeText(items) {
+    const issuers = [...new Set(items.map((e) => e.authority))].join(", ");
+    return `${issuers} blacklisted tokens held by this contract`;
+}
+/** "⛔ Sanctioned — US OFAC · … " / "🧊 Frozen by issuer — Tether (USDT, TRON) · … Not a sanctions designation." */
+export function evidenceText(e) {
+    if (!isEvidenceClass(e.class))
+        return null;
+    if (isOwnTokenContractFreeze(e))
+        return ownTokenContractFreezeText([e]);
+    const { icon, title } = TITLES[e.class];
+    const date = day(e.document_date);
+    let line;
+    switch (e.class) {
+        case "sanctions_designation":
+            line = join([e.authority, e.document_ref ?? e.legal_basis, date, e.subject], " · ");
+            break;
+        case "issuer_freeze": {
+            const what = join([e.token, chainName(e.chain)], ", ");
+            const when = date ?? join(["first seen by ChainHint", day(e.first_seen_at)], " ");
+            line = join([what ? `${e.authority} (${what})` : e.authority, when], " · ");
+            break;
+        }
+        case "law_enforcement_attribution":
+        case "national_seizure_order":
+            line = attributionLine(e);
+            break;
+        default:
+            line = join([e.authority, e.subject, date ?? (e.first_seen_at ? `first seen by ChainHint ${day(e.first_seen_at)}` : null)], " · ");
+    }
+    const caveat = e.class === "sanctions_designation" ? null : NOT_A_SANCTIONS_DESIGNATION;
+    return `${icon} ${caveat ? `${title} — ${line}. ${caveat}` : `${title} — ${line}`}`;
+}
+/**
+ * Designations first, then by strength of proof; unknown classes dropped.
+ * Freezes of tokens held by the looked-up token contract itself close the
+ * list as one line in the backend's wording — never a "Frozen by issuer" line.
+ */
+export function evidenceLines(items) {
+    if (!items?.length)
+        return [];
+    const rank = (c) => EVIDENCE_CLASSES.indexOf(c);
+    const known = items.filter((e) => isEvidenceClass(e.class));
+    const own = known.filter(isOwnTokenContractFreeze);
+    const lines = known
+        .filter((e) => !isOwnTokenContractFreeze(e))
+        .sort((a, b) => rank(a.class) - rank(b.class))
+        .map((e) => `- ${evidenceText(e)}`);
+    if (own.length)
+        lines.push(`- ${ownTokenContractFreezeText(own)}`);
+    return lines;
+}

package/dist/index.js

@@ -18,12 +18,16 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { apiErrorMessage, formatRiskLevel, lookupRiskLines, traceStatusLine } from "./verdicts.js";
+import { evidenceLines } from "./evidence.js";
+import { entityLine } from "./entity.js";
+import { ADDRESS_FORMS, normalizeAddr } from "./address.js";
+import { DATABASE_CANON } from "./canon.js";
 // ── Config ────────────────────────────────────────────────────────────────────
 const API_KEY = process.env.CHAINHINT_API_KEY;
 const BASE_URL = process.env.CHAINHINT_API_URL ?? "https://kjiwfwymnuzxriokhcjk.supabase.co/functions/v1";
 const SUPABASE_URL = process.env.CHAINHINT_SUPABASE_URL ?? "https://kjiwfwymnuzxriokhcjk.supabase.co";
 const SUPABASE_ANON_KEY = process.env.CHAINHINT_SUPABASE_ANON_KEY ?? "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImtqaXdmd3ltbnV6eHJpb2toY2prIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI3MzkxODgsImV4cCI6MjA4ODMxNTE4OH0.VqzzF_jI8zF072cbjWEDbYo3PnMDlIPy621iWkXEqyo";
-const VERSION = "1.3.2";
+const VERSION = "1.3.4";
 const USER_AGENT = `chainhint-mcp/${VERSION}`;
 const FREE_CHECKS_PER_DAY = 3;
 const UPGRADE_HINT = "set CHAINHINT_API_KEY (Agency plan, https://chainhint.com/pricing) for 10,000/day";
@@ -164,12 +168,6 @@ function endpointBucket(category, type, name) {
         return "defi";
     return "unknown";
 }
-// EVM addresses are case-insensitive and stored lowercase; base58 chains
-// (BTC/TRON/SOL/TON) are case-sensitive — never lowercase those.
-function normalizeAddr(addr) {
-    const a = addr.trim();
-    return a.startsWith("0x") ? a.toLowerCase() : a;
-}
 function formatExposure(label, buckets) {
     if (!buckets?.length)
         return [];
@@ -220,8 +218,8 @@ const server = new McpServer({
     version: VERSION,
 });
 // ── Tool 1: check_wallet_risk ─────────────────────────────────────────────────
-server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address against ChainHint's 54M+ labeled address database (12 chains). Returns risk score 0-100, risk level (clean/low/medium/high/critical/sanctioned), entity name and category, labels, and sanctions hit. Use it to decide allow/warn/block before paying or interacting with a counterparty wallet. Free: 3 checks per day without a key; CHAINHINT_API_KEY (Agency plan) lifts it to 10,000/day. For a deeper report (risk factors, exposure, balance) use lookup_address.", {
-    address: z.string().describe("Wallet address to check (EVM 0x..., Bitcoin, or Solana)"),
+server.tool("check_wallet_risk", `Fast risk check for a crypto wallet address against ChainHint's entity database — ${DATABASE_CANON}. Returns risk score 0-100, risk level (clean/low/medium/high/critical/sanctioned), entity name and category, labels, and sanctions hit. Use it to decide allow/warn/block before paying or interacting with a counterparty wallet. Free: 3 checks per day without a key; CHAINHINT_API_KEY (Agency plan) lifts it to 10,000/day. For a deeper report (risk factors, exposure, balance) use lookup_address.`, {
+    address: z.string().describe(`Wallet address to check: ${ADDRESS_FORMS}`),
     chain: z.string().optional().describe("Blockchain: ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, gnosis, bitcoin, solana, tron, ton (default: auto-detect from address format; the response chain is the address family for bitcoin/solana/tron/ton)"),
 }, async ({ address, chain }) => {
     try {
@@ -236,13 +234,13 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
             `**Chain:** ${d.chain}`,
         ];
         // Canon (same as chainhint.com and the TG bot): an address that is not in
-        // the labeled database has NO DATA — that is not evidence it is clean.
+        // the entity database has NO DATA — that is not evidence it is clean.
         // The API still returns risk_score 0 / "clean" for not-found, so the
         // wording is fixed here, and public incidents are cross-checked so a
         // known hack attacker that never got an `addresses` row is not
         // presented as unknown.
         if (!d.found_in_db) {
-            lines.push(`**Risk:** ⚪ NO DATA — address is not in ChainHint's labeled database. This is not evidence it is clean.`);
+            lines.push(`**Risk:** ⚪ NO DATA — address is not in ChainHint's entity database. This is not evidence it is clean.`);
             const inc = await findPublicIncidentByAttacker(d.address);
             if (inc) {
                 const attribution = attackerAttribution({ attacker_address: d.address, ...inc });
@@ -256,13 +254,17 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
         else {
             lines.push(`**Risk Score:** ${d.risk_score}/100 — **${(d.risk_level ?? formatRiskLevel(d.risk_score)).toUpperCase()}**`);
         }
-        if (d.sanctions?.hit) {
-            lines.push(`⛔ **SANCTIONED / OFAC-linked**`);
+        // sanctions.hit comes only from a sanctions designation (API since migration 129);
+        // the evidence lines say which authority and that other classes are not sanctions.
+        const walletEvidence = evidenceLines(d.evidence);
+        if (d.sanctions?.hit && !walletEvidence.some((l) => l.startsWith("- ⛔"))) {
+            lines.push(`⛔ **SANCTIONED**`);
         }
+        if (walletEvidence.length)
+            lines.push(`**Evidence:**`, ...walletEvidence);
         if (d.entity?.name) {
-            const sub = d.entity.subcategory ? ` / ${d.entity.subcategory}` : "";
-            const ver = d.entity.verified ? ", verified" : "";
-            lines.push(`**Entity:** ${d.entity.name} (${d.entity.category}${sub}${ver})`);
+            // An unconfirmed attribution is marked; the API's top-level category is then "unknown".
+            lines.push(entityLine(d.entity, { showVerified: true }));
         }
         else if (d.category) {
             lines.push(`**Category:** ${d.category}`);
@@ -294,7 +296,7 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
 });
 // ── Tool 2: lookup_address ────────────────────────────────────────────────────
 server.tool("lookup_address", "Detailed lookup of a blockchain address: entity attribution, risk score with the factors behind it, sanctions and GoPlus security flags, counterparty exposure (where funds came from / went to, by category with named entities), balance, token count and transaction count. Free: 10 lookups per day without a key; CHAINHINT_API_KEY lifts it. Supports EVM chains, Bitcoin, Solana, TRON, TON.", {
-    address: z.string().describe("Blockchain address to look up"),
+    address: z.string().describe(`Blockchain address to look up: ${ADDRESS_FORMS}`),
     chain: z.string().optional().describe("Blockchain (ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, gnosis, bitcoin, solana, tron, ton)"),
 }, async ({ address, chain }) => {
     try {
@@ -313,9 +315,7 @@ server.tool("lookup_address", "Detailed lookup of a blockchain address: entity a
             `**Type:** ${d.is_contract ? "Smart Contract" : "EOA (wallet)"}`,
         ];
         if (d.entity?.name) {
-            const sub = d.entity.subcategory ? ` / ${d.entity.subcategory}` : "";
-            const conf = d.entity.confidence != null ? `, confidence ${Math.round(d.entity.confidence * 100)}%` : "";
-            lines.push(`**Entity:** ${d.entity.name} (${d.entity.category}${sub}${conf})`);
+            lines.push(entityLine(d.entity));
         }
         else {
             lines.push(`**Entity:** Unknown / unlabeled`);
@@ -328,6 +328,9 @@ server.tool("lookup_address", "Detailed lookup of a blockchain address: entity a
             lines.push(`**Labels:** ${[...new Set(d.labels)].join(", ")}`);
         // Never a score or "CLEAN" when there was nothing to score (verdicts.ts).
         lines.push(...lookupRiskLines(d));
+        const lookupEvidence = evidenceLines(d.evidence);
+        if (lookupEvidence.length)
+            lines.push(`**Evidence:**`, ...lookupEvidence);
         const sanctionIds = d.sanctions?.identifications ?? [];
         if (sanctionIds.length) {
             const names = sanctionIds.map((s) => [s.name, s.program].filter(Boolean).join(" / ")).filter(Boolean);

package/dist/verdicts.d.ts

@@ -19,6 +19,13 @@ export declare function isTraceableChain(chain: string | null | undefined): bool
 /** Same sentence as the backend's tracingUnavailableMessage. */
 export declare function tracingUnavailableMessage(chain: string | null | undefined): string;
 export declare function formatRiskLevel(score: number): string;
+/**
+ * Risk factors the API still returns in the response shape but no longer
+ * scores (always false). Never printed, whatever an old or cached response says.
+ * contract_not_verified: retired 2026-09-15 (risk-engine.ts) — the contract
+ * flag it read was wrong on every audited row.
+ */
+export declare const RETIRED_RISK_FACTORS: readonly string[];
 export type DataUnavailable = {
     provider?: string;
     reason?: string;

package/dist/verdicts.js

@@ -39,6 +39,13 @@ export function formatRiskLevel(score) {
         return "LOW";
     return "CLEAN";
 }
+/**
+ * Risk factors the API still returns in the response shape but no longer
+ * scores (always false). Never printed, whatever an old or cached response says.
+ * contract_not_verified: retired 2026-09-15 (risk-engine.ts) — the contract
+ * flag it read was wrong on every audited row.
+ */
+export const RETIRED_RISK_FACTORS = ["contract_not_verified"];
 function unavailableDetail(d) {
     const provider = d.data_availability?.provider ?? d.exposure?.data_unavailable?.provider;
     return d.data_availability?.detail
@@ -63,7 +70,9 @@ export function lookupRiskLines(d) {
         return [];
     const level = (d.risk.level ?? formatRiskLevel(d.risk.score)).toUpperCase();
     const lines = [`**Risk Score:** ${d.risk.score}/100 — **${level}**`];
-    const factors = Object.entries(d.risk.factors ?? {}).filter(([, v]) => v).map(([k]) => k);
+    const factors = Object.entries(d.risk.factors ?? {})
+        .filter(([k, v]) => v === true && !RETIRED_RISK_FACTORS.includes(k))
+        .map(([k]) => k);
     if (factors.length)
         lines.push(`**Risk Factors:** ${factors.join(", ")}`);
     if (d.risk.details?.length)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chainhint-mcp",
-  "version": "1.3.2",
-  "description": "ChainHint MCP server \u2014 crypto risk intelligence tools for Claude Desktop and Cursor",
+  "version": "1.3.4",
+  "description": "ChainHint MCP server — crypto risk intelligence tools for Claude Desktop and Cursor",
   "license": "MIT",
   "repository": {
     "type": "git",