English · Français
Map the blockchain. Turn raw on-chain transactions into an interactive fund-flow graph — for OSINT investigators, journalists, and students learning how blockchains work.
Paste an address → chainmap fetches its transactions from the Etherscan v2 API and draws a directed address → address graph, expanded breadth-first to a depth you choose. Then it layers investigator tooling on top: filters, edge bundling, contract-call decoding, cycle detection, sink/faucet hubs, and per-node risk scoring.
- Fully client-side — no backend, no build step, no telemetry.
- Your API key and data stay in your browser. On EVM chains the only
site contacted is
api.etherscan.io— plusapi.trongrid.io(TronGrid) only after you explicitly choose Tron, andcoins.llama.fi(DefiLlama) only while you tick the opt-in Show USD values box — enforced by a strict Content-Security-Policy. - English + French, fully localized.
- 1011 unit/integration tests on the DOM-free core.
- Quick start
- Features
- Learn how blockchains work
- Architecture
- Tron (opt-in, via TronGrid)
- Privacy, security & ethics
- Development & tests
- Supported chains
Zero install — it's native ES modules.
git clone https://github.com/gl0bal01/chainmap.git && cd chainmap
python3 -m http.server 8000
# open http://localhost:8000/No API key? Click Demo mode — it loads a bundled sample investigation so you can explore every feature immediately.
Live scans: get a free key at https://etherscan.io → API Keys, paste it in the UI, pick a chain, paste an address, Start. One key works across all supported chains (Etherscan v2 is a unified multichain endpoint; some chains need a paid plan — see Supported chains).
- BFS expansion — recurse from a root address to any depth, with a per-address sample size, a hard safety cap, and a Stop that truly aborts in-flight requests.
- Load older — a node whose last fetch returned a full batch gets a dashed border (more history available). Select it and use Load older (+N) in the details panel to page further back by block number; new counterparties are added but not explored automatically. The cursor is saved in the workspace. A graph can hold several chains: every node and edge keeps its own chain, and the same address on two chains is two nodes.
- Multi-chain graph — add a chain from the scan form or a node's Other chains row. The
same address on two chains is two nodes. A dotted same key link appears only when the
address signed a transaction on a non-AA chain; "same address only" pairs are listed, never
drawn. Known limitation: on OP-stack/Arbitrum chains Etherscan's
txlistcan include L1→L2 deposit/system transactions whose sender is an aliased L1 contract, which could read as "same key" across two such chains. The link is a signal, not proof of common ownership. Not in this version: coloring nodes by chain, and drawing "same address only" links. - Three tx families — normal, internal, and ERC-20/721/1155 token transfers, each a colored edge.
- Calldata decoding — 4-byte selectors → human method names + named decoded args and
a plain-language
► Summaryline, so atransfer()'s real recipient (hidden in calldata) is surfaced. Any human-readable message carried in a transaction's input (on-chain notes, "gm", ransom demands — Latin, Cyrillic, CJK or Arabic) is decoded and shown both in the edge details panel and directly in the on-graph hover tooltip, so you spot it without a click. - Noise reduction — amount/date/zero-value/spam filters, and edge bundling (collapse many A→B transfers into one weighted arrow).
- Investigation overlays — round-trip (cycle) detection, sink/faucet hubs (with reversible Hide faucets / Hide sinks toggles), peel-chain detection (highlights forwarding chains where value hops through throwaway addresses), color-by-age, known-address labels (see below), mixer/bridge/sanctioned tagging (🌀/🌉/⛔ badges), and an explainable per-node risk score.
- Likely exchange deposit addresses (🏦) — an address whose sampled outflow went almost
entirely (>= 90 % of transfers and of each swept asset's value) to one known exchange hot
wallet, with at least one sweep in the native coin or a known token (a forged token transfer
cannot create a mark alone), is marked "likely deposit →
<wallet>", with its evidence in the details panel and in the CSV (likely_deposit_of,deposit_evidence). A heuristic lead for a compliance request, never an attribution. Only addresses whose own transactions were fetched are judged, and only wallets listed indata/are recognized. - Sourced known-address base — ~580 labels (bridges, routers, mixers, canonical tokens,
OFAC-sanctioned addresses, a few exchange hot wallets) generated from the official OFAC SDN
list (sanctions and delistings as of the last data rebuild; the OFAC publish date is shown in
each sanctioned entry's Source), the MIT superchain registry and a curated seed verified
against cited official pages, except 9 legacy explorer-label rows marked
needs official source. Seedata/README.md. - Imitation-token detection — a transfer whose symbol mimics an official token (spoofed USDT/USDC, look-alike letters, invisible characters) from a non-official contract gets an amber ⓘ flag and is hidden by the spam filter ("Hide known spam tokens"). Known limitation: legit but uncurated same-symbol contracts (e.g. Wormhole-wrapped USDC/WETH, PulseChain-bridged WETH/WBTC on Ethereum) are flagged too: the flag means "not the official contract for this symbol on this chain", a signal, not a verdict.
- Per-edge risk flags — unlimited/blanket approvals, a hidden real recipient, and mixer/bridge/sanctioned counterparties are called out in the edge details panel and escalated on the graph in two visual tiers: danger (mixer/bridge/sanctioned, red ⚠) vs informational (approvals/hidden-recipient/imitation tokens, amber ⓘ). Signals, not verdicts — always corroborate before you conclude.
- Chain detector — paste any address; it tells you the chain family (or non-EVM) by format. Then click Detect chain to probe ~12 popular chains for on-chain activity and auto-select the one where the address is most active, showing where else it's active.
- Exports — PNG, PDF, and CSV (with a sampling caveat baked in, plus decoded method, real recipient, decoded amount, and risk-flag columns per edge). Save/load workspaces. PNG/PDF carry a provenance footer and the likely-deposit mark; the CSV carries it on line 1.
- Query log — every Etherscan request is logged in memory (time, chain, request without
the API key, HTTP status, row count, SHA-256 of the raw response body, outcome) and shown in
a panel. Export it as
.json; it is also saved inside workspaces. - Evidence bundle — one
.zip(store-only) withgraph.csv,graph.png,workspace.json,query-log.json, aMANIFEST.jsonand aSHA256SUMSyou check withsha256sum -c. The zip's own SHA-256 is written in the app log for your case notes. Tamper evidence only. - Inferred bridge links — deposits into known bridges are detected and the expected recipient
on the other side is decoded from the call, or else assumed to be the depositor's own address (a
weaker basis, said so). Look for the release on {chain} sends up to three requests for that
recipient there (one page each of normal, internal and token transactions, each logged in the
query log); candidate releases are drawn dashed, "inferred — verify", with a
low/medium/highconfidence and their evidence (amount, delay, recipient basis, release sender). You confirm or reject each one; that decision is recorded as your assertion (not on-chain proof) in the details panel, the CSVbridge_inferredcolumn, PNG/PDF, the evidence MANIFEST and the workspace. Never proof, and only from the data already loaded. - Search & keyboard navigation — a 🔍 search button in the top bar (or Ctrl/Cmd+K) opens a command palette that searches nodes by address / alias / known-label / category and transactions by hash / method (hybrid substring + fuzzy ranking); picking a result focuses + selects it and auto-reveals it if hidden by a filter/hub-hide. The button makes search reachable on mobile / touch, where there's no keyboard shortcut. Ctrl/Cmd+Arrow jumps selection to the nearest node in that direction.
- Historical USD values (opt-in) — tick Show USD values (off at every page load,
never saved) to get an estimate of each transfer's USD value in the edge details panel and
in a CSV column
usd_value: DefiLlama's price within 1 h of the transaction × the exact token amount (BigInt). Unknown, pending or unpriced is blank, never0. NFTs, zero-value, imitation-token, spam-list, investigated-contract and unknown-data transfers, testnets and unsupported chains are never priced. Every price request is in the query log. See LEARN §11. - Honest by design — big-integer amounts (never floating point), failed txs dropped, and sampling surfaced everywhere. The sampling caveat applies to every feature above: overlays, flags, and hub/peel-chain detection only ever see the sampled graph, never full on-chain history.
chainmap doubles as a hands-on course. Every blockchain concept — accounts, the three transaction families, base units & decimals, calldata, token standards, BFS graphs, sampling, failed txs, multichain, and investigation heuristics — maps to something you can see and do in the tool, with 8 guided labs.
📚 Full curriculum + labs → docs/LEARN.md · en français → docs/LEARN.fr.md
Native ES modules, no bundler. The design principle: graphStore is the single
source of truth. Every mutation goes through it; it emits events; the render layer mirrors
it into vis-network DataSets by subscribing. Filters/overlays are a display projection
(vis DataViews) over that mirror, so the store always holds the full graph for CSV/detail
even when the view is filtered.
BFS scan ──► graphStore (truth) ──emits events──► render/network ──► vis DataViews ──► canvas
▲ │ ▲
etherscanClient ui.js / main.js (composition root) filters · bundling · overlays
▲
rateLimiter
The correctness-critical core is DOM-free and unit-tested in Node (format,
etherscanClient, graphStore, scanner, display, roundTrips, riskScore, …). The
DOM/vis layer (render/*, ui.js) is thin. See INTERFACES.md for the
frozen module contracts.
Tron is not an Etherscan chain, so it is read through TronGrid (api.trongrid.io) and only
when you ask for it.
- Choose it: pick Tron — via TronGrid (opt-in) in Chain. The choice is per session
(never saved: a reload shows your last EVM chain). Paste a
T…address (checksum-verified, case kept) or41…hex. AT…pasted while an EVM chain is selected only shows a hint; no request is sent. - Key (optional): a TronGrid API key lifts the rate limit (2 requests/s without one, up
to 10 with one). It is sent only in the
TRON-PRO-API-KEYrequest header, toapi.trongrid.io, and kept like the Etherscan key (the Remember toggle applies). No Etherscan key is needed for Tron. - Sampling: TronGrid returns at most 200 rows per request, so the per-address sample is capped at 200 (the log says so when the form asks for more). Native TRX/TRC-10, internal and TRC-20 transfers are fetched, latest first.
- Load older pages by block time (TRC-20 and internal rows carry no block number), with the cursor saved in the workspace.
- Sanctions and fake USDT: Tron nodes get the OFAC SDN sanctions label and flag (a dated snapshot, not a live feed) and imitation-USDT detection against Tether's official USDT TRC-20 contract. There are no other Tron labels (no exchange, bridge or mixer labels), so no exchange-deposit marks.
- Not supported on Tron: other known-address labels, USD values, bridge links, same-key/chain twins and other-chain lookups, NFTs, testnets. A Tron sample is never complete.
Who sees what:
| Provider | When | Sees |
|---|---|---|
| Etherscan | EVM scans | EVM addresses, Etherscan key, IP |
| TronGrid | Tron scans | Tron addresses, optional TronGrid key, IP |
| DefiLlama | USD on | coin ids, hour timestamps, IP |
- Nothing leaves your browser except calls to
api.etherscan.io— no backend, proxy, analytics, or third-party beacons.api.trongrid.iois contacted only after you choose Tron (see the table above). One more exception is opt-in: only while Show USD values is ticked,coins.llama.fi(DefiLlama) receives token contract ids (or native-coin ids) and hour-rounded times, never the addresses you investigate, a transaction hash or your API key. Verify it in DevTools → Network. - Vendored libraries (
vis-network,jsPDF) — no CDN — pinned with Subresource Integrity. A strict CSP limitsscript-srcto'self'andconnect-srcto the Etherscan API,coins.llama.fiandapi.trongrid.io. - The API key is never written to any export, log or filename. The query log keeps only the request parameters without the key and a SHA-256 of each response, never response bodies.
- No untrusted string reaches
innerHTML— aliases and API token symbols are rendered as DOM text nodes; the analysis is XSS-inert by construction. - OSINT ethics: the graph is a sample, not proof. Public-chain data is pseudonymous, not anonymous, and not always what it seems (spoofed token names, dust attacks, exchange omnibus wallets). Label your limits; corroborate before you conclude.
Tests are dev-only (they never run in production and aren't needed to use the app).
bun install # dev deps only (happy-dom, playwright-core)
bun test # 1011 unit + integration testsbun run ci mirrors every CI job locally (scripts/ci-local.sh). Enable the tracked pre-push hook once with:
git config core.hooksPath .githooksbun test covers the DOM-free modules (amount math, dedup keys, BFS guards, failed-tx
filtering, cycle detection, ABI decode, risk scoring, en/fr key parity, …) plus a happy-dom
integration test that drives the real main.js against a stubbed vis/fetch. CI runs the
suite and a vendor-integrity check (SRI + SHA-256) on every push.
All 64 Etherscan v2 chains (Ethereum, L2s like Base/Arbitrum/Optimism/Linea/Blast, sidechains like BNB/Polygon/Gnosis/Avalanche, Sonic, and ~30 testnets). One API key is used for every chain — Etherscan v2 is a unified multichain endpoint (but see the paid-plan note below). Each chain carries its native currency symbol (so native txs show BNB/POL/AVAX/S/… not "ETH" everywhere). Add one = a single entry in src/config.js ({id, name, explorer, native}, validated against Etherscan v2's chainlist).
Base, BNB Chain, OP Mainnet, Avalanche (and Gnosis) now require a paid Etherscan API plan (an Etherscan policy change, not a chainmap limit); with a free key the app tells you that's the cause instead of a generic error.
Tron (opt-in) is read through TronGrid, not Etherscan: see Tron. It is not one of the 64 chains above.
- Blockchain address-format patterns for the chain detector are adapted from gl0bal01's
discord-osint-assistant. - Graph rendering by vis-network;
- PDF export by jsPDF.
- OiY for the idea ;)
