seedrecover.py takes a seed phrase with one or more mistakes and searches for the correct seed. It is designed for situations where you have an intact physical seed backup but it produces an empty wallet or throws an “invalid seed” error — indicating a transcription mistake.
What you need
Before starting, gather:- Your best guess at the seed phrase — even with mistakes, you need most of the words.
- One of the following to verify candidate seeds against:
- An Electrum wallet file, or
- Your master public key (xpub), or
- A receiving address generated by the wallet (earlier addresses are better), or
- An Address Database if you have none of the above.
Automatic search phases
When you runseedrecover.py with default settings, it automatically runs four search phases in order:
- Single typo — one word has a typo (wrong letters within the same word)
- Two typos, one wrong word — two typos, one of which could be a completely wrong BIP-39 word
- Three typos, one wrong word — three typos, one could be a completely wrong BIP-39 word
- Two wrong words — two of your words could be completely different BIP-39 words
Run seedrecover.py
Option 1 — GUI (easiest): Double-click Replace
seedrecover.py. On macOS, first rename it to seedrecover.command. A series of dialog boxes will guide you through selecting your wallet type, entering your xpub or address, and entering your seed guess.Option 2 — Command line: Open a terminal in the BTCRecover directory and run:YOUR_ADDRESS with a receiving address from your wallet, and fill in your seed words — including your best guess at any words you are unsure about.The
--addr-limit argument controls how many addresses per account BTCRecover generates to check. If your receiving address was the 7th address you ever created, use at least --addr-limit 10 to be safe. A higher limit is slower but less likely to miss the seed.Wait for results
BTCRecover displays a progress bar with an ETA. The four automatic phases run back to back. If the correct seed is found, it is printed to the terminal:If no seed is found after all phases, the search ends without a result. You may need to reconsider which words are wrong, or use additional options to expand the search.
Example commands
The commands below use test addresses that ship with BTCRecover. They find a result immediately and are safe to run as-is.Bitcoin (BIP-39)
One missing word, Native Segwit address, address generation limit of 5:Cardano (Shelley)
Seed from a Ledger Nano, one missing word, using a base address:Ethereum Validator seeds
Use the validator’s public key (signing key) in place of an address:Electrum (Legacy seeds)
One wrong word, Electrum V1 seed, address generation limit of 2:LND aezeed wallets
One missing word, address generation limit of 5. Add--passphrase-arg "YOUR PASSPHRASE" if your seed uses a custom passphrase:
Polkadot (Substrate)
One missing word, blank derivation path:Helium
One missing word:Stellar (XLM)
One wrong word, address generation limit of 2:Tron
One missing word:Stacks
One missing word, checks the first 10 accounts:SLIP-39 share recovery
Fix a damaged SLIP-39 share (up to 2 typos):Useful options
| Option | Description |
|---|---|
--wallet-type TYPE | Specify wallet type: bip39, electrum2, cardano, tron, xlm, polkadotsubstrate, etc. |
--addrs ADDRESS | A receiving address from the wallet (space-separated for multiple) |
--addr-limit N | Number of addresses to generate per account for checking (default: 1) |
--mnemonic "WORDS" | Your best guess at the seed phrase |
--passphrase-arg PASS | BIP-39 passphrase (25th word), if applicable |
--big-typos N | Allow up to N completely wrong BIP-39 words (slow — use sparingly) |
--typos N | Allow up to N character-level typos per word |
--substrate-path PATH | Derivation path for Polkadot/Substrate wallets |
--no-eta | Suppress ETA display (useful for some wallet types) |
If you do not have any address or xpub from your wallet, you can create an Address Database from the blockchain. There is no significant performance penalty — it just requires some setup time.