Skip to main content
Sometimes you have a backup of all your seed words but the order is wrong or unknown — for example, if words were stored without position labels, shuffled, or written across multiple locations. seedrecover.py supports this via the same tokenlist feature used for password recovery.
Descrambling is currently practical for 12-word seeds. For 24-word seeds it is feasible only when the position of at least 12 words is already known.

​
How it works

A tokenlist file lists the words you have, with anchors for words whose position you know. seedrecover.py generates all valid orderings of those words, filters by BIP39 checksum, then tests each candidate against your address. The tokenlist syntax is the same as for password recovery. See the BTCRecover tokenlist documentation for the full syntax reference. A sample tokenlist for a 12-word seed with 6 words of known position and 6 unknown is available at btcrecover/test/test-listfiles/SeedTokenListTest.txt in the repository.

​
Requirements

You must always specify both of these flags when using a tokenlist for seeds:
  • --mnemonic-length — the number of words in your seed (12 or 24)
  • --language — the BIP39 wordlist language (e.g. EN)
Supported languages correspond to the wordlist files in btcrecover/wordlists/.

​
Example: tokenlist-based descrambling

python3 seedrecover.py \
  --no-dupchecks \
  --mnemonic-length 12 \
  --language EN \
  --dsw \
  --wallet-type BIP39 \
  --addr-limit 1 \
  --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU \
  --tokenlist ./btcrecover/test/test-listfiles/SeedTokenListTest.txt
FlagPurpose
--no-dupchecksAllows the same word to appear in multiple positions during candidate generation
--mnemonic-length 12Tells the tool to generate 12-word combinations
--language ENUses the English BIP39 wordlist
--dswDisables seed word validation (required when words may appear in unexpected positions)
--wallet-type BIP39Selects the BIP39 wallet type
--addr-limit 1Checks only the first derived address per candidate
--addrsThe known receiving address to test against
--tokenlistPath to the tokenlist file

​
Debugging: listing generated candidates

You can print all seed candidates that will be tested using --listseeds (also known as --listpass in password recovery mode). This is useful for verifying your tokenlist before running a full search: 
python3 seedrecover.py \
  --no-dupchecks \
  --mnemonic-length 12 \
  --language EN \
  --dsw \
  --wallet-type BIP39 \
  --addr-limit 1 \
  --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU \
  --tokenlist ./btcrecover/test/test-listfiles/SeedTokenListTest.txt \
  --listseeds candidates.txt
This writes all generated seed candidates to candidates.txt without testing them.

​
Seedlist approach: split generation from testing

For very large candidate sets, you can split the work into two stages:
  1. Generate candidates to a file using --listseeds
  2. Test candidates from that file using --seedlist
This lets you generate once and run the testing step multiple times (for example, on a faster machine or with GPU acceleration), or distribute the testing across multiple systems.

​
Stage 1: generate candidates

python3 seedrecover.py \
  --no-dupchecks \
  --mnemonic-length 12 \
  --language EN \
  --dsw \
  --wallet-type BIP39 \
  --addr-limit 1 \
  --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU \
  --tokenlist ./btcrecover/test/test-listfiles/SeedTokenListTest.txt \
  --listseeds my-candidates.txt

​
Stage 2: test from the seedlist

python3 seedrecover.py \
  --no-dupchecks \
  --mnemonic-length 12 \
  --language EN \
  --dsw \
  --wallet-type BIP39 \
  --addr-limit 1 \
  --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU \
  --seedlist ./btcrecover/test/test-listfiles/SeedListTest.txt
Each line in the seedlist must be formatted exactly as the --listseeds output produces it. Do not manually edit the format.
Seedlist files produced by --listseeds can become very large very quickly for long candidate sets. Use this approach only when the tokenlist-direct method is too slow or when you need to reuse the candidate list.

Seed recovery overview

How seedrecover.py works and the four automatic search phases

Derivation paths and altcoins

Select the right wallet type and derivation path for your coin

Build docs developers (and LLMs) love

Get started for freeTalk to us