► Try it in your browser — paste a key, get the chain + checksum + cross-chain alternates, all client-side via Pyodide. No server, no telemetry.

crypto-key-classifier (classify-key / ckc)

Classify any plausible crypto-key string — BTC / ETH / SOL / Cosmos family + a dozen more chains, plus BIP-39 and Electrum mnemonics — with aggressive recovery from formatting noise, bad checksums, wrong encodings, and OCR corruption. Recommends compatible wallets and enumerates cross-chain re-encodings for shared-key families (Cosmos IBC, EVM L2s, BTC forks, Polkadot SS58).

Status: v0.6.1-pypi, shipped. 239 tests, 17 validators covering ~50 chains, hypothesis fuzz suite.

Why

If you've ever stared at a string like 0x7c13fff2d7e8... or bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh and wondered "is this an address or a private key? which chain? is the checksum valid?" — this tool answers that, fast, locally, and without leaking the key to a lookup service.

Built for the recovery / forensics / support-ticket triage case: someone hands you a string and you need to (a) figure out what it is, (b) tell them what wallets will accept it, and (c) cross-check it against related chains they might also own.

Install

pip install crypto-key-classifier

classify-key --help

Requires Python ≥ 3.10. Dependencies: base58, pycryptodome.

Development install

For hacking on the source:

git clone https://github.com/JordanNewell/crypto-key-classifier.git
cd crypto-key-classifier
pip install -e ".[dev]"   # adds pytest, hypothesis, ruff, pyright

In action

Usage

# Classify one key — rich multi-line output (default for single input)
classify-key 0x7c13fff2d7e8b1f7b8e1d8a1f3c5b8a1f3c5b8a1

# Batch — one-line-per-key (default for 2+ inputs)
classify-key addr1.txt addr2.txt
classify-key --file keys.txt
cat keys.txt | classify-key

# JSON for scripting — pipe to jq
classify-key --json addr.txt | jq '.[] | .best_guess'

# Narrow to specific chains
classify-key --chains btc,eth,sol <input>

# Filter low-confidence matches
classify-key --min-confidence 80 <input>

# Show the repair trace (what mutations recovered a corrupted input)
classify-key --explain <input>

# Print full private keys (DANGEROUS — read the Safety section)
classify-key --no-mask <input>

Validator coverage (17 validators, ~50 chains)

The Cosmos HRP swap (why this tool exists)

The same Ed25519 private key underlies every Cosmos SDK chain. Decode the bech32 once, re-encode with a different human-readable prefix (HRP), and you have a valid address on every chain in the family:

$ classify-key cosmos1... --json | jq '.[0].cross_chain_alternates | length'
20

Twenty chains, one key. If you've ever recovered an ATOM wallet and wondered "do I also own the OSMO/JUNO/AKT at the matching address?" — yes, you do. This tool enumerates them.

The same pattern applies to EVM (11 L2s from one address) and BTC forks (LTC/DOGE from one WIF).

Recovery pipeline

Each input runs through three stages:

1. Preprocess — strips whitespace, normalizes confusables (O→0, l→1), handles case folds, removes invisible characters, copes with copy-paste artifacts.
2. Validate — for each of the 17 validators, shape-match (length/charset) → strict validate (checksum, prefix, structure). Short-circuits on first checksum_status: valid match.
3. Repair (optional) — if nothing matches clean, generate aggressive candidates: OCR substitutions, encoding variants (hex↔base58↔base64), Levenshtein word fixes for mnemonics. Cap to bound runtime.

classify-key --explain <input> shows the repair trace so you can see what was wrong and what fix recovered it.

Safety

• Default masking for private keys — WIF / seed phrases / secret keys print as bc1q…wlh (8 chars masked) unless you pass --no-mask. Never accidentally leak a key to your terminal scrollback.
• Zero network calls — pure local, no telemetry, no key material leaves the process.
• Public test vectors only in tests/fixtures/ — no real mainnet keys in the repo.
• --no-mask prints a warning to stderr before any output. Do not pipe --no-mask output to logs, cloud storage, or LLM prompts.

Development

pip install -e ".[dev]"

# Run the full suite (239 tests)
pytest

# Property tests via hypothesis
pytest tests/fuzz

# Lint + typecheck
ruff check .
pyright

Validators auto-discover via src/ckc/validators/__init__.py — drop a new foo.py with a Validator subclass exposing chain, formats, shape_match, and validate, and it joins the pipeline on next run.

Changelog

See CHANGELOG.md for releases v0.1.0-mvp → v0.6.1-pypi.

Community

• Contributing — dev setup, validator recipe, code style, PR expectations
• Code of Conduct — Contributor Covenant 2.1
• Security — report vulnerabilities privately, not via public issues

License

MIT © Jordan Newell