chainhint-mcp 1.3.3 → 1.4.0

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
@@ -96,11 +104,13 @@ npm run dev
 
 ## Environment Variables
 
+> **Upgrade to 1.4.0.** Versions before 1.4.0 send ChainHint's legacy Supabase anon key, which is being retired: `get_trace_status` on those versions will return 401. `check_wallet_risk` and `lookup_address` are unaffected. `npx chainhint-mcp@latest` picks up 1.4.0.
+
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `CHAINHINT_API_KEY` | — | Agency plan key from chainhint.com. Lifts the free limits (3 checks + 10 lookups per day) to 10,000 / day |
 | `CHAINHINT_API_URL` | — | Override API base URL (default: production) |
-| `CHAINHINT_SUPABASE_ANON_KEY` | — | Override anon key for get_trace_status (public incidents) |
+| `CHAINHINT_SUPABASE_PUBLISHABLE_KEY` | — | Override the Supabase publishable key used by get_trace_status (public incidents). Sent only in `apikey`. The pre-1.4.0 name `CHAINHINT_SUPABASE_ANON_KEY` is still read |
 
 ## Example prompts
 

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

@@ -21,9 +21,27 @@ export interface EvidenceItem {
     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. */
+/**
+ * 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

@@ -49,10 +49,24 @@ function attributionLine(e) {
         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;
@@ -76,13 +90,22 @@ export function evidenceText(e) {
     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. */
+/**
+ * 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);
-    return [...items]
-        .filter((e) => isEvidenceClass(e.class))
+    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

@@ -19,12 +19,17 @@ 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";
+import { DEFAULT_SUPABASE_KEY, isSupabaseKeyConfigured, resolveSupabaseKey, supabaseRestHeaders } from "./supabase-rest.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.3";
+// Publishable key, sent only in `apikey` (never as a Bearer token) — see supabase-rest.ts.
+const SUPABASE_KEY = resolveSupabaseKey(process.env, DEFAULT_SUPABASE_KEY);
+const VERSION = "1.4.0";
 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";
@@ -75,12 +80,11 @@ async function supabaseGet(table, params) {
     for (const [k, v] of Object.entries(params)) {
         url.searchParams.set(k, v);
     }
+    if (!isSupabaseKeyConfigured(SUPABASE_KEY)) {
+        throw new Error("get_trace_status is not configured: no Supabase publishable key (set CHAINHINT_SUPABASE_PUBLISHABLE_KEY or upgrade chainhint-mcp)");
+    }
     const res = await fetch(url.toString(), {
-        headers: {
-            "apikey": SUPABASE_ANON_KEY,
-            "Authorization": `Bearer ${SUPABASE_ANON_KEY}`,
-            "Accept": "application/json",
-        },
+        headers: supabaseRestHeaders(SUPABASE_KEY),
     });
     if (!res.ok) {
         const err = await res.text();
@@ -165,12 +169,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 [];
@@ -221,8 +219,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 {
@@ -237,13 +235,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 });
@@ -266,9 +264,8 @@ server.tool("check_wallet_risk", "Fast risk check for a crypto wallet address ag
         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}`);
@@ -300,7 +297,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 {
@@ -319,9 +316,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`);

package/dist/supabase-rest.d.ts

@@ -0,0 +1,21 @@
+/** Env var for the project key (1.4.0+). */
+export declare const PUBLISHABLE_KEY_ENV = "CHAINHINT_SUPABASE_PUBLISHABLE_KEY";
+/** Pre-1.4.0 name, still honoured so existing configs keep their override. */
+export declare const LEGACY_ANON_KEY_ENV = "CHAINHINT_SUPABASE_ANON_KEY";
+/** Env override first (new name, then the legacy name), else the built-in default. */
+export declare function resolveSupabaseKey(env: Record<string, string | undefined>, fallback: string): string;
+/** Headers for an anonymous REST read of a public view: key in apikey only. */
+export declare function supabaseRestHeaders(key: string): Record<string, string>;
+/** Marker the default carries until the owner pastes the real publishable key. */
+export declare const PUBLISHABLE_KEY_PLACEHOLDER = "sb_publishable_PASTE_BEFORE_PUBLISH";
+/**
+ * ChainHint's Supabase publishable key (sb_publishable_…) — public by design, the
+ * same value the chainhint.com bundle ships. Paste it here before `npm publish`;
+ * `prepublishOnly` (scripts/check-publish.mjs) refuses to publish while this is the
+ * placeholder, a JWT or anything that is not a publishable key.
+ */
+export declare const DEFAULT_SUPABASE_KEY: string;
+/** Why `key` must not be the published default, or null when it is a real publishable key. */
+export declare function publishKeyProblem(key: string): string | null;
+/** true when REST reads can run: an override or a real default. */
+export declare function isSupabaseKeyConfigured(key: string): boolean;

package/dist/supabase-rest.js

@@ -0,0 +1,44 @@
+// KIR-81 (1.4.0): the Supabase project key is a publishable key
+// (`sb_publishable_…`), not a JWT. It is sent ONLY in the `apikey` header —
+// never as `Authorization: Bearer`, which PostgREST would try to verify as a
+// JWT. Versions < 1.4.0 sent the legacy anon JWT in both headers and stop
+// working when the project disables its legacy API keys.
+/** Env var for the project key (1.4.0+). */
+export const PUBLISHABLE_KEY_ENV = "CHAINHINT_SUPABASE_PUBLISHABLE_KEY";
+/** Pre-1.4.0 name, still honoured so existing configs keep their override. */
+export const LEGACY_ANON_KEY_ENV = "CHAINHINT_SUPABASE_ANON_KEY";
+/** Env override first (new name, then the legacy name), else the built-in default. */
+export function resolveSupabaseKey(env, fallback) {
+    const fromEnv = env[PUBLISHABLE_KEY_ENV] || env[LEGACY_ANON_KEY_ENV];
+    return fromEnv && fromEnv.trim() ? fromEnv.trim() : fallback;
+}
+/** Headers for an anonymous REST read of a public view: key in apikey only. */
+export function supabaseRestHeaders(key) {
+    return { apikey: key, Accept: "application/json" };
+}
+/** Marker the default carries until the owner pastes the real publishable key. */
+export const PUBLISHABLE_KEY_PLACEHOLDER = "sb_publishable_PASTE_BEFORE_PUBLISH";
+/**
+ * ChainHint's Supabase publishable key (sb_publishable_…) — public by design, the
+ * same value the chainhint.com bundle ships. Paste it here before `npm publish`;
+ * `prepublishOnly` (scripts/check-publish.mjs) refuses to publish while this is the
+ * placeholder, a JWT or anything that is not a publishable key.
+ */
+export const DEFAULT_SUPABASE_KEY = "sb_publishable_BpalXiQKLHEpDqyNpt2Tkw_JYkuIGBK";
+/** Why `key` must not be the published default, or null when it is a real publishable key. */
+export function publishKeyProblem(key) {
+    const k = (key ?? "").trim();
+    if (k === PUBLISHABLE_KEY_PLACEHOLDER)
+        return "the default key is still the placeholder";
+    if (k.startsWith("eyJ"))
+        return "the default key is a JWT (legacy anon key) — use the sb_publishable_ key";
+    if (k.startsWith("sb_secret_"))
+        return "the default key is a SECRET key — never ship it";
+    if (!/^sb_publishable_[A-Za-z0-9_-]{16,}$/.test(k))
+        return "the default key does not look like an sb_publishable_ key";
+    return null;
+}
+/** true when REST reads can run: an override or a real default. */
+export function isSupabaseKeyConfigured(key) {
+    return publishKeyProblem(key) === null || ((key ?? "").trim() !== "" && (key ?? "").trim() !== PUBLISHABLE_KEY_PLACEHOLDER && !(key ?? "").trim().startsWith("eyJ"));
+}

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.3",
-  "description": "ChainHint MCP server \u2014 crypto risk intelligence tools for Claude Desktop and Cursor",
+  "version": "1.4.0",
+  "description": "ChainHint MCP server — crypto risk intelligence tools for Claude Desktop and Cursor",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,8 +35,9 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build",
-    "test": "npm run build && node --test test/*.test.mjs"
+    "prepublishOnly": "npm run build && node scripts/check-publish.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "check:publish": "npm run build && node scripts/check-publish.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",