// system

kazumi is an autonomous agent that audits your ethereum footprint for deanon risk.

every on-chain action leaves a trail — reused addresses, cex deposits, nft markers, funding chains, ens reverse lookups. a cluster analyst can follow that trail in an afternoon and tie your "anonymous" wallet to a twitter handle, a discord, a real name, a postal address.

kazumi walks the same trail first. she hands you back the map before someone weaponizes it against you.

not a mixer. no on-chain execution, no token routing, no "private send" button that makes your funds disappear into a dark pool. kazumi is a read-only scanner.

not a tumbler. we don't break your trail. we show you where you already broke it yourself.

not an oracle. kazumi does not claim "this wallet is anonymous". that claim is impossible. she reports the visible footprint — what a motivated adversary would find if they ran the same tools.

// capabilities

| module | what it catches | severity band | |---|---|---| | reuse | same signer on multiple dapps within a narrow window, tx-pattern fingerprint overlap | low → high | | cex_ties | deposit/withdrawal paths to labeled exchanges (binance, coinbase, okx, kraken, bybit, kucoin, gate, crypto.com, gemini) | medium → critical | | clustering | common-input heuristic, co-spend graph, sibling wallet detection | medium → high | | funding_trace | recursive ancestor walk to origin cluster (N hops) | medium → high | | nft_marker | identifying collections — pfp sets, poap drops, event-gated mints | low → medium | | ens_leak | .eth reverse lookups that bind wallet to handle | medium → critical | | timing_fingerprint | activity windows that leak timezone / sleep schedule | low |

each finding returns a severity, evidence blob, and a remediation hint.

// how it works

       ┌──────────────────────────────────────────┐
       │  wallet address                          │
       └─────────────────┬────────────────────────┘
                         ▼
       ┌──────────────────────────────────────────┐
       │  kazumi scanner loop                     │
       │  (parallel module execution)             │
       └───┬────┬────┬────┬────┬────┬────┬───────┘
           ▼    ▼    ▼    ▼    ▼    ▼    ▼
         reuse cex cluster fund nft ens timing
           │    │    │    │    │    │    │
           └────┴────┴────┴────┴────┴────┘
                         ▼
       ┌──────────────────────────────────────────┐
       │  finding aggregator                      │
       │  + severity-weighted score               │
       └─────────────────┬────────────────────────┘
                         ▼
       ┌──────────────────────────────────────────┐
       │  terminal report  //  json  //  watch    │
       └──────────────────────────────────────────┘

parallel by design. each module is an independent Scanner. adding a new heuristic means implementing the interface and registering it — no ordering, no shared state, no side effects.

no data exfil. all api calls go to the etherscan endpoint you configure. no telemetry, no "anonymous usage stats", no beacon to a kazumi server.

synthetic evidence. every finding includes an evidence blob — the exact tx hash or address chain that triggered it. you can verify independently on etherscan.io.

// quickstart

install

npm install -g kazumi-sentinel

or one-shot without install:

npx kazumi-sentinel scan <wallet>

run

kazumi scan 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

expected output

  kazumi  //  ID: 0257-21
────────────────────────────────────────────────────────
  wallet   0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
  scanned  2026-04-25T18:02:00Z
  score    34/100
────────────────────────────────────────────────────────
  [HIGH]     direct cex tie — binance-14
    wallet interacts with binance-14 (0x28C6c0…1d60) in 6/50 sampled tx
    → use a dedicated deposit wallet per venue
  [MEDIUM]   heavy counterparty reuse
    0x7a250d…488d appears in 18/50 sampled tx
    → rotate wallets between frequent counterparties
  [LOW]      funding source identified
    earliest counterparty: 0xab5801…ec9b (no cex label at depth 1)
    → review the source chain depth (-d 3+) for cex or bridge ties
────────────────────────────────────────────────────────
  ▌▌▌  0257-21  ▌▌ ▌▌▌ ▌  ▌▌  ▌▌▌▌  ▌

configure your etherscan key (recommended)

free tier works (5 req/sec without key). for real use:

export KAZUMI_API_KEY="<your etherscan key>"
kazumi scan <wallet>
# or pass directly:
kazumi scan <wallet> --key <key>

get a free key at etherscan.io/myapikey. for self-hosted, point --rpc at any etherscan-v2-compatible endpoint.

// cli reference

kazumi scan <wallet> [options]

| flag | default | description | |---|---|---| | -d, --depth <n> | 3 | funding-trace depth in hops | | -r, --rpc <url> | etherscan.io | etherscan-compatible api base | | -k, --key <key> | — | etherscan api key (or env KAZUMI_API_KEY) | | --json | — | emit machine-readable json |

exit codes

| code | meaning | |---|---| | 0 | scan complete, score ≥ 50 | | 2 | scan complete, score < 50 | | 64 | invalid wallet input | | 1 | runtime / api error |

use the codes in ci — gate deployments on wallet hygiene.

// score rubric

score starts at 100. each finding subtracts a severity-weighted penalty:

| severity | penalty | typical example | |---|---|---| | low | −5 | activity burst within a timezone window | | medium | −15 | reuse across 2–3 dapps | | high | −30 | direct cex interaction | | critical | −50 | wallet funded directly from a labeled cex |

score never drops below 0. interpretation:

| score | reading | |---|---| | 80 – 100 | clean trail. no obvious public footprint. | | 50 – 79 | surface-level deanon possible with public tools. | | 20 – 49 | cluster analyst will link this wallet to an identity within an hour. | | 0 – 19 | already linked. assume your identity is known. rotate before you act. |

score is not a compliance tool. it does not say "this wallet is sanctioned" or "this wallet is safe to interact with". it only describes visibility of the footprint.

// modules (detail)

reuse

• signal. same counterparty appears across many of the wallet's recent tx.
• why it matters. one mistake on a doxxed dapp (say, opensea logged-in with twitter) propagates to every other dapp the signer touched. cluster analysts build co-activity graphs from this.
• method. sample the latest 50 tx, group counterparties (from/to), flag any that exceed a reuse threshold.
• remediation. per-venue wallets. separate signer for each dapp that touches an identity surface.

cex_ties

• signal. funding or exit path to a labeled centralized exchange hot wallet.
• why it matters. cex kyc ties wallet → legal name. 3–4 hops is enough for a subpoena-grade link.
• method. match counterparties in recent tx against a curated label set (binance, coinbase, kraken, okx, bybit, kucoin, gate, crypto.com, gemini). label set is local and editable in data/cex_labels.json.
• remediation. rotate funding through fresh wallets. route exits via dex-side paths, not direct cex deposit.

clustering

• signal. common-input heuristic + co-spend graph (planned).
• why it matters. if wallet A and wallet B appear together as inputs on the same tx, they are almost certainly the same entity. this is how chain-analysis cluster "super-wallets" form.
• method. build co-input adjacency, report cluster size + representative member.
• remediation. never co-sign across identity boundaries. if you must, use a multisig — it breaks the heuristic.

funding_trace

• signal. recursive ancestor walk — who funded you, who funded them.
• why it matters. a clean-looking wallet funded 2 hops away from a doxxed address is still doxxed.
• method. locate the wallet's earliest tx, identify the counterparty, recurse up to depth hops, flag any cex match.
• remediation. if origin is dirty, no amount of rotation downstream helps. burn the line.

ens_leak

• signal. ens reverse-resolution that maps wallet → human-readable handle.
• why it matters. .eth is a public reverse record. searching twitter for kazumi.eth often returns the owner's profile.
• method. query ens reverse resolver, match handle against known public indexes.
• remediation. unlink the primary name, transfer to a burner, or accept the link as intentional.

nft_marker

• signal. identifying collection in the wallet's holdings (bayc, punks, azuki, milady, pudgy, etc).
• why it matters. some collections are effectively identity tokens — ticketed events, dao membership, poap-like drops. holding one ties the wallet to a known human group.
• method. intersect erc-721/1155 holdings with a maintained MARKER_COLLECTIONS set.
• remediation. hold identity nfts on a separate, dedicated wallet. never combine identity + activity surfaces.

// architecture

kazumi/
├─ src/
│  ├─ index.ts              cli entry (commander)
│  ├─ types.ts              Finding, ScanResult, Scanner interfaces
│  ├─ rpc/                  etherscan rest client
│  ├─ scanner/
│  │  ├─ index.ts           scan() — parallel module dispatch + score
│  │  ├─ reuse.ts           heavy counterparty reuse
│  │  ├─ cex.ts             labeled exchange tie detection
│  │  ├─ cluster.ts         common-input cluster heuristic (stub)
│  │  └─ funding.ts         earliest funder + cex match
│  ├─ labels/               cex + protocol + nft label modules
│  └─ report/
│     └─ terminal.ts        neon-styled terminal report + ID footer
├─ data/                    label datasets (cex, protocols, nfts)
├─ tests/
├─ examples/
└─ assets/                  logo + banner

module ownership

| area | owner | |---|---| | core, cli, scoring, ci | @kazumiAgent | | src/scanner/reuse, funding | @0xryu | | src/scanner/cex, cluster | @nullshade | | src/report/ | @kohaku |

see .github/CODEOWNERS for the authoritative mapping.

// roadmap

| version | scope | status | |---|---|---| | v0.1 – v0.4 | scaffold, scoring, terminal report, ci, solana prototype | ✅ shipped | | v1.0 | ethereum rewrite — reuse / cex / funding on etherscan data | ✅ shipped | | v1.1 | clustering + ens_leak + nft_marker on real data | 🛠️ in progress | | v1.2 | timing_fingerprint + per-protocol fingerprint patterns | ⏳ planned | | v1.3 | watch mode — streaming findings via websocket | ⏳ planned | | v1.4 | json-rpc daemon + http api | ⏳ planned | | v1.5 | web dashboard — shareable scan cards | ⏳ planned | | v2.0 | multi-chain (l2s, base, arbitrum, optimism) | ⏳ planned |

// faq

is kazumi going to break my trail for me? no. kazumi tells you what's visible. making yourself invisible is a separate, harder problem and involves operational habits kazumi cannot enforce for you.

why ethereum? mature label infrastructure, public reverse-resolution via ens, and the most well-documented cex hot wallets on any chain. l2s come next (v2.0).

can i use this on a wallet i don't own? technically yes. ethically, only when the owner asked you to. kazumi reads public chain data — it doesn't let you do anything you couldn't do with etherscan. do not use findings to dox people.

false positives? file a false-positive report with wallet + module + evidence. the label set is community-maintained — we treat these as bug reports.

will there be a web ui? v1.5. until then, cli only.

does kazumi store my scans? no. all state is in-memory within a single invocation. nothing is written to disk by default.

// contributing

good first contributions:

• add a label to data/cex_labels.json with an evidence link
• add a collection address to data/marker_collections.json
• write a test case for an existing detector with a synthetic wallet
• improve a remediation message (the text shown after →)

what we will reject:

• heuristics that require closed data (paid arkham feeds, private label packs)
• anything that executes on-chain — kazumi is read-only, forever
• generic ethereum utils not tied to a deanon vector

see CONTRIBUTING.md for flow, SECURITY.md for disclosure policy.

// why

if arkham watches you, kazumi watches your trail first. she's the scanner you run before you sign anything public.