Skip to main content
When seedrecover.py tests a seed candidate, it needs something to compare the derived addresses against. Normally you provide a known receiving address or master public key. If you have neither, you can use an address database — a compact on-disk lookup table built from blockchain data that lets the tool check any generated address against every address that has ever appeared on-chain.
There is no real performance penalty for using an address database. The seed search runs at roughly the same speed whether it is comparing against one address or 600 million. The main cost is the one-time effort of downloading the blockchain and building the database.

​
Pre-made address databases

Pre-built address databases for several chains are available for download: cryptoguide.tips/btcrecover-addressdbs Download the file, unzip it, then pass the full path to seedrecover.py: 
python seedrecover.py \
  --addressdb /path/to/addresses-BTC.db \
  --wallet-type bip39 \
  --mnemonic "..."
Address database files are not compatible between Python 2 and Python 3. The current master branch of BTCRecover is Python 3 only. Make sure you download the Python 3 version.

​
Database size and the --dblength parameter

The database is a fixed-size hash table. You must choose its maximum capacity before creation using --dblength, expressed as a power of 2.
  • --dblength 30 reserves space for 2^30 (~1 billion) addresses and creates an ~8 GB file. This is the default.
  • If the blockchain contains more addresses than the database can hold, the creation script will crash. Increase --dblength by 1 and retry.
  • File size depends on the maximum capacity, not the number of addresses actually stored. For smaller chains, use a smaller --dblength to avoid wasting disk space.
CoinBlockchain sizeAddressDB sizeRecommended --dblength
Bitcoin561 GB16 GB31
Bitcoin Cash155 GB4 GB29
Litecoin133 GB4 GB29
Vertcoin5 GB32 MB22
Monacoin2.5 GB32 MB22
EthereumN/A (BigQuery, ~250M addresses)4 GB29
DogecoinN/A (BigQuery, ~60M addresses)1 GB27
If you have plenty of disk space and don’t want to think about sizing, leave --dblength at the default. The resulting 8 GB file works for Bitcoin and all smaller chains.

​
Creating an address database from blockchain data

Direct blockchain parsing is supported for:
  • Bitcoin
  • Bitcoin Cash
  • Litecoin
  • Vertcoin
  • Monacoin
It does not work for Dogecoin, Verge, Zcash/Zencash, Monero, or Ethereum. Use the address list approach for those chains.
1

Ensure sufficient disk space and RAM

You need space for the full blockchain plus RAM equal to roughly double the final AddressDB size. For Bitcoin this means 16+ GB of RAM. Smaller chains require significantly less.You must use a 64-bit Python installation.
2

Install and sync a full-node client

Install the full-node client for your chosen chain and let it fully sync:A lite client (Electrum, etc.) will not work. Syncing can take one or more days. Use the -dbcache option (e.g. -dbcache 4000 for 4 GB) to speed up the initial sync.
3

Close the full-node client

Once fully synced, shut down the full-node software before running the database creation script.
4

Run create-address-db.py

Double-click create-address-db.py (rename to .command on macOS first), or run it from the terminal:
python create-address-db.py
The script reads blockchain data from the default install location. For an alternative blockchain or install path, use --datadir:
python create-address-db.py --datadir /path/to/blockchain --dblength 29
The output file addresses.db is saved in the same directory. This step takes roughly one hour for Bitcoin and uses about 4 GB of RAM and disk space.
5

Run seedrecover.py with --addressdb

python seedrecover.py \
  --addressdb ./addresses.db \
  --wallet-type bip39 \
  --mnemonic "..."
When prompted for an address in the GUI, click Cancel to use the database instead.

​
Limiting by date range

To create a database covering only a specific time window, use --blocks-startdate and --blocks-enddate (format: YYYY-MM-DD). This reduces RAM and disk space requirements and is useful if you know roughly when your wallet was active: 
python create-address-db.py \
  --blocks-startdate 2020-01-01 \
  --blocks-enddate 2021-01-01 \
  --dblength 28

​
Skipping early block files

To skip block files you know are before your date window, use --first-block-file: 
python create-address-db.py \
  --first-block-file 600 \
  --blocks-startdate 2020-01-01
--first-block-file does not warn you if the specified block file falls after the --blocks-startdate. Make sure the block number you choose actually precedes the start date.

​
Creating an address database from an address list

For chains where direct blockchain parsing is not supported (Ethereum, Dogecoin, etc.), you can build the database from a plain-text list of addresses. This is also useful when you have blockchain data from Google BigQuery or Blockchair database dumps. 
python create-address-db.py \
  --inputlist addresses.txt \
  --dblength 29
For multiple input files (e.g., BigQuery export shards stored in Google Cloud Storage), use --multifileinputlist: 
python create-address-db.py \
  --multifileinputlist file-list.txt \
  --dblength 29
To add addresses to an existing database, use --update: 
python create-address-db.py \
  --inputlist more-addresses.txt \
  --update \
  --dblength 29
Adding ~10 million addresses takes roughly one minute.

​
Address list sources

Google BigQuery — Useful SQL queries for extracting all addresses are available for Bitcoin, Ethereum, Dogecoin, Bitcoin Cash, and Litecoin in the BTCRecover documentation. Note that BigQuery data is updated every 1–2 months; check the “Last Modified” timestamp for the dataset you use. Blockchair database dumps — Blockchair distributes .tsv.gz files at blockchair.com/dumps. These compressed files can be passed directly to --inputlist without decompressing. Note that Blockchair lists only include addresses with a current balance, which differs from the BigQuery approach (which includes all addresses that ever had a balance). This can cause issues with address generation limits. Ethereum-ETL — For EVM-compatible chains with a Geth or Parity node, use ethereum-etl to export transaction data, then process it with utilities/addrListsFromETLTransactions.py to produce address lists. This approach requires several TB of disk space for the node and ETL output.

​
Verifying an address database

Use check-address-db.py to confirm that a database contains specific addresses: 
python check-address-db.py \
  --dbfilename addresses-DOGE.db \
  --checkaddresses DMQ6uuLAtNoe5y6DCpxk2Hy83nYSPDwb5T DFgLZmxFnzv2wR4GAGS3GeHvoEeSkz9ubU
Example output: 
Starting CheckAddressDB 1.9.0-CryptoGuide
Loading address database ...
Loaded 60750752 addresses from database ...
DMQ6uuLAtNoe5y6DCpxk2Hy83nYSPDwb5T Found!
DFgLZmxFnzv2wR4GAGS3GeHvoEeSkz9ubU Found!
To verify date coverage using the bundled checklist files (which contain addresses sampled at ~6-month intervals from the blockchain), use --checkaddresslist: 
python check-address-db.py \
  --dbfilename addresses-DOGE.db \
  --checkaddresslist ./addressdb-checklists/DOGE.txt

​
Using a test database

The repository includes small test databases covering 24 hours of addresses for each supported chain. These are useful for verifying your setup: 
python seedrecover.py \
  --no-dupchecks \
  --addr-limit 2 \
  --bip32-path "m/44'/28'/1'/0" \
  --big-typos 1 \
  --addressdb ./btcrecover/test/test-addressdbs/addresses-VTC-Test.db \
  --wallet-type bip39
The seed for that test (with 1 substituted for the first word): 
1 entire sniff tired miracle solve shadow scatter hello never tank side sight isolate sister uniform advice pen praise soap lizard festival connect baby

Seed recovery overview

What you need to start a seed recovery

Derivation paths and altcoins

Choose the right wallet type and path for your coin

Build docs developers (and LLMs) love

Get started for freeTalk to us