chainhint-mcp 1.1.0 → 1.2.1

package/dist/index.js

@@ -105,14 +105,78 @@ function formatRiskLevel(score) {
 function truncateAddr(addr) {
     return addr.length > 12 ? `${addr.slice(0, 8)}...${addr.slice(-6)}` : addr;
 }
+// Same tiers as the site's formatUsd (src/lib/utils.ts): $1.4B, $115.0M, $629.4K.
+// KIR-45: this used to stop at "M" and print "$1409.97M" for the Bybit loss.
 function usd(n) {
     if (n == null || !Number.isFinite(n))
         return "Unknown";
-    if (Math.abs(n) >= 1_000_000)
-        return `$${(n / 1_000_000).toFixed(2)}M`;
-    if (Math.abs(n) >= 1_000)
-        return `$${(n / 1_000).toFixed(1)}K`;
-    return `$${n.toFixed(2)}`;
+    const abs = Math.abs(n);
+    if (abs >= 1e15)
+        return "Unknown";
+    if (abs >= 1e12)
+        return `$${(n / 1e12).toFixed(1)}T`;
+    if (abs >= 1e9)
+        return `$${(n / 1e9).toFixed(1)}B`;
+    if (abs >= 1e6)
+        return `$${(n / 1e6).toFixed(1)}M`;
+    if (abs >= 1e3)
+        return `$${(n / 1e3).toFixed(1)}K`;
+    return `$${n.toLocaleString("en-US", { maximumFractionDigits: 2 })}`;
+}
+// Hop count as the site counts it (src/lib/traceReconciliation deriveDepthMap):
+// shortest-path depth from the attacker over the edges, max over reachable
+// nodes — NOT max(edge.depth), which the tracer assigns as it walks (Bybit:
+// 6 vs the site's 5).
+function hopCount(edges, attacker) {
+    const src = (attacker ?? "").toLowerCase();
+    if (!src || !edges.length)
+        return 0;
+    const out = new Map();
+    for (const e of edges) {
+        const f = (e.from ?? "").toLowerCase(), t = (e.to ?? "").toLowerCase();
+        if (!f || !t)
+            continue;
+        (out.get(f) ?? out.set(f, []).get(f)).push(t);
+    }
+    const depth = new Map([[src, 0]]);
+    const queue = [src];
+    let max = 0;
+    while (queue.length) {
+        const a = queue.shift();
+        const d = depth.get(a);
+        for (const b of out.get(a) ?? []) {
+            if (depth.has(b))
+                continue;
+            depth.set(b, d + 1);
+            if (d + 1 > max)
+                max = d + 1;
+            queue.push(b);
+        }
+    }
+    return max;
+}
+// Endpoint buckets as the site's Flow Summary (src/lib/flowSummary.ts): the
+// entity CATEGORY decides — an attacker wallet retyped "exchange" is not an
+// exchange, a no-KYC swap is not a freeze target.
+const ATTACKER_CATEGORIES = new Set(["hacker", "scam", "exploit"]);
+const NO_KYC_TOKENS = ["changenow", "fixedfloat", "simpleswap", "sideshift", "stealthex", "changelly", "letsexchange", "godex", "swapuz", "exolix", "exch.cx", "exch.sc", "exch.net", "ff.io"];
+function endpointBucket(category, type, name) {
+    const c = (category ?? "").toLowerCase();
+    const t = (type ?? "").toLowerCase();
+    const n = (name ?? "").toLowerCase().replace(/[\s_-]/g, "");
+    if (ATTACKER_CATEGORIES.has(c))
+        return "attacker-attributed";
+    if (c === "sanctioned" || c === "high_risk_exchange" || NO_KYC_TOKENS.some((k) => n.includes(k.replace(/[\s_-]/g, ""))))
+        return "risky";
+    if (c === "mixer" || t === "mixer")
+        return "mixer";
+    if (c === "bridge" || t === "bridge")
+        return "bridge";
+    if (c === "exchange" || t === "exchange")
+        return "exchange";
+    if (c === "defi" || c === "dex" || t === "defi" || t === "dex")
+        return "defi";
+    return "unknown";
 }
 // EVM addresses are case-insensitive and stored lowercase; base58 chains
 // (BTC/TRON/SOL/TON) are case-sensitive — never lowercase those.
@@ -154,7 +218,7 @@ const server = new McpServer({
 // ── 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)"),
-    chain: z.string().optional().describe("Blockchain: ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, solana, bitcoin (default: auto-detect from address format)"),
+    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 {
         const params = { address };
@@ -217,7 +281,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"),
-    chain: z.string().optional().describe("Blockchain (ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, solana, bitcoin, tron, ton)"),
+    chain: z.string().optional().describe("Blockchain (ethereum, bsc, polygon, arbitrum, optimism, base, avalanche, gnosis, bitcoin, solana, tron, ton)"),
 }, async ({ address, chain }) => {
     try {
         const params = { address };
@@ -323,7 +387,8 @@ server.tool("get_trace_status", "Fund-trace summary for a publicly tracked crypt
             };
         }
         const inc = rows[0];
-        const lossUsd = inc.amount_usd ?? inc.estimated_loss_usd;
+        // The site's figure: stored estimated_loss_usd first (TraceFacts.displayedLossUsd), amount_usd as fallback.
+        const lossUsd = inc.estimated_loss_usd ?? inc.amount_usd;
         const date = inc.display_date ?? inc.hack_date ?? inc.created_at;
         const status = (inc.status ?? "unknown").toLowerCase();
         const lines = [
@@ -346,15 +411,20 @@ server.tool("get_trace_status", "Fund-trace summary for a publicly tracked crypt
         const edges = inc.flow_graph?.edges ?? [];
         const nodes = inc.flow_graph?.nodes ?? [];
         if (edges.length) {
-            const maxDepth = edges.reduce((m, e) => Math.max(m, e.depth ?? 0), 0);
+            const hops = hopCount(edges, inc.attacker_address);
             lines.push(``, `### Trace Graph`);
-            lines.push(`**Hops traced:** ${maxDepth} · **Addresses:** ${nodes.length} · **Transfers:** ${edges.length}`);
+            lines.push(`**Hops traced:** ${hops} · **Addresses:** ${nodes.length} · **Transfers:** ${edges.length}`);
         }
         const endpoints = inc.endpoints ?? [];
+        // A graph none of whose edges carries amount_usd was never valued (legacy
+        // Bitcoin rows): endpoint.amount_usd then holds the raw asset quantity and
+        // must not be printed as dollars (multi-chain audit 2026-09-03).
+        const graphPriced = edges.length === 0 || edges.some((e) => e.amount_usd != null && Number(e.amount_usd) > 0);
+        const money = (n) => (graphPriced ? usd(n) : "unpriced");
         if (endpoints.length) {
             const byType = new Map();
             for (const e of endpoints) {
-                const t = e.type ?? "unknown";
+                const t = endpointBucket(e.entity_category, e.type, e.entity_name ?? e.entity);
                 const b = byType.get(t) ?? { usd: 0, n: 0, entities: new Map() };
                 b.usd += e.amount_usd ?? 0;
                 b.n += 1;
@@ -364,11 +434,12 @@ server.tool("get_trace_status", "Fund-trace summary for a publicly tracked crypt
                 byType.set(t, b);
             }
             const totalUsd = [...byType.values()].reduce((s, b) => s + b.usd, 0);
-            lines.push(``, `### Where the funds went (${endpoints.length} endpoints, ${usd(totalUsd)} tracked)`);
+            // Σ endpoint amounts counts every hop's inflow (multi-hop), so it is larger than the loss — name the base.
+            lines.push(``, `### Where the funds went (${endpoints.length} endpoints, ${graphPriced ? `${usd(totalUsd)} observed at endpoints — not the loss figure` : "this trace carries no USD valuation"})`);
             for (const [t, b] of [...byType.entries()].sort((a, b) => b[1].usd - a[1].usd)) {
                 const top = [...b.entities.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([n]) => n);
                 const pct = totalUsd > 0 ? ` (${((b.usd / totalUsd) * 100).toFixed(1)}%)` : "";
-                lines.push(`- **${t}**: ${usd(b.usd)}${pct} across ${b.n} address(es)${top.length ? ` — ${top.join(", ")}` : ""}`);
+                lines.push(`- **${t}**: ${money(b.usd)}${graphPriced ? pct : ""} across ${b.n} address(es)${top.length ? ` — ${top.join(", ")}` : ""}`);
             }
             const topEndpoints = [...endpoints]
                 .filter((e) => (e.amount_usd ?? 0) > 0)
@@ -378,7 +449,7 @@ server.tool("get_trace_status", "Fund-trace summary for a publicly tracked crypt
                 lines.push(`**Largest endpoints:**`);
                 for (const e of topEndpoints) {
                     const name = e.entity_name ?? e.entity ?? "unattributed";
-                    lines.push(`- ${truncateAddr(e.address)} — ${name} (${e.type ?? "unknown"}): ${usd(e.amount_usd)}`);
+                    lines.push(`- ${truncateAddr(e.address)} — ${name} (${endpointBucket(e.entity_category, e.type, e.entity_name ?? e.entity)}): ${money(e.amount_usd)}`);
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chainhint-mcp",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "ChainHint MCP server — crypto risk intelligence tools for Claude Desktop and Cursor",
   "license": "MIT",
   "repository": {