BTC Recover Crypto Guide wallet password and seed recovery tools open source

In this article, we will take a detailed look at the open source password recovery tools and wallet seed phrases in the Crypto Deep Tools repository, and we will also discuss the situation when you accidentally lost or forgot part of your mnemonic or made a mistake while decrypting it. (So you either see an empty wallet or get an error that your seed is invalid) For wallet password or passphrase recovery, it is primarily useful if you have a reasonable idea about what your password might be.

BTCRecover is an open source wallet password and seed recovery tool.

Your best bet is to follow the Installing BTCRecover guide, then read the “Quick Start” for the recovery type you want. (Or look at some usage examples)

Usage Examples

This page provides links to a number of examples tht demonstrate how the setup and syntax to use BTCRecover in a number of different recovery scenarios. (Generally with a corresponding YouTube video)

The commands given can be pretty much copy/pasted as-is to allow you to recreate the examples given in the YouTube video.

Note: Some changes may be required based on your platform, often simple things like using “python” vs “python3”.

Python Version: Many of these videos were created using different forks of BTCRecover. The resources and commands here may differ slightly, but are designed to work with this fork under Python3.

Seed Recovery

Basic Seed Recoveries (Demonstrates the basic commands that you would use for a recovery with various types of wallets)


Basic Password/Passphrase Recoveries

The idea is that, if you are running this tool on Windows, you can directly copy/paste any of these examples. (They all use the same seeds and addresses that are in the automatic tests)

They will all find a result almost straight away.

Seed Based Recovery Notes

Notes Seedrecover.py has been set up so that the defaults should get a result for the majorty of simple “invalid menmonic” or “invalid seed” type errors. (Eg: Where you have an intact seed backup that has a typo in it)

It will search all account types for the supported cryptocurrencies, on all common derivation paths.

It will automatically run through four search phases that should take a few hours at most. 1. Single typo 2. Two typos, including one where you might have a completely different BIP39 word 3. Three typos, including one where you might have a completely different BIP39 word 4. Two typos that could be completely different words.

Fully Supported wallets (For supported cryptocurrencies)

  • Hardware Wallets
    • Ledger Nano X and S
    • Trezor One and T
    • Keepkey
    • Safepal
    • Coldcard
    • Bitbox02
    • Keystone
    • Cobo Vault
    • Ellipal
    • CoolWallet S (You will need both convert the seed numbers to BIP39 seed words and to use the –force-p2sh argument for Bitcoin and Litecoin…)
  • Software Wallets
    • Electrum – Both V1 and V2 Seeds (This includes forks like Electrum-LTC, Electron-Cash, etc)
    • Coinomi
    • Wasabi
    • Edge Wallet
    • Mycelium
    • Exodus
    • Trust Wallet
    • Metamask (Including clones like Binance Chain Wallet Extension)

Wallets with Compatibility Issues(Due to not following derivation standards…)

  • Atomic Wallet. (Non-Standard derivation for ETH (And all ERC20 tokens), needs to be used with the --checksinglexpubaddress, XRP)
  • Abra Wallet. (Non-Standard seed format, first word is Non-BIP39 “at”, the last 12 are BIP39 (and checksum) but unable to reproduce derivation)

Let’s move on to the experimental part:

Let’s open [TerminalGoogleColab].

Let’s use the repository «17BTCRecoverCryptoGuide».

git clone https://github.com/demining/CryptoDeepTools.git

cd CryptoDeepTools/17BTCRecoverCryptoGuide/

ls
BTC Recover Crypto Guide wallet password and seed recovery tools open source

Install all the packages, modules and libraries we need

pip3 install -r requirements.txt
BTC Recover Crypto Guide wallet password and seed recovery tools open source
BTC Recover Crypto Guide wallet password and seed recovery tools open source

Using the lscpu command to find out the processor architecture of Google Colab

lscpu
BTC Recover Crypto Guide wallet password and seed recovery tools open source

PyOpenCL Installation for Linux

sudo apt install python3-pyopencl
BTC Recover Crypto Guide wallet password and seed recovery tools open source

Testing your System

python3 -m btcrecover.test.test_passwords -v GPUTests
BTC Recover Crypto Guide wallet password and seed recovery tools open source

Basic Bitoin Recoveries

Note: Most of the time you can just run seedrecover.py, even simply double click it and follow the graphical interface.

With a Native Segwit Address – One missing word, address generation limit of 5. (So address needs to be in the first 5 addresses in that account)

python3 seedrecover.py --wallet-type bip39 --addrs bc1qv87qf7prhjf2ld8vgm7l0mj59jggm6ae5jdkx2 --mnemonic "element entire sniff tired miracle solve shadow scatter hello never tank side sight isolate sister uniform advice pen praise soap lizard festival connect" --addr-limit 5
BTC Recover Crypto Guide wallet password and seed recovery tools open source

With a P2SH Segwit Address – One missing word, address generation limit of 5. (So address needs to be in the first 5 addresses in that account)

python3 seedrecover.py --wallet-type bip39 --addrs 3NiRFNztVLMZF21gx6eE1nL3Q57GMGuunG --mnemonic "element entire sniff tired miracle solve shadow scatter hello never tank side sight isolate sister uniform advice pen praise soap lizard festival connect" --addr-limit 5
BTC Recover Crypto Guide wallet password and seed recovery tools open source

Basic Cardano Recoveries

For Cardano recovers, see the notes here as well. You can use any Shelley-Era base or stake addresses. (Byron-Era not supported)

Seed from a Ledger Nano, missing one word, using a standard base address. (Address generation limit isn’t appliable in Cardano)

python3 seedrecover.py --wallet-type cardano --addrs addr1qyr2c43g33hgwzyufdd6fztpvn5uq5lwc74j0kuqr7gdrq5dgrztddqtl8qhw93ay8r3g8kw67xs097u6gdspyfcrx5qfv739l --mnemonic "wood blame garbage one federal jaguar slogan movie thunder seed apology trigger spoon basket fine culture boil render special enforce dish middle antique"

Seed from a Trezor, missing one word, using a standard base address. (Address generation limit isn’t appliable in Cardano)

python3 seedrecover.py --wallet-type cardano --addrs addr1q8k0u70k6sxkcl6x539k84ntldh32de47ac8tn4us9q7hufv7g4xxwuezu9q6xqnx7mr3ejhg0jdlczkyv3fs6p477fqxwz930 --mnemonic "ocean kidney famous rich season gloom husband spring convince attitude boy"

Seed from Yoroi, Adalite or Daedalus (Working as a software wallet), using a standard stake address

python3 seedrecover.py --wallet-type cardano --addrs stake1uxztdzzm4ljw9a0qmgregc8efgg56p2h3kj75kc6vmhfj2cyg0jmy --mnemonic "cave table seven there limit fat decorate middle gold ten battle trigger luggage demand"

Basic Tron Recoveries

One missing word, address generation limit of 1. (So address needs to be in the first account)

python3 seedrecover.py --wallet-type tron --addrs TLxkYzNpMCEz5KThVuZzoyjde1UfsJKof6 --mnemonic "have hint welcome skate cinnamon rabbit cable payment gift uncover column duck scissors wedding decorate under marine hurry scrub rapid change roast print arch" --addr-limit 1

Basic Helium Recoveries

One missing word

python3 seedrecover.py --wallet-type helium --addrs 13hP2Vb1XVcMYrVNdwUW4pF3ZDj8CnET92zzUHqYp7DxxzVASbB --mnemonic "arm hundred female steel describe tip physical weapon peace write advice"

Basic Polkadot(Substrate) Recoveries

One missing word, blank secret derivation path

python3 seedrecover.py --wallet-type polkadotsubstrate --addrs 13SsWBQSN6Se72PCaMa6huPXEosRNUXN3316yAycS6rpy3tK --mnemonic "toilet assume drama keen dust warrior stick quote palace imitate music disease"

One missing word, secret derivation path of “//hard/soft///btcr-test-password” The soft/hard derivation path is passed to the program via the –substrate-path argument and the password is treated the same as a passphrase (Without the leading ///)

python3 seedrecover.py --wallet-type polkadotsubstrate --addrs 12uMBgecqfkHTYZE4GFRx847CwR7sfs2bTdPbPLpzeMDGFwC --mnemonic "toilet assume drama keen dust warrior stick quote palace imitate music disease" --passphrase-arg btcr-test-password --substrate-path //hard/soft

Basic Stacks Recoveries

One missing word, address generation limit of 10. (So will check the first 10 “accounts” for a given seed)

python3 seedrecover.py --wallet-type stacks --addrs SP11KHP08F4KQ06MWESBY48VMXRBK5NB0FSCRP779 --mnemonic "hidden kidney famous rich season gloom husband spring convince attitude boy" --addr-limit 10

Descrambling 12 word BIP39 Seeds (Demonstrates Using a TokenList for unscramblng seeds for Electrum Legacy, Electrum Segwit, BIP39 Bitcoin and BIP39 Ethereum)

Descrambling 12 Word Seeds

Three types of token files are provided for these tests. Token files that will find the result on their first check, token files that will find the result as the last possible combination and those which will find it at some point inbetween.

The idea is that these allow you to quickly verify that things are working (finding on the first result), get an idea for how long a full run might take (last result) and also try something representative of a real world situation.

If you are just descrambing a 12 word seed, there isn’t much point running without –no-eta, as the number of seeds to be tested can be easily worked out and the seed generator can easily keep up with at least 48 threads.

Note: The YouTube video and examples were made before OpenCL acceleration was added to Blockchain.com wallets and can give a 2x performance improvement. (See GPU Accleration for more info)

Performance

On a 48 core Linode you can expect to… * Descramble a 12 word Electrum seed in less than 15 minutes… * Descramble a 12 word BIP39 seed in less than 50 minutes…

You can expect things to take about 5 times this long on a current (mid 2020), mid-range CPU.

Electrum

Legacy Wallet (Last Result)

Using Tokenlist lastcombination_electrum.txt

1 2 3 4 5 6 7 8 9 10 11 12book fit fly ketchup also elevator scout mind edit fatal where rookie

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --addr-limit 1 --addrs 1CU62HPowYSxhHiiNu1ukSbMjrkGj4x52i --tokenlist ./docs/Usage_Examples/2020-05-02_Descrambling_a_12_word_seed/lastcombination_electrum.txt --wallet-type electrum2

Segwit Wallet

Using Tokenlist randomcombination_electrum.txt

1 2 3 4 5 6 7 8 9 10 11 12social shoe spin enlist sponsor resource result coffee ocean gas file paddle

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --wallet-type electrum2 --addr-limit 1 --addrs bc1qtylwmarke39nysxepdx5xzfatvrlel5z8m0jx2 --tokenlist ./docs/Usage_Examples/2020-05-02_Descrambling_a_12_word_seed/randomcombination_electrum.txt --bip32-path "m/0'/0"

BIP39

Ethereum Address (Default derivation path for Trezor, MEW)

Using Tokenlist randomcombination_bip39.txt

1 2 3 4 5 6 7 8 9 10 11 12boy hidden kidney famous spring convince rich season gloom ocean husband attitude

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --wallet-type ethereum --addr-limit 1 --addrs 0x66F9C09118B1C726BC24811a611baf60af42070A --tokenlist ./docs/Usage_Examples/2020-05-02_Descrambling_a_12_word_seed/randomcombination_bip39.txt --bip32-path "m/44'/60'/0'/0"

Legacy BTC Address (First Result)

Using Tokenlist firstcombination_bip39.txt

1 2 3 4 5 6 7 8 9 10 11 12boy attitude convince spring husband gloom season rich famous kidney hidden ocean

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --wallet-type BIP39 --addr-limit 1 --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU --tokenlist ./docs/Usage_Examples/2020-05-02_Descrambling_a_12_word_seed/firstcombination_bip39.txt

Legacy BTC Address (Last Result)

Using Tokenlist lastcombination_bip39.txt

1 2 3 4 5 6 7 8 9 10 11 12ocean hidden kidney famous rich season gloom husband spring convince attitude boy

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --wallet-type BIP39 --addr-limit 1 --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU --tokenlist ./docs/Usage_Examples/2020-05-02_Descrambling_a_12_word_seed/lastcombination_bip39.txt

Litecoin Native Segwit Address (Seed with Positional Anchors for known words, last word as any valid BIP39 word starting with ‘B’)

Using Tokenlist fixedwords_bip39.txt

1 2 3 4 5 6 7 8 9 10 11 12^1^ocean ^2^ocean ^3^ocean ^1^hidden ^2^hidden ^3^hidden ^1^kidney ^2^kidney ^3^kidney ^4^famous ^5^rich ^6^season gloom husband spring convince attitude baby bachelor bacon badge bag balance balcony ball bamboo banana banner bar barely bargain barrel base basic basket battle beach bean beauty because become beef before begin behave behind believe below belt bench benefit best betray better between beyond bicycle bid bike bind biology bird birth bitter black blade blame blanket blast bleak bless blind blood blossom blouse blue blur blush board boat body boil bomb bone bonus book boost border boring borrow boss bottom bounce box boy bracket brain brand brass brave bread breeze brick bridge brief bright bring brisk broccoli broken bronze broom brother brown brush bubble buddy budget buffalo build bulb bulk bullet bundle bunker burden burger burst bus business busy butter buyer buzz

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --wallet-type BIP39 --addr-limit 1 --addrs ltc1q9srpp39hev6dpsxjjp8t5g0m3z7509vc9llalv --tokenlist ./docs/Usage_Examples/2020-05-02_Descrambling_a_12_word_seed/fixedwords_bip39.txt --bip32-path "m/84'/2'/0'/0"

Multi-Device Descrambling 12 word Seed with Extra words (Demonstrates “Required” Anchors, “Positional” Anchors and Spreading Work Accross Multiple Devices)

“Required” Anchors, “Positional” Anchors and Spreading Work Accross Multiple Devices

YouTube Video can be found here: TBC

Background

In addition to being able to simply descramble a BIP39 seed using a tokenlist of potential words, BTCRecover can also be used in a situation where you may know the position of some words while also having additional decoy words in a seed phrase.

Example tokenlist in use: tokenlist.txt

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17+ ^1^ocean + ^2^hidden + ^3^kidney famous + ^5^rich + ^6^season + ^7^gloom husband spring + ^10^convince + ^11^attitude + ^12^boy glove section chunk brick sauce

For larger recovery jobs, BTCRecover also allows you to spread the workload over multiple devices. It’s important to understand that the process that BTCRecover uses is deterministic what this means in simple terms is that every time you run BTCRecover, it will search through potential passwords/passphrases in exactly the same order, every single time. The implication of this is that simply running it on two devices at the same time, without using the –workers command, will simply be doing the identical work twice…

Fortunately, you can split a search up into slices and assign these slices to different devices. The mechanism for this is extremely simple, basically assigning passwords in a “round robin” scheduling style. (eg: If the work is split up into three slices for three devices, each device will process every 3rd password) There is also the ability to assign multiple time slices to a single device in situations where one device may be multiple times faster than the others.

So let’s consider the example of two devices, PC1 and PC2. In this example, PC1 is twice as powerful as PC2, so will be assigned 2/3 of the work, while PC2 will be assigned 1/3.

Practical Limits

Working out how many potential passwords there are in a situation like this is quite straight forward.

For example, if you have a list of 20 words and know the postition of 3 of them within the 12 word seed, then there will be:

17 * 16 * 15 * 14 * 13 * 12 * 11 * 10 * 9 = 8,821,612,800 possible seeds (Very do-able in a few days depending on your CPU power available)

Running BTCRecover

Both PCs will need BTCRecover installed and both use the identical command, with the exception of the –worker command which is different for each PC. (We can just ignore the fact that this tokenlist only produces a very small set to test)

The devices don’t need to be running the same operating system, nor do they need to communicate with each other in any way…

Command on PC 1

So we want to assign work slices 1 and 2 to PC1

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --wallet-type BIP39 --addr-limit 1 --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU --tokenlist ./docs/Usage_Examples/2020-05-23_multi_device_descrambling_12_word_seed_with_extras/tokenlist.txt
 --no-eta --worker 1,2/3

Command on PC 2

And work slice 3 to PC2

Command

python3 seedrecover.py --no-dupchecks --mnemonic-length 12 --language EN --dsw --wallet-type BIP39 --addr-limit 1 --addrs 17GR7xWtWrfYm6y3xoZy8cXioVqBbSYcpU --tokenlist ./docs/Usage_Examples/2020-05-23_multi_device_descrambling_12_word_seed_with_extras/tokenlist.txt
 --no-eta --worker 3/3

The Outcome…

In this example, the correct seed phrase is found by PC2. Since there is no communication between the devices, PC1 will continue searching until it has exhausted the search space.

This also highlights that you need to pay careful attention to what you are doing when using this command. If you accidentally forget to assign a work share to a PC, or assign the same shares twice, BTCrecover will have no way to know this has occured and no result will be found if the correct password would have occured in the untested share.

Closing Thoughts

Using the –no-eta command can be useful in situations like this as it will show you the current speed at which a device is checking passwords. It will also start immediately. (Which can be good if you are paying for cloud server time)

One way that it an be useful to use this command is if you have already started a password search on your PC and know how many passwords will need to be checked, it can speed things up to run with –no-eta and just manually work out how long things will take.

If you have started doing a seed recovery on a single device and want to move to a multi-device setup, but don’t want to re-check the passwords already tested on a single device, you can take note of how many passwords the single device had tested and just use the –skip command when restarting the test across multiple devices.


Grouping words together in tokenlist based seed recoveries (Demonstrates descrambling a 24 word seed where there several groups of words known to follow one another, but the position of these groups within the seed is unknown)

Grouping words together in tokenlist based seed recoveries

Background

Sometimes there are recoveries where someone may have either written their seed in such a way that they are unsure of the order, or split the backup in to multiple parts. Either way, this can mean that are words grouped together in such a way that their relative ordering is known, but the position of these words within the larger seed is not.

In situations like this, you can use a single comma character , (No space, just a single comma) for words within a tokenlist to indicate that words must be used together, in the provided order. This is similar to the “relative anchor” feature, but is both far more efficient and also allows for multiple word groupings.

Grouped word tokens can also be used in conjunction with other types of anchors, positional, etc.

Using these tokens also means that the number of tokens will no longer equal the mnemonic length (as it typically does for descrambling with single word tokens) so you can also make use of the --min-tokens and --max-tokens arguments to specify the minimum number of tokens that should be tried for any given seed guess. (A comma separated group of words counts as a single token)

Like with seed descrambling, the ceiliing for this sort of recovery is based off the number of tokens, generally (without positional anchors) there will be max-tokens! (max-tokens factorial) possible seeds to check.

Example

The following example uses the following tokenlist:

1 2 3 4 5 6 7 8 9 10 11 12^basic,dawn,renew,punch,arch,situate arrest,question,armor hole,lounge,practice resist zoo,zoo,zoo indicate,call lens,group,empty zoo husband verify,eternal,injury battle,satoshi brother,damp,this

You can see in this tokenlist that there are a few blocks of tokens that we are sure are in the correct order, (Including a positional anchor for one of the groups of seed words) as well as a few extra/single words.

And is run with the following command (Will find a result in a few seconds)

python3 seedrecover.py --tokenlist ./docs/Usage_Examples/2022-04-02_Seed_Tokenlist_TokenBlocks/tokengroups_tokenlist.txt --mnemonic-length 24 --language en --wallet-type bip39 --addrs 1PTcESpqrmWePYB5h18Ni11QTKNfMkdSYJ --dsw --addr-limit 10 --max-tokens 9 --min-tokens 8

The correct seed is: basic dawn renew punch arch situate resist indicate call lens group empty brother damp this verify eternal injury arrest question armor hole lounge practice

And as you can see, this is made up of some of the token-groups included in the tokenlist file above.


Password Recovery

Basic Password Recoveries (Demonstrates the basic commands that you would use for a recovery with various types of wallets)

Basic Password/Passphrase Recoveries

None of these examples are concerned with arguments that you would use for different types of typos, tokenlists, etc.

The idea is that, if you are running this tool on Windows, you can directly copy/paste any of these examples. (They all use the same seeds and addresses that are in the automatic tests)

They will all find a result almost straight away.

Basic Passwordlist used in basic examples below

1 2 3 4 5btcr-test-password btcr-test-password:p2pkh btcr-test-password:p2wpkh btcr-test-password:p2wpkh-p2sh btcrtestpassword2022

BIP38 Encrypted Paper Wallet Recovery.

Notes BIP38 wallets are encrypted via sCrypt, so will be very slow to brute-force. GPU acceleration for these wallets is available, but doesn’t offer much of a performance boost unless you have multiple GPUs or a particularly powerful GPU relative to your CPU… (Or some kind of dedicated OpenCL accelerator)

Supported wallets

And just about any other BIP38 encrypted private keys.

Commands

For Bitcoin (No coin needs to be specified, Bitcoin is checked by default)

python3 btcrecover.py --bip38-enc-privkey 6PnM7h9sBC9EMZxLVsKzpafvBN8zjKp8MZj6h9mfvYEQRMkKBTPTyWZHHx --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

For Litecoin

python3 btcrecover.py --bip38-enc-privkey 6PfVHSTbgRNDaSwddBNgx2vMhMuNdiwRWjFgMGcJPb6J2pCG32SuL3vo6q --bip38-currency litecoin --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

For Dash

python3 btcrecover.py --bip38-enc-privkey 6PnZC9Snn1DHyvfEq9UKUmZwonqpfaWav6vRiSVNXXLUEDAuikZTxBUTEA --bip38-currency dash --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

BIP39 Passphrase Protected Wallets & Electrum “Extra Words”

Notes The language used to refer to a BIP39 passpharse can vary betwen vendors. Sometimes it is talked about as a “25th word”, other times a “plausible deniability passphrase” or sometimes just as “passphrase”. Just note that this is different from your wallet password or PIN.

The most common symptom of you having an error in your BIP39 passphrase is that your seed+passhrase will produce a set of completely empty accounts, with no balance or transaction history. (Every BIP39 passphrase is valid, so you will not get any kind of error message)

While BIP39 seed recovery can benefit from GPU acceleration, this is currently not the case for recovering a BIP39 passphrase.

All of the example commands below have the address generation limit set to 10, so the address they are searching for needs to be within the first 10 addresses in the wallet.

Supported wallets

  • Most hardware wallets that support BIP39/44
    • Trezor (One and T)
    • Ledger Nano (S and X)
    • Keepkey
    • Coldcard
    • Bitbox02
    • Cobo Vault Pro
  • Most Software Wallets that support BIP39/44
    • Wasabi Wallet (Wasabi refers to this as your wallet password)
    • Samourai Wallet
    • Coinomi
    • Mycelium
    • Zillet (Referrs to BIP39 passphrase as a “password based” wallet type)
    • Electrum
    • Exodus

Commands

Basic Bitcoin Command, so no need to specify --wallet-type This will support all Bitcoin address types (Legacy, Segwit or Native Segwit) without the need to add any additional parameters.

python3 btcrecover.py --bip39 --addrs 1AmugMgC6pBbJGYuYmuRrEpQVB9BBMvCCn --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "certain come keen collect slab gauge photo inside mechanic deny leader drop"

Basic Bitcoin Electrum Wallet Command. These aren’t BIP39, so need to use --wallet-type electrum2 This will support both Legacy and Segwit Electrum wallets without any additional parameters. (It will also work with most Electrum Altcoin clones)

python3 btcrecover.py --wallet-type electrum2 --addrs bc1q6n3u9aar3vgydfr6q23fzcfadh4zlp2ns2ljp6 --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "quote voice evidence aspect warfare hire system black rate wing ask rug"

Basic Ethereum Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)

python3 btcrecover.py --wallet-type ethereum --addrs 0x4daE22510CE2fE1BC81B97b31350Faf07c0A80D2 --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Zilliqa Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)This will support all address types (Base16 and Bech32) without the need to add any additional parameters.

Note: Zilliqa seed recovery can’t be used as the basis for recovering a Ledger Nano seed/passphrase at this time.

python3 btcrecover.py --wallet-type zilliqa --addrs zil1dcsu2uz0yczmunyk90e8g9sr5400c892yeh8fp --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Bitcoin Cash Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) This will accept either Cashaddres or Legacy style addresses… This will also work for BCH forks like BSV…

python3 btcrecover.py --wallet-type bch --addrs bitcoincash:qqv8669jcauslc88ty5v0p7xj6p6gpmlgv04ejjq97 --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Cardano, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) For Cardano recovers, see the notes here as well. This will accept either base or stake addresses… (Byron-Era addresses are not supported))

python3 btcrecover.py --wallet-type cardano --addrs addr1q90kk6lsmk3fdy54mqfr50hy025ymnmn5hhj8ztthcv3qlzh5aynphrad3d26hzxg7xzzf8hnmdpxwtwums4nmryj3jqk8kvak --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "ocean hidden kidney famous rich season gloom husband spring convince attitude boy"

Basic Dash Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)

python3 btcrecover.py --wallet-type dash --addrs XuTTeMZjUJuZGotrtTPRCmHCaxnX44a2aP --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Dogecoin Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)

python3 btcrecover.py --wallet-type dogecoin --addrs DSTy3eptg18QWm6pCJGG4BvodSkj3KWvHx --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Vertcoin Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) This will support all address types (Legacy, Segwit or Native Segwit) without the need to add any additional parameters.

python3 btcrecover.py --wallet-type vertcoin --addrs Vwodj33bXcT7K1uWbTqtk9UKymYSMeaXc3 --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Litecoin Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) This will support all address types (Legacy, Segwit or Native Segwit) without the need to add any additional parameters.

python3 btcrecover.py --wallet-type litecoin --addrs LdxLVMdt49CXcrnQRVJFRs8Yftu9dE8xxP --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Monacoin Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) This will support all address types (Legacy, Segwit or Native Segwit) without the need to add any additional parameters.

python3 btcrecover.py --wallet-type monacoin --addrs MHLW7WdRKE1XBkLFS6oaTJE1nPCkD6acUd --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic DigiByte Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) This will support all address types (Legacy, Segwit or Native Segwit) without the need to add any additional parameters.

python3 btcrecover.py --wallet-type digibyte --addrs DNGbPa9QMbLgeVspu9jb6EEnXjJASMvA5r --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic GroestleCoin Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) This will support all address types (Legacy, Segwit or Native Segwit) without the need to add any additional parameters.

Note: This needs the groestlecoin_hash module to be installed…

python3 btcrecover.py --wallet-type groestlecoin --addrs FWzSMhK2TkotZodkApNxi4c6tvLUo7MBWk --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Ripple Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)

python3 btcrecover.py --wallet-type ripple --addrs rwv2s1wPjaCxmEFRm4j724yQ5Lh161mzwK --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "cable top mango offer mule air lounge refuse stove text cattle opera"

Basic Tron Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)

python3 btcrecover.py --wallet-type tron --addrs TGvJrj5D8qdzhcppg9RoLdfbEjDYCne8xc --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "have hint welcome skate cinnamon rabbit cable payment gift uncover column duck scissors wedding decorate under marine hurry scrub rapid change roast print arch" 

Basic Polkadot(Substrate) Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)

This command will search for the correct “secret derivation path”

python3 btcrecover.py --wallet-type polkadotsubstrate --addrs 12uMBgecqfkHTYZE4GFRx847CwR7sfs2bTdPbPLpzeMDGFwC --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "toilet assume drama keen dust warrior stick quote palace imitate music disease" --substrate-path "//hard/soft"

Basic Stacks Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied) This example also has the address generation limit set to 10, so will check the first 10 “accounts” for a given seed+passphrase.

python3 btcrecover.py --wallet-type stacks --addrs SP2KJB4F9C91R3N5XSNQE0Z3G34DNJWQYTP3PBJTH --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --mnemonic "ocean hidden kidney famous rich season gloom husband spring convince attitude boy" --addr-limit 10

Brainwallets

Notes Brainwallets are a very old (and very unsafe) type of wallet. Given this, most of them still produce addresses based on “uncompressed”

Supported wallets

Sha256(Passphrase) Wallets

Commands

Basic Bitcoin Command (Will check both compressed and uncompressed address types, even though in this example this is a compressed address)

python3 btcrecover.py --brainwallet --addrs 1BBRWFHjFhEQc1iS6WTQCtPu2GtZvrRcwy --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Bitcoin Wallet, but set to only check uncompressed addresses. (Only use this for VERY old wallets that you are sure aren’t a compressed address, though also consider that uncompressed is the default… Only gives a small speed boost)

python3 btcrecover.py --brainwallet --addrs 1MHoPPuGJyunUB5LZQF5dXTrLboEdxTmUm --skip-compressed --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

P2SH Bitcoin Wallet (Like the kind you would get of something like segwitaddress.org, as of 2021, these are all compressed type addresses, so can skip checking uncomrpessed ones…)

python3 btcrecover.py --brainwallet --addrs 3C4dEdngg4wnmwDYSwiDLCweYawMGg8dVN --skip-uncompressed --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Bech32 Bitcoin Wallet. (From segwitaddress.org)

python3 btcrecover.py --brainwallet --addrs bc1qth4w90jmh0a6ug6pwsuyuk045fmtwzreg03gvj --skip-uncompressed --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Litecoin Wallet (From liteaddress.org – These are all uncompressed with no option to use compressed) No extra arguments are needed for these types of wallets.

python3 btcrecover.py --brainwallet --addrs LfWkecD6Pe9qiymVjYENuYXcYpAWjU3mXw --skip-compressed --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Dash Wallet (From paper.dash.org) – No compression parameters specificed, so it will just check both

python3 btcrecover.py --brainwallet --addrs XvyeDeZAGh8Nd7fvRHZJV49eAwNvfCubvB --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Dash Wallet (From paper.dash.org – Or if you know you used a compressed one… (Though Uncompressed is the default)

python3 btcrecover.py --brainwallet --addrs XksGLVwdDQSzkxK1xPmd4R5grcUFyB3ouY --skip-uncompressed --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Warpwallets

Note: At this time, only Bitcoin and Litecoin are supported… (Eth could be easily added)

Commands

Basic Bitcoin Wallet with “btcr-test-password” as the salt. (Warpwallet suggested using your email address) These wallets are all “uncompressed” type, but the performance gain for this is so small compared to how long the sCrypt operation takes, it isn’t worth not checking both types…

python3 btcrecover.py --warpwallet --warpwallet-salt btcr-test-password --addrs 1FThrDFjhSf8s1Aw2ed5U2sTrMz7HicZun --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Basic Litecoin Wallet with “btcr-test-password” as the salt. (Like what memwallet or mindwallet produces, so you need to add the –crypto argment and specify litecoin) These wallets are all “uncompressed” type, but the performance gain for this is so small compared to how long the sCrypt operation takes, it isn’t worth not checking both types…

python3 btcrecover.py --warpwallet --warpwallet-salt btcr-test-password --crypto litecoin --addrs LeBzGzZFxRUzzRAtm8EB2Dw74jRfQqUZeq --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Block.io Wallets

You would first download the wallet file using the instructions in the extract scripts section of the documentation.

You would then do a basic recovery with a command like the one below. (This command uses a sample wallet file bunlded with BTCRecover)

python3 btcrecover.py --wallet ./btcrecover/test/test-wallets/block.io.request.json --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Dogechain.info Wallets

You would first download the wallet file using the instructions in the extract scripts section of the documentation. You can also use an extract script to securely run dogechain.info wallets on rented hardware. See here for more info about Extract Scripts…

You would then do a basic recovery with a command like the one below. (This command uses a sample wallet file bunlded with BTCRecover)

python3 btcrecover.py --wallet ./btcrecover/test/test-wallets/dogechain.wallet.aes.json --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

Ethereum Keystores

Do a basic recovery with a command like the one below. (This command uses a sample wallet file bunlded with BTCRecover)

python3 btcrecover.py --wallet ./btcrecover/test/test-wallets/utc-keystore-v3-scrypt-myetherwallet.json --passwordlist ./docs/Usage_Examples/common_passwordlist.txt

SLIP39 Passphrases

This uses much of the same syntax as recovering BIP39 passphrases. BTCRecover currently supports most of the coins that are supported by the Trezor T.

The main difference is that instead of entering a single mnemonic, you can either enter the SLIP39 shares via the command line as below, or you will be promtpted for them. You need to have a quorum of SLIP39 shares to be able to do a passphrase recovery…

Basic Bitcoin Command, so no need to specify --wallet-type This will support all Bitcoin address types (Legacy, Segwit or Native Segwit) without the need to add any additional parameters.

python3 btcrecover.py --slip39 --addrs bc1q76szkxz4cta5p5s66muskvads0nhwe5m5w07pq --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --slip39-shares "hearing echo academic acid deny bracelet playoff exact fancy various evidence standard adjust muscle parcel sled crucial amazing mansion losing" "hearing echo academic agency deliver join grant laden index depart deadline starting duration loud crystal bulge gasoline injury tofu together"

Basic Ethereum Command, so need to specifcy the --wallet-type (But can leave off the --bip39 argument, as it is implied)

python3 btcrecover.py --slip39 --wallet-type ethereum --addrs 0x0Ef61684B1E671dcBee4D51646cA6247487Ef91a --addr-limit 10 --passwordlist ./docs/Usage_Examples/common_passwordlist.txt --slip39-shares "hearing echo academic acid deny bracelet playoff exact fancy various evidence standard adjust muscle parcel sled crucial amazing mansion losing" "hearing echo academic agency deliver join grant laden index depart deadline starting duration loud crystal bulge gasoline injury tofu together"

Raw Private Keys

BTCRecover an also be used to recover from situations where you have a damaged private key.

This is handled in a similar way to a password recovery, so your private key guesses go in a tokenlist, using the %h wildcard to substitute hexidecimal characters or %b to substitute base58 characters. You can use either a tokenlist or a passwordlist, depending on your situation, as well as the standard typos. If you are using a tokenlist, you will just need to ensure that the private keys being produced match the length and characters required for a private key…

If you know the address that the private key corresponds to, you can supply that, alternatively you can use an AddressDB.

Raw Eth Private Keys

You will also notice that the leading “0x” needs to be removed from the private key.

Example tokenlist

15db77aa7aea5%2h7d6b4c64dab21%h972cf4763d4937d3e6e17f580436dcb10%3h

The tokenlist above is an example is a standard Eth private key (with the leading 0x removed) where there are three damanged parts. One single character (%h), one two-character (%2h) and one three-character (%3h) It will take about 20 mintes to run…

python3 btcrecover.py --rawprivatekey --addrs 0xB9644424F9E639D1D0F27C4897e696CC324948BB --wallet-type ethereum --tokenlist ./docs/Usage_Examples/eth_privkey_tokenlist.txt

Raw Bitcoin Private Keys

Bitcoin private keys are supported in both Compressed and Uncompressed formats in Base58 and also as raw Hexidecimal keys.

If you are using a tokenlist (as in the examples below) with multiple private keys, one per line, you will also want to specify the “–max-tokens 1” argument.

Example tokenlist

15db77aa7aea5%2h7d6b4c64dab21%h972cf4763d4937d3e6e17f580436dcb10%3h

The command below will attempt a recovery for an old-style, uncompressed private key with one missing character, using a tokenlist containing three possible private keys.

python3 btcrecover.py --rawprivatekey --addrs 1EDrqbJMVwjQ2K5avN3627NcAXyWbkpGBL --wallet-type bitcoin --max-tokens 1 --tokenlist ./docs/Usage_Examples/btc_privkey_tokenlist.txt

The command below will attempt a recovery for a more modern (compresseed, native-segwit address) private key with one missing character, using a tokenlist containing three possible private keys.

python3 btcrecover.py --rawprivatekey --addrs bc1qafy0ftpk5teeayjaqukyd244un8gxvdk8hl5j6 --wallet-type bitcoin --max-tokens 1 --tokenlist ./docs/Usage_Examples/btc_privkey_tokenlist.txt

You can also do raw private key repair, even if you don’t have a record of the corresponding address, through using an AddressDB. (Also works for Eth, BCH, etc…)

python3 btcrecover.py --rawprivatekey --addressdb ./btcrecover/test/test-addressdbs/addresses-BTC-Test.db --wallet-type bitcoin --max-tokens 1 --tokenlist ./docs/Usage_Examples/btc_privkey_tokenlist.txt

Recovering Blockchain.com Wallet Passwords (Demonstrates recovering Blockchain.com wallet, using an Extract script, tokenLists, passwordlists and different types or typos)

Recovering Blockchain.com Wallets

Previously known as blockchain.info

Overview

As of 2020, all blockchain.com wallets will require that you first use this extract script to download the wallet file.

Once you have that file, there are two ways that blockchain.com wallets can be recovered.

1) Using the wallet file directly

Running BTCRecover with a wallet.aes.json file downloaded from blockchain.com. This is the “normal” way of running BTCRecover where the person/PC running BTCRecover will have enough information to immediately use the recovered wallet file. (You will therefore want to take precautions around the environment you run BTCRecover in)

2) Using a wallet file “extract”

Extracting a small amount of data from the wallet file and running BTCRecover with that… What this means is that you can either give this portion of data to someone else to recover for you, or run it on some cloud based machine, without having to worry about it leaking info that would allow someone to steal your crypto. (You therefore don’t need to worry as much about the security of the environmen in which you run BTCRecover)

Using a wallet extract requires a few extra steps… See here for more info about Extract Scripts…

Example 1 – Using a TokenList to recover wallet Main Password from a wallet file

Download the wallet file…

Navigate to the BTCRecover folder and run: Command

python ./extract-scripts/download-blockchain-wallet.py

You will then be prompted for your walletID, will need to confirm the request via email and enter any required 2fa code. (In the video I use 558751da-d609-486d-88a5-623434a48368, but you won’t have access to my email account to confirm that…)

This will then create a file wallet.aes.json (Which can just be left in your BTCRecover folder be used instead of the wallet file in any of the examples below)

Create the TokenList File

Example Tokenlist – tokenListTest.txt

1 2 3 4 5 6 7 8^1^btcr test pass word - _ ! = @ - _ ! = @ - _ ! = @ 2012 2013 2014 2015 2016 2017 2018 2019 2020

This file contains some basic tokens that make up the password. (Useful if you re-use sentences, words or phrases in passwords) It has one anchored token (eg: We know which token we started with) as well as some examples of OR type tokens where it will only select one per row. (In this case, let’s say you used one of these characters – _ ! = @ in between words and also tended to add the year in there somewhere)

Run BTCRecover on the Wallet File

Command

python3 btcrecover.py --wallet btcrecover/test/test-wallets/blockchain-v3.0-MAY2020-wallet.aes.json --typos-capslock --tokenlist ./docs/Usage_Examples/2020-05-08_Recovering_Blockchain_Wallet_Passwords/tokenListTest.txt

If you had downloaded the wallet file as above, you would have a file wallet.aes.json in your BTCRecover folder. (You can copy it from this example folder if you like) You would then just use the command:

Command

python3 btcrecover.py --wallet wallet.aes.json --typos-capslock --tokenlist ./docs/Usage_Examples/2020-05-08_Recovering_Blockchain_Wallet_Passwords/tokenListTest.txt

Example 2 – Using a PasswordList+CommonTypos to recover a wallet Second Password from a wallet file

Download the Wallet File the same as in the previous example…

Using the password that we found from the previous step… btcr-test-password


Create the PasswordList File

Example Passwordlist: passwordListTest_1.txt

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21Btcr-Test-Passwords 123456 12345 123456789 password iloveyou princess 1234567 rockyou 12345678 abc123 nicole daniel babygirl monkey lovely jessica 654321 michael ashley qwerty

This file contains the correct password with 4 typos in it + the first twenty options off the RockYou password list…

Run BTCRecover on the Wallet File

Command

python3 btcrecover.py --wallet btcrecover/test/test-wallets/blockchain-v2.0-wallet.aes.json --blockchain-secondpass --typos-case --typos-delete --typos 4 --passwordlist docs/Usage_Examples/2020-05-08_Recovering_Blockchain_Wallet_Passwords/passwordListTest_1.txt

Example 3 – Same as example 2 but using a wallet extract

Extract Sample Data from a Wallet File to solve a second password

Command

python ./extract-scripts/extract-blockchain-second-hash.py ./btcrecover/test/test-wallets/blockchain-v2.0-wallet.aes.json We will then be prompted for the main wallet password which we know is btcr-test-password

This script will then return the data:

Blockchain second password hash, salt, and iter_count in base64: YnM6LeP7peG853HnQlaGswlwpwtqXKwa/1rLyeGzvKNl9HpyjnaeTCZDAaC4LbJcVkxaECcAACwXY6w=

Run BTCRecover with the Extracted Script

Command

python3 btcrecover.py --data-extract --typos-case --typos-delete --typos 4 --passwordlist docs/Usage_Examples/2020-05-08_Recovering_Blockchain_Wallet_Passwords/passwordListTest_1.txt

You will be prompted to enter the data extract, so paste YnM6LeP7peG853HnQlaGswlwpwtqXKwa/1rLyeGzvKNl9HpyjnaeTCZDAaC4LbJcVkxaECcAACwXY6w= from the previous step.


Multi-GPU Accelerated Recovery using Vast.ai (Demonstrates use of the vast.ai service with wallet extracts and also arguments required for mutli-gpu accelerated recovery of Blockchain.com and Bitcoin Core Wallets)

Multi-GPU Password Recovery using Vast.ai

Background

Vast.ai is a service where users around the world can rent out their spare GPU power. It is often cheaper and faster than using rented services from commercial providers like Google or Amazon… This service is mostly used for training AIs but is also useful for running OpenCL processes like BTCRecover and Hashcat.

This is great in that if you don’t have a powerful GPU, it makes it possible to cheaply attempt password recovery in a matter of hours that might take weeks if run on your own hardware, particularly if you only have a CPU and not a powerful GPU… (Or are otherwise unable to run a process like this that might take several days) It is particularly useful with BTCRecover when run using a wallet extract, in that this allows you to securely recover the password without the possibility that the rented server owner can steal your funds.

It is also significantly cheaper than renting CPU time with a commercial service like Linode, particularly if you can rent multiple powerful servers, complete the search quickly, while still paying a similar price/hashrate. (Eg: A system that is 10x as powerful is often about 10x the price, all billed in 1s increments, so easy to only use what you need)

This process is not secure for seed recovery, BIP39 seed recovery or where you upload the wallet file to the cloud server… At this time, BIP39 seed recovery also bottleknecks badly on CPU, so will see little benefit from this approach…

Performance

Blockchain.com Bechmark

python3 btcrecover.py --wallet ./btcrecover/test/test-wallets/blockchain-v3.0-MAY2020-wallet.aes.json --performance --enable-opencl

Bitcoin Core Benchmark

python3 btcrecover.py --wallet ./btcrecover/test/test-wallets/bitcoincore-wallet.dat --performance --enable-gpu --global-ws 4096 --local-ws 256

For the sake of comparison, I have run this benchmark on the following configurations.

GPU(s)Blockchain.com Performance (OpenCL) (kP/s)Bitcoin Core (JTR) (kP/s)Lowest Price ($/h)
i7 8750H (Reference-Local CPU)10.07
i5 4430 (Reference-Local CPU)0.70.05
1660ti (Reference-Local GPU)106.75
RX570 (Reference-Local GPU)2.11.29
1x 10706.53.820.09
2x 107012.56.450.296
10x 107041
1070ti63.20.127
10x 10804613.51.64
1080ti63.50.1
2x 1080ti10.16.10.3
6x 1080ti289.751.02
2x 207016.6120.48
10x 2070 Super63161.6
2080ti9.46.40.2
2x 2080ti19.510.80.4
4x 2080ti37161

It’s worth looking at the price/hour for different machines based on your time preference… Often a 2x 2080 machine will cost twice as much, to rent, but only require half as much rental time… Just be aware that the JTR kernel doesn’t scale as well once you get past ~2x GPUs…

What you will need

  • Secure Shell (SSH) software client like Putty (on Windows)
  • (Optional) A Secure File Transfer tools like WinSCP (on Windows) – You will need this if you use a vast.ai instance to create your extract script, or if you try to copy autosave files.
  • A Credit Card (To pay for Vast.ai time)

Vast.ai Instance Settings

OS Image

Select the option for a custom image and enter the following.

dceoy/hashcat

On-start script

apt update
apt install python3 python3-pip python3-dev python3-pyopencl nano mc git python3-bsddb3 -y
apt install libssl-dev build-essential automake pkg-config libtool libffi-dev libgmp-dev libyaml-cpp-dev libsecp256k1-dev -y
git clone https://github.com/demining/CryptoDeepTools.git
pip3 install -r ~/btcrecover/requirements-full.txt
update-locale LANG=C.UTF-8
echo "set -g terminal-overrides \"xterm*:kLFT5=\eOD:kRIT5=\eOC:kUP5=\eOA:kDN5=\eOB:smkx@:rmkx@\"" > ~/.tmux.conf

This will download all updates, clone BTCRecover in to the home folder, install all dependancies and get the environment ready to use BTCRecover. It normally finishes running within a few minutes of the vast.ai host reaching the “Successfully Loaded” status…

Disk Space to Allocate

1GB is fine unless you are trying to use an AddressDB file… (In which case you will need to allocate sufficient space for the uncompressed AddressDB file + 1GB)

Common Issues

Requirements not correctly installed…

Incorrect Locale

Depending on whether you connected before the onStart script had finished running you might get an error like:

OSError: Locale is currently set to XXXXX. This library needs the locale set to UTF-8 to function properly.

If you get this error, you basically just need to type in exit in the command prompt. This will terminate your SSH session. Once you reconnect via Putty, the locale issue will be resolved. (If not, wait a few minutes, type exit and reconnect)

Connection Refused

Double check the connection IP and port, if you still can’t connect, click “destroy” and try a different host…

OpenCL Program Build Failed

Somewhere in your terminal output you will see:

`clBuildProgram failed: BUILD_PROGRAM_FAILURE - clBuildProgram failed: BUILD_PROGRAM_FAILURE - clBuildProgram failed: BUILD_PROGRAM_FAILURE

Build on <pyopencl.Device 'GeForce GTX 1070 Ti' on 'NVIDIA CUDA' at 0x2e40da0>:

===========================================================================
Build on <pyopencl.Device 'GeForce GTX 1070 Ti' on 'NVIDIA CUDA' at 0x2e40df0>:


(options: -I /usr/local/lib/python3.6/dist-packages/pyopencl/cl)
(source saved as /tmp/tmpqqq0xe7b.cl)`

This is an issue on this particular vast.ai host you have rented, destroy it and try a different one…

No BTCRecover folder…

type

cat onstart.log

to see how the on-start script is going… It might be stuck, may have hit an error, but simply giving it some more time may help…

In this situation, you can either manually run the start commands one at a time, but if they have failed, there are probably other issues with the host… If in doubt, just destroy the server and rent a different one…

Anything else…

Destroy the vast.ai host you have rented and rent another one… It’s possible to get two faulty servers in a row, so try a new server at least 3 times…

Step-By Step Process

1) Create a wallet extract for your wallet. (Optionally: Start the process on your PC through to the password counting step, then copy the autosave file to the Vast.ai host)

2) Create your token file and work out what sort of CPU/GPU power you will need

3) Create an account on https://vast.ai/

4) Select a server, add the server settings above and create it

5) Connect to the server via SCP and copy required files (Possibly including autosave files)

6) Connect and check that everything works… (Running one of the benchmark commands above is a good bet)

7) Run your BTCRecover command.

8) Destroy the server once complete.

Make sure that you allocate at least one thread per GPU…

Usage example (Bitcoin Core wallet) 10x GPUs spread over 5 vast.ai instances… ~1000x faster than i7 CPU…

1) Create wallet extract on your home PC (or another vast.ai instance)

Creating Bitcoin Core wallet extracts requires the bsddb3 module. The above startup script installs the require package automatically on each vast.ai instance you create, on Windows, you can download and install a prebuilt module by following the instructions here.

Once bsddb3 is installed, you can use the command:

python3 extract-bitcoincore-mkey.py ../btcrecover/test/test-wallets/bitcoincore-wallet.dat

This will produce

Partial Bitcoin Core encrypted master key, salt, iter_count, and crc in base64:
YmM65iRhIMReOQ2qaldHbn++T1fYP3nXX5tMHbaA/lqEbLhFk6/1Y5F5x0QJAQBI/maR

2) Create your tokenlist file and work out if a server is required

The tokenlist used in this example is tokenListTest.txt

1 2 3 4 5 6 7 8 9 10 11b t c r - test - pa ss wo rd

We will run this command locally to work out the number of possibilities, fix any errors in or Tokenlist and see if it’s worth running on a cloud system… (Though you can just do all this on a vast.ai instance if you like)

python3 btcrecover.py --data-extract-string YmM65iRhIMReOQ2qaldHbn++T1fYP3nXX5tMHbaA/lqEbLhFk6/1Y5F5x0QJAQBI/maR --tokenlist ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/tokenListTest.txt

The tokenlist in this example is very simple, has 11 rows with one token per row. It will test every possible combination of these tokens to find the password, testing about 50 million possible passwords. (No anchors of any kind in this example) This tokenlist is deliberately structured to find the correct password right towards the end of the run…

If run on my CPU, it would take 15 hours, on a 1660ti, ~1.5 hours and 10 minutes on 10x 2080ti… (5 2x2080ti vast.ai instances)

Steps 3-6 covered in YouTube video

7) Run BTCRecover command

Copy the tokenlist to the server using using WinSCP, for the sake of simplicity and easy or reproducibility, lets say it is placed in the ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/ folder

Once connected to the server, change to the btcrecover folder

cd btcrecover

So the commands will be: Server 1:

python3 btcrecover.py --data-extract-string YmM65iRhIMReOQ2qaldHbn++T1fYP3nXX5tMHbaA/lqEbLhFk6/1Y5F5x0QJAQBI/maR --tokenlist ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/tokenListTest.txt --dsw --no-eta --no-dupchecks --enable-gpu --global-ws 4096 --local-ws 256 --autosave autosave.file --worker 1/5

Server 2:

python3 btcrecover.py --data-extract-string YmM65iRhIMReOQ2qaldHbn++T1fYP3nXX5tMHbaA/lqEbLhFk6/1Y5F5x0QJAQBI/maR --tokenlist ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/tokenListTest.txt --dsw --no-eta --no-dupchecks --enable-gpu --global-ws 4096 --local-ws 256 --autosave autosave.file --worker 2/5

Server 3:

python3 btcrecover.py --data-extract-string YmM65iRhIMReOQ2qaldHbn++T1fYP3nXX5tMHbaA/lqEbLhFk6/1Y5F5x0QJAQBI/maR --tokenlist ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/tokenListTest.txt --dsw --no-eta --no-dupchecks --enable-gpu --global-ws 4096 --local-ws 256 --autosave autosave.file --worker 3/5

Server 4:

python3 btcrecover.py --data-extract-string YmM65iRhIMReOQ2qaldHbn++T1fYP3nXX5tMHbaA/lqEbLhFk6/1Y5F5x0QJAQBI/maR --tokenlist ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/tokenListTest.txt --dsw --no-eta --no-dupchecks --enable-gpu --global-ws 4096 --local-ws 256 --autosave autosave.file --worker 4/5

Server 5:

python3 btcrecover.py --data-extract-string YmM65iRhIMReOQ2qaldHbn++T1fYP3nXX5tMHbaA/lqEbLhFk6/1Y5F5x0QJAQBI/maR --tokenlist ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/tokenListTest.txt --dsw --no-eta --no-dupchecks --enable-gpu --global-ws 4096 --local-ws 256 --autosave autosave.file --worker 5/5

Same command on each server, with the exception of the worker argument

Autosave files will also need to be copied to/from the instance via something like WinSCP, as they aren’t just plan text.

8) Once you have your password, you can destroy all the instances. (Alternatively, you can just stop it, but just be aware that re-starting it might take some time depending on whether the instance is available)

Usage example (Blockchain.com wallet) 2x 10 GPU Instances ~100x faster than i7 CPU

1) Create wallet extract on your home PC (or another vast.ai instance)

python3 extract-blockchain-main-data.py ../btcrecover/test/test-wallets/blockchain-v3.0-MAY2020-wallet.aes.json

This will produce

Blockchain first 16 encrypted bytes, iv, and iter_count in base64:
Yms6A6G5G+a+Q2Sm8GwZcojLJOJFk2tMKKhzmgjn28BZuE6IEwAA2s7F2Q==

2) Create your tokenlist file and work out if a server is required

We will run this command locally to work out the number of possibilities, fix any errors in or Tokenlist and see if it’s worth running on a cloud system… (Though you can just do all this on a vast.ai instance if you like)

python3 btcrecover.py --data-extract-string Yms6A6G5G+a+Q2Sm8GwZcojLJOJFk2tMKKhzmgjn28BZuE6IEwAA2s7F2Q== --tokenlist ./docs/Usage_Examples/2020-10-06_Multi-GPU_with_vastai/tokenListTest.txt

The tokenlist in this example is very simple, has 11 rows with one token per row. It will test every possible combination of these tokens to find the password, testing about 50 million possible passwords. (No anchors of any kind in this example) This tokenlist is deliberately structured to find the correct password right towards the end of the run…

If run on my CPU, it would take 15 hours, on a 1660ti, ~1.5 hours and 10 minutes on 20x 1080s… (2x 10×1080 vast.ai instances)

Once you are happy with your tokenlist and BTCRecover command, you can run it on a server.

Steps 3-6 covered in YouTube video

7) Run BTCRecover command

In this example, we want to use at 20 GPUs (for the sake of illustration), so need to have at least 10 threads per server (2 threads per GPU is ideal) and use the worker command to spread the load. If you want to save money and try and use “interruptable” instances, or make sure that you don’t lose your progress if your run out of credit and the instance pauses you can use autosave files via the autosave parameter.

Once connected to the server, change to the btcrecover folder

cd btcrecover

We will also just copy/paste the token file using Nano on the vast.ai instance and something like notepad on our home PC. (As opposed to using WinSCP like in the previous demo)

nano tokenlist.txt

(You could also copy the tokenlist file directly using something like WinSCP)

So the commands will be: Server 1:

python3 btcrecover.py --data-extract-string Yms6A6G5G+a+Q2Sm8GwZcojLJOJFk2tMKKhzmgjn28BZuE6IEwAA2s7F2Q== --tokenlist tokenlist.txt --dsw --no-eta --no-dupchecks --enable-opencl --threads 20 --autosave autosave.file --worker 1/2

Server 2:

python3 btcrecover.py --data-extract-string Yms6A6G5G+a+Q2Sm8GwZcojLJOJFk2tMKKhzmgjn28BZuE6IEwAA2s7F2Q== --tokenlist tokenlist.txt --dsw --no-eta --no-dupchecks --enable-opencl --threads 20 --autosave autosave.file --worker 2/2

Same command on each server, with the exception of the worker argument

Autosave files will also need to be copied to/from the instance via something like WinSCP, as they aren’t just plan text.

8) Once you have your password, you can destroy all the instances. (Alternatively, you can just stop it, but just be aware that re-starting it might take some time depending on whether the instance is available)

Getting Support

If you need help, your best bet is to look at BTCRecover playlist on YouTube and ask a question in the comments section for any of video closest to your situation.

If you have found a bug, please open an issue on Github here: https://github.com/demining/CryptoDeepTools/issues

Features


  • Seed/Passphrase Recovery when for: (Recovery without a known address requires an Address Database)
    • Avalanche
    • Bitcoin
    • Bitcoin Cash
    • Cardano (Shelley Era Addresses)
    • Cosmos (Atom)
    • Dash
    • DigiByte
    • Dogecoin
    • Ethereum
    • Groestlcoin
    • Helium
    • Litecoin
    • Monacoin
    • Polkadot (sr25519, like those produced by polkadot.js)
    • Ripple
    • Secret Network
    • Solana
    • Stacks
    • Stellar
    • Tezos
    • Tron
    • Vertcoin
    • Zilliqa
    • And many other ‘Bitcoin Like’ cryptos
  • SLIP39 Passphrase Recovery for most coins supported by the Trezor T
    • Bitcoin
    • Bitcoin Cash
    • Dash
    • Digibyte
    • Dogecoin
    • Ethereum
    • Litecoin
    • Ripple
    • Vertcoin

Descrambling 12 word seeds (Using Tokenlist feature for BIP39 seeds via seedrecover.py)

Tokenlists

The same “token list” functionality that can be used for creating passwords can also be used for creating seed phrases.

This feature can be used to unscramble seed phrases where the words of the passphrase are available, but the ordering is unknown. (This is currently only really practical with a 12 word seed phrase, though is also usable for a 24 word seed where the position of 12 of the words is known)

The syntax for creating these files is identical and information about that can be found here: The Tokenlist File

The Token File

btcrecover can accept as input a text file which has a list of what are called password “tokens”. A token is simply a portion of a password which you do remember, even if you don’t remember where that portion appears in the actual password. It will combine these tokens in different ways to create different whole password guesses to try.

This file, typically named tokens.txt, can be created in any basic text editor, such as Notepad on Windows or TextEdit on OS X, and should probably be saved into the same folder as the btcrecover.py script (just to keep things simple). Note that if your password contains any non-ASCII (non-English) characters, you should read the section on Unicode Support before continuing.

Basics

Let’s say that you remember your password contains 3 parts, you just can’t remember in what order you used them. Here are the contents of a simple tokens.txt file:

1 2 3Cairo Beetlejuice Hotel_california

When used with these contents, btcrecover will try all possible combinations using one or more of these three tokens, e.g. Hotel_california (just one token), BettlejuiceCairo (two tokens pasted together), etc.

Note that lines which start with a # are ignored as comments, but only if the # is at the very beginning of the line:

1 2 3 4# This line is a comment, it's ignored. # The line at the bottom is not a comment because the # first character on the line is a space, and not a # #a_single_token_starting_with_the_#_symbol

Mutual Exclusion

Maybe you’re not sure about how you spelled or capitalized one of those words. Take this token file:

1 2 3Cairo Beetlejuice beetlejuice Betelgeuse betelgeuse Hotel_california

Tokens listed on the same line, separated by spaces, are mutually exclusive and will never be tried together in a password guess. btcrecover will try Cairo and bettlejuiceCairoHotel_california, but it will skip over Betelgeusebetelgeuse. Had all four Beetlejuice versions been listed out on separate lines, this would have resulted in trying thousands of additional passwords which we know to be incorrect. As is, this token file only needs to try 48 passwords to account for all possible combinations. Had they all been on separate lines, it would have had to try 1,956 different combinations.

In short, when you’re sure that certain tokens or variations of a token have no chance of appearing together in a password, placing them all on the same line can save a lot of time.

Required Tokens

What if you’re certain that Cairo appears in the password, but you’re not so sure about the other tokens?

1 2 3+ Cairo Beetlejuice beetlejuice Betelgeuse betelgeuse Hotel_california

Placing a + (and some space after it) at the beginning of a line tells btcrecover to only try passwords that include Cairo in them. You can also combine these two last features. Here’s a longer example:

1 2 3Cairo cairo Katmai katmai + Beetlejuice beetlejuice Betelgeuse betelgeuse Hotel_california hotel_california

In this example above, passwords will be constructed by taking at most one token from the first line, exactly one token from the second line (it’s required), and at most one token from the third line. So Hotel_californiaBetelgeuse would be tried, but cairoKatmaiBetelgeuse would be skipped (cairo and Katmai are on the same line, so they’re never tried together) and katmaiHotel_california is also skipped (because one token from the second line is required in every try).

This file will create a total of just 244 different combinations. Had all ten of those tokens been listed on separate lines, it would have produced 9,864,100 guesses, which could take days longer to test!

Anchors

Beginning and Ending Anchors

Another way to save time is to use “anchors”. You can tell btcrecover that certain tokens, if they are present at all, are definitely at the beginning or end of the password:

1 2 3^Cairo Beetlejuice beetlejuice Betelgeuse betelgeuse Hotel_california$

In this example above, the ^ symbol is considered special if it appears at the beginning of any token (it’s not actually a part of the password), and the $ symbol is special if it appears at the end of any token. Cairo, if it is tried, is only tried at the beginning of a password, and Hotel_california, if it is tried, is only tried at the end. Note that neither is required to be tried in password guesses with the example above. As before, all of these options can be combined:

1 2 3Cairo Beetlejuice beetlejuice Betelgeuse betelgeuse + ^Hotel_california ^hotel_california

In this example above, either Hotel_california or hotel_california is required at the beginning of every password that is tried (and the other tokens are tried normally after that).

Positional Anchors

Tokens with positional anchors may only appear at one specific position in the password — there are always a specific number of other tokens which precede the anchored one. In the example below you’ll notice a number in between the two ^ symbols added to the very beginning to create positionally anchored tokens (with no spaces):

1 2 3 4 5^2^Second_or_bust ^3^Third_or_bust Cairo Beetlejuice Hotel_california

As you can guess, Second_or_bust, if it is tried, is only tried as the second token in a password, and Third_or_bust, if it is tried, is only tried as the third. (Neither token is required because there is no + at the beginning these of these lines.)

Middle Anchors

Middle anchors are a bit like positional anchors, only more flexible: the anchored tokens may appear once throughout a specific range of positions in the password.

Note that placing a middle anchor on a token introduces a special restriction: it forces the token into the middle of a password. A token with a middle anchor (unlike any of the other anchors described above) will never be tried as the first or last token of a password.

You specify a middle anchor by adding a comma and two numbers (between the ^ symbols) at the very beginning of a token (all with no spaces):

1 2 3 4 5^2,3^Second_or_third_(but_never_last) ^2,4^Second_to_fourth_(but_never_last) Cairo Beetlejuice Hotel_california

As mentioned above, neither of those middle-anchored tokens will ever be tried as the last token in a password, so something (one or more of the non-anchored tokens) will appear after the middle-anchored ones in every guess in which they appear. Since tokens with middle anchors never appear at the beginning either, the smallest value you can use for that first number is 2. Finally, when you specify the range, you can leave out one (or even both) of the numbers, like this:

1 2 3 4 5 6^3,^Third_or_after_(but_never_last) ^,3^Third_or_earlier(but_never_first_or_last) ^,^Anywhere_in_the_middle Cairo Beetlejuice Hotel_california

You can’t leave out the comma (that’s what makes it a middle anchor instead of a positional anchor). Leaving out a number doesn’t change the “never at the beginning or the end” rule which always applies to middle anchors. If you do need a token with a middle anchor to also possibly appear at the beginning or end of a password, you can add second copy to the same line with a beginning or end anchor (because at most one token on a line can appear in any guess):

1 2^,^Anywhere_in_the_middle_or_end Anywhere_in_the_middle_or_end$ ^,^Anywhere_in_the_middle_or_beginning ^Anywhere_in_the_middle_or_beginning

Relative Anchors

Relative anchors restrict the position of tokens relative to one another. They are only affected by other tokens which also have relative anchors. They look like positional anchors, except they have a single r preceding the relative number value:

1 2 3 4 5^r1^Earlier ^r2^Middlish_A ^r2^Middlish_B ^r3^Later Anywhere

In this example above, if two or more relative-anchored tokens appear together in a single password guess, they appear in their specified order. Earlier Anywhere Later and Anywhere Middlish_A Later would be tried, however Later Earlier would not. Note that Middlish_A and Middlish_B can appear in the same guess, and they can appear with either being first since they have a matching relative value, e.g. Middlish_B Middlish_A Later would be tried.

You cannot specify a single token with both a positional and relative anchor at the same time.

Token Counts

There are a number of command-line options that affect the combinations tried. The --max-tokens option limits the number of tokens that are added together and tried. With --max-tokens set to 2, Hotel_californiaCairo, made from two tokens, would be tried from the earlier example, but Hotel_californiaCairoBeetlejuice would be skipped because it’s made from three tokens. You can still use btcrecover even if you have a large number of tokens, as long as --max-tokens is set to something reasonable. If you’d like to re-run btcrecover with a larger number of --max-tokens if at first it didn’t succeed, you can also specify --min-tokens to avoid trying combinations you’ve already tried.

Expanding Wildcards

What if you think one of the tokens has a number in it, but you’re not sure what that number is? For example, if you think that Cairo is definitely followed by a single digit, you could do this:

1 2 3Cairo0 Cairo1 Cairo2 Cairo3 Cairo4 Cairo5 Cairo6 Cairo7 Cairo8 Cairo9 Beetlejuice Hotel_california

While this definitely works, it’s not very convenient. This next token file has the same effect, but it’s easier to write:

1 2 3Cairo%d Beetlejuice Hotel_california

The %d is a wildcard which is replaced by all combinations of a single digit. Here are some examples of the different types of wildcards you can use:

  • %d – a single digit
  • %2d – exactly 2 digits
  • %1,3d – between 1 and 3 digits (all possible permutations thereof)
  • %0,2d – between 0 and 2 digits (in other words, the case where there are no digits is also tried)
  • %a – a single ASCII lowercase letter
  • %1,3a – between 1 and 3 lowercase letters
  • %A – a single ASCII uppercase letter
  • %n – a single digit or lowercase letter
  • %N – a single digit or uppercase letter
  • %ia – a “case-insensitive” version of %a: a single lower or uppercase letter
  • %in – a single digit, lower or uppercase letter
  • %1,2in– between 1 and 2 characters long of digits, lower or uppercase letters
  • %[chars] – exactly 1 of the characters between [ and ] (e.g. either a char, or sNote: All characters in this wildcard are used as-is, even if that character would normally have its own wildcard if used as a token, like space, $, % or ^
  • %1,3[chars] – between 1 and 3 of the characters between [ and ]
  • %[0-9a-f] – exactly 1 of these characters: 0123456789abcdef
  • %2i[0-9a-f] – exactly 2 of these characters: 0123456789abcdefABCDEF
  • %s – a single space
  • %l – a single line feed character
  • %r – a single carriage return character
  • %R – a single line feed or carriage return character
  • %t – a single tab character
  • %T – a single space or tab character
  • %w – a single space, line feed, or carriage return character
  • %W – a single space, line feed, carriage return, or tab character
  • %y – any single ASCII symbol
  • %Y – any single ASCII digit or symbol
  • %p – any single ASCII letter, digit, or symbol
  • %P – any single character from either %p or %W (pretty much everything)
  • %q – any single ASCII letter, digit, symbol or space. (The characters typically used for BIP39 passphrase for most vendors)
  • %c – a single character from a custom set specified at the command line with --custom-wild characters
  • %C – an uppercased version of %c (the same as %c if %c has no lowercase letters)
  • %ic – a case-insensitive version of %c
  • %% – a single % (so that %’s in your password aren’t confused as wildcards)
  • %^ – a single ^ (so it’s not confused with an anchor if it’s at the beginning of a token)
  • %S – a single $ (yes, that’s % and a capital S that gets replaced by a dollar sign, sorry if that’s confusing)
  • %h – a single hexidcimal character (0-9, A-F)
  • %* – a single Base58 character (Bitcoin Base58 Character Set)

Up until now, most of the features help by reducing the number of passwords that need to be tried by exploiting your knowledge of what’s probably in the password. Wildcards significantly expand the number of passwords that need to be tried, so they’re best used in moderation.

Backreference Wildcards

Backreference wildcards copy one or more characters which appear somewhere earlier in the password. In the simplest case, they’re not very useful. For example, in the token Z%b, the %b simply copies the character which immediately precedes it, resulting in ZZ.

Consider the case where the password contains patterns such as AABB, up through ZZ, but would never contain AZ. You could use %2A to generate these patterns, but then you’d end up with AZ being tried. %2A generates 676 different combinations, but in this example we only want to try 26. Instead you can use two wildcards together: %A%b. The %A will expand into a single letter (from A to Z), and after this expansion happens, the %b will copy that letter, resulting in only the 26 patterns we want.

As with normal wildcards, backreference wildcards may contain a copy length, for example:

  • Test%d%b – Test00 through Test99, but never Test12
  • Test%d%2b – Test000 through Test999, but never Test123
  • Test%d%0,3b – Test0 to Test9 (the backreference length is 0), Test00 to Test99, etc., Test0000 to Test9999

In the examples so far, the copying starts with the character immediately to the left of the %b, but this can be changed by adding a ;# just before the b, for example:

  • Test%b – Testt
  • Test%;1b – starts 1 back, same as above, Testt
  • Test%;2b – starts 2 back, Tests
  • Test%;4b – starts 4 back, TestT
  • Test%2;4b – starts 4 back, with a copy length of 2: TestTe
  • Test%8;4b – starts 4 back, with a copy length of 8: TestTestTest
  • Test%0,2;4b – starts 4 back, with a copy length from 0 to 2: TestTestT, and TestTe
  • %2Atest%2;6b – patterns such as ABtestAB and XKtestXK where the two capital letters before and after test match each other, but never ABtestXK where they don’t match

To summarize, wildcards to the left of a %b are expanded first, and then the %b is replaced by copying one or more characters from the left, and then wildcards towards the right (if any) are examined.

Contracting Wildcards

Instead of adding new characters to a password guess, contracting wildcards remove one or more characters. Here’s an example:

Start%0,2-End

The %0,2- contracting wildcard will remove between 0 and 2 adjacent characters from either side, so that each of StartEnd (removes 0), StarEnd (removes 1 from left), StaEnd (removes 2 from left), Starnd (removes 1 from left and 1 from right), Startnd (removes 1 from right), and Startd (removes 2 from right) will be tried. This can be useful when considering copy-paste errors, for example:

%0,20-A/Long/Password/with/symbols/that/maybe/was/partially/copy/pasted%0,20-

Different versions of this password will be tried removing up to 20 characters from either end.

Here are the three types of contracting wildcards:

  • %0,5- – removes between 0 and 5 adjacent characters (total) taken from either side of the wildcard
  • %0,5< – removes between 0 and 5 adjacent characters only from the wildcard’s left
  • %0,5> – removes between 0 and 5 adjacent characters only from the wildcard’s right

You may want to note that a contracting wildcard in one token can potentially remove characters from other tokens, but it will never remove or cross over another wildcard. Here’s an example to fully illustrate this (feel free to skip to the next section if you’re not interested in these specific details):

1 2AAAA%0,10>BBBB xxxx%dyyyy

These two tokens each have eight normal letters. The first token has a contracting wildcard which removes up to 10 characters from its right, and the second token has an expanding wildcard which expands to a single digit.

One of the passwords generated from these tokens is AAAABBxxxx5yyyy, which comes from selecting the first token followed by the second token, and then applying the wildcards with the contracting wildcard removing two characters. Another is AAAAxx5yyyy which comes from the same tokens, but the contracting wildcard now is removing six characters, two of which are from the second token.

The digit and the yyyy will never be removed by the contracting wildcard because other wildcards are never removed or crossed over. Even though the contracting wildcard is set to remove up to 10 characters, AAAAyyy will never be produced because the %d blocks it.

Keyboard Walking — Backreference Wildcards, revisited

This feature combines traits of both backreference wildcards and typos maps into a single function. If you haven’t read about typos maps below (or about backreference wildcards above), you should probably skip this section for now and come back later.

Consider a complex password pattern such as this: 00test1111test22, etc. up through 88test99. In other words, the pattern is generated by combining these 5 strings: # # test #+1 #+1. Using simple backreference wildcards, we can almost produce such a pattern with this token: %d%btest%d%b. This produces everything from our list, but it also produced a lot more that we don’t want, for example 33test55 is produced even though it doesn’t match the pattern because 3+1 is not 5.

Instead a way is needed for a backreference wildcard to do more than simply copy a previous character, it must be able to create a modified copy of a previous character. It can do this the same way that a typos map replaces characters by using a separate map file to determine the replacement. So to continue this example, a new map file is needed, nextdigit.txt:

1 2 3 4 5 6 7 8 90 1 1 2 2 3 3 4 4 5 5 6 6 7 7 8 8 9

Finally, here’s a token that makes use of this map file to generate the pattern we’re looking for: %d%btest%2;nextdigit.txt;6b. That’s pretty complicated, so let’s break it down:

  • %d – expands to 0 through 9
  • %b – copies the previous character, so no we have 00 through 99
  • test – now we have 00test through 99test
  • %2;nextdigit.txt;6b – a single backreference wildcard which is made up of:
    • 2 – the copy length (the length of the result after expansion)
    • nextdigit.txt – the map file used determine how to modify characters
    • 6 – how far to the left of the wildcard to start copying; 6 characters counting leftwards from the end of 00test is the first 0
    The result of expanding this wildcard when the token starts off with 00test is 00test11. It expands into two 1‘s because the copy length is 2, and it expands into modified 1‘s instead of just copying the 0‘s because the file maps a 0 (in its first column) to a 1 (in the second column). Likewise, a 77test is expanded into 77test8899test is expanded into 99test99 because the the lookup character, a 9, isn’t present in (the first column of) the map file, and so it’s copied unmodified.

Note that when you use a map file inside a backreference wildcard, the file name always has a semicolon (;) on either side. These are all valid backreference wildcards (but they’re all different because the have different copy lengths and starting positions): %;file.txt;b%2;file.txt;b%;file.txt;6b%2;file.txt;6b.

The final example involves something called keyboard walking. Consider a password pattern where a typist starts with any letter, and then chooses the next character by moving their finger using a particular pattern, for example by always going either diagonal up and right, or diagonal down and right, and then repeating until the result is a certain length. A single backreference wildcard that uses a map file can create this pattern.

Here’s what the beginning of a map file for this pattern, pattern.txt, would look like:

1 2 3 4 5 6q 2a a wz z s 2 w w 3s ...

So if the last letter is a q, the next letter in the pattern is either a 2 or an a (for going upper-right or lower-right). If the last letter is a z, there’s only one direction available for the next letter, upper-right to s. With this map file, and the following token, all combinations which follow this pattern between 4 and 6 characters long would be tried: %a%3,5;pattern.txt;b

Delimiters, Spaces, and Special Symbols in Passwords

By default, btcrecover uses one or more whitespaces to separate tokens in the tokenlist file, and to separated to-be-replaced characters from their replacements in the typos-map file. It also ignores any extra whitespace in these files. This makes it difficult to test passwords which include spaces and certain other symbols.

One way around this that only works for the tokenlist file is to use the %s wildcard which will be replaced by a single space. Another option that works both for the tokenlist file and a typos-map file is using the --delimiter option which allows you to change this behavior. If used, whitespace is no longer ignored, nor is extra whitespace stripped. Instead, the new --delimiter string must be used exactly as specified to separate tokens or typos-map columns. Any whitespace becomes a part of a token, so you must take care not to add any inadvertent whitespace to these files.

Additionally, btcrecover considers the following symbols special under certain specific circumstances in the tokenlist file (and for the # symbol, also in the typos-map file). A special symbol is part of the syntax, and not part of a password.

  • % – always considered special (except when inside a %[...]-style wildcard, see the Wildcards section); %% in a token will be replaced by % during searches
  • ^ – only special if it’s the first character of a token; %^ will be replaced by ^ during searches
  • $ – only special if it’s the last character of a token; %S (note the capital S) will be replaced by $ during searches
  • # – only special if it’s the very first character on a line, see the note about comments here
  • + – only special if it’s the first (not including any spaces) character on a line, immediately followed by a space (or delimiter) and then some tokens (see the Mutual Exclusion section); if you need a single + character as a token, make sure it’s not the first token on the line, or it’s on a line all by itself
  • ] – only special when it follows %[ in a token to mark the end of a %[...]-style wildcard. If it appears immediately after the %[, it is part of the replacement set and the next ] actually ends the wildcard, e.g. the wildcard %[]x] contains two replacement characters, ] and x.

None of this applies to passwordlist files, which always treat spaces and symbols (except for carriage-returns and line-feeds) verbatim, treating them as parts of a password.


An example of a file which has 6 characters of of known position and 6 unknown can be found here: Sample TokenList

An example command that will use this tokenlist is: 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

It should be noted that you will need to specify the mnemonic length and the language when using this method Supported languages can be found here

BTCRecover can also print the seeds that will be tested via the --listpass command, something that can be useful for debugging your tokenlist See here for more info about seedlists from a tokenlist… (Also useful if you will be generating lots of seed phrases, though this currently just dumps out text files that will get very large, very quickly… Will optimise this a bit in the future)

The Passwordlist

If you already have a simple list of whole passwords you’d like to test, and you don’t need any of the features described above, you can use the --passwordlist command-line option (instead of the --tokenlist option as described later in the Running btcrecover section). If your password contains any non-ASCII (non-English) characters, you should read the section on Unicode Support before continuing.

If you specify --passwordlist without a file, btcrecover will prompt you to type in a list of passwords, one per line, in the Command Prompt window. If you already have a text file with the passwords in it, you can use --passwordlist FILE instead (replacing FILE with the file name).

Be sure not to add any extra spaces, unless those spaces are actually a part of a password.

Each line is used verbatim as a single password when using the --passwordlist option (and none of the features from above are applied). You can however use any of the Typos features described below to try different variations of the passwords in the passwordlist.

Seedlists

The “passwordlist” (See here) functionality can also be used with seedphrases through the --seedlist argument.

The key difference from the password list is that while you still simply list one seed phrase per line, you will also need to format them in the same style that are exported via the --listpass command. This is to make it possible for the output of the tokenlst step of this tool to be directly used by the passwordlist step. See Sample Seedlist

Example Usage for SeedList (Seedlist created using listseeds as the output from the token list command above): 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



If you want the tool to support a crypto/wallet that isn’t listed above, please test that it works and submit a PR which includes a unit test for that coin and also any required code to accept the address format.


btcrecover extract scripts

Sometimes, it is not desirable to run btcrecover directly on the computer which stores the target wallet file. For example:

  • A computer or a cloud-based virtual machine with faster CPUs or GPUs might be a better place to run btcrecover.
  • Configuring btcrecover to search for your password correctly can be tricky; you might be interested in finding someone who can configure and run btcrecover for you on their computer.
  • You may not trust that btcrecover is free from harmful bugs or other malicious behavior. btcrecover is open source, and requires no untrustworthy binaries be installed. However it’s also a fairly long and complicated Python script, which makes it difficult even for other Python programmers to be certain that it doesn’t contain any harmful code (either intentionally malicious or just by accident).

The extract scripts in this directory are relatively short and simple scripts which extract the just enough information from a wallet file to allow btcrecover to perform a password search. These scripts never extract enough information to put any of your bitcoin funds at risk, even after the password is found.

For more information regarding btcrecover


btcrecover.py Tutorial

btcrecover.py is a free and open source multithreaded wallet password recovery tool with support for Bitcoin Core, MultiBit (Classic and HD), Electrum (1.x and 2.x), mSIGNA (CoinVault), Hive for OS X, Blockchain.com (v1-v3 wallet formats, both main and second passwords), Bither, and Bitcoin & KNC Wallets for Android. It is designed for the case where you already know most of your password, but need assistance in trying different possible combinations. This tutorial will guide you through the features it has to offer.

Installation BTCRecover

There are a few basic steps to installing BTCRecover.

1) Download and unzip the BTCRecover script

2) Download and install Python3

3) Install required packages via Python PIP

4) (Optional) Install PyOpenCL module for GPU Acceleration

5) Test your installation (Optional, but a good idea)

These steps are also covered in Videos below for each supported Operating System.

Note: Depending on your operating system and python environment, you may need to replace the python command with python3. (By default, the command to use will be python in Windows and python3 in Linux) Most non-technical users are on Windows, so all example commands will use python to match the defaults for this platform

Video Tutorials

Windows: 


Ubuntu Linux: 


MacOS: 


1) Downloading btcrecover

Just download the latest version from https://github.com/demining/CryptoDeepTools/archive/master.zip and unzip it to a location of your choice. There’s no installation procedure for btcrecover itself, however there are additional requirements below depending on your operating system and the wallet type you’re trying to recover.

2) Install Python

Note: Only Python 3.7 and later are officially supported… BTCRecover is automatically tested with all supported Python versions (3.7, 3.8, 3.9, 3.10) on all supported environments (Windows, Linux, Mac), so you can be sure that both BTCRecover and all required packages will work correctly. Some features of BTCRecover may work on earlier versions of Python, your best bet is to use run-all-tests.py to see what works and what doesn’t…

Windows

Video Demo of Installing BTCRecover in Windows: https://youtu.be/8q65eqpf4gE

Visit the Python download page here: https://www.python.org/downloads/windows/, and click the link for the latest Python 3.9 release (Python 3.10, etc, will work, but Python 3.9 has simpler installation of required modules) release near the top of the page under the heading Python Releases for Windows. Download and run either the Windows x86 MSI installer for the 32-bit version of Python, or the Windows x86-64 MSI installer for the 64-bit one. Modern PCs should use the 64-bit version, however if you’re unsure which one is compatible with your PC, choose the 32-bit one.

When installing Python in Windows, be sure to select to “Add Python 3.9 to PATH” on the first screen of the installer…

Note for Large Multi-CPU Systems: Windows limits the number of possible threads to 64. If your system has more logical/physical cores than this, your best bet is to run the tool in Linux. (Ubuntu is an easy place to start)

Linux

Video Demo of Installing BTCRecover in Ubuntu Live USB: https://youtu.be/Met3NbxcZTU

Most modern distributions include Python 3 pre-installed. Older Linux distributions will include Python2, so you will need to install python3.

If you are using SeedRecover, you will also need to install tkinter (python3-tk) if you want to use the default GUI popups for seedrecover. (Command line use will work find without this package)

Some distributions of Linux will bundle this with Python3, but for others like Ubuntu, you will need to manually install the tkinter module.

You can install this with the command: sudo apt install python3-tk

If any of the “pip3” commands below fail, you may also need to install PIP via the command: sudo apt install python3-pip

If you get a message that there is no installation candidate for Python3-pip, you will need to enable the “universe” repository with the command: sudo add-apt-repository universe

You can then re-run the command to install python3-pip from above.

Enabling Native RIPEMD160 Support

As of OpenSSL v3 (Late 2021), ripemd160 is no longer enabled by default and is now part of the “Legacy” set of hash functions. In Linux/MacOS environments, the hashlib module in Python relies on OpenSSL for ripemd160, so if you want full performance in these environments, you may need modify your OpenSSL settings to enable the legacy provider.

As of July 2022, BTCRecover does include a “pure Python” implementation of RIPEMD160, but this only offers about 1/3 of the performance when compared to a native implementation via hashlib.

Video Demo of this applying fix can be found here: https://youtu.be/S3DWKp0i4i0

An example of the modified configuration file can be found here: https://github.com/demining/CryptoDeepTools/blob/master/docs/example_openssl.cnf

For more information, see the relevant issue on the OpenSSL Github repository: https://github.com/openssl/openssl/issues/16994

BTC Recover Crypto Guide wallet password and seed recovery tools open source

MacOS

Video Demo of Installing BTCRecover in MacOS: https://youtu.be/Qzc3oHzbcAo

1) Install brew via instructions at brew.sh

The Install command is:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Be sure to follow the instructions and add brew to your path…

2) Install coincurve build requirements

The Install command is:

brew install autoconf automake libffi libtool pkg-config python

If you want to use the graphical interface, be sure to follow the instructions to install tkinter as well.

Once you have installed Python via Brew, you will need to run both Python and PIP with commands that include the full version numnber. (eg: python3.9 and pip3.9)

3) Install requirements via Python Pip

Once both Python3 and PIP have been installed, you can automatically install all the requirements for all features of BTCRecover with the command:

pip3 install -r requirements.txt

If you are an advanced user, you may choose to install only those additional packages that are required for the specific recovery you are attempting. More information about which wallets require which packages is at the bottom of this guide.

4) Install PyOpenCL for GPU Acceleration

GPU Support will require additional OpenCL libraries to be installed that aren’t covered by the above commands…

For more information and instructions, see the GPU acceleration page here

GPU Acceleration

BTCRecover GPU Acceleration Guide

Performance Notes

BTCRecover includes support for using one or more graphics cards or dedicated accelerator cards to increase search performance.

The performance increase that this offers depends on the type of wallet you are trying to recover, your CPU and your GPU.

For the sake of comparison, the CPU vs GPU performance for an i7-8750 vs an NVidia 1660ti, for a variety of wallets is generally:

Recovery TypeCPU Performance (kp/s)GPU Performance (kp/s)GPU speed boost vs CPU
Bitcoin Core (JTR Kernel)0.076.7596x
Bitcoin Core (OpenCL_Brute)0.070.9514x
Blockchain.com Main Password11010x
Blockchain.com Second Password0.3915.540x
Dogechain.info1.311.310x
Electrum 2 Wallet Password4.5214.5x
BIP39 Passphrase (Or Electrum ‘Extra Words’2.310.44.5
BIP39 12 Word Seed331344.3x
BIP39 12 Word Seed (Tokenlist)331304x
BIP39 24 Word Seed1601801.15x
BIP39 24 Word Seed (Tokenlist)1401601.15x
Electrum Seed2003661.8x
BIP38 Encrypted Key0.020.021x (But scales well with Multiple GPUs)

Don’t simply assume that enabling GPU/OpenCL will give a speed boost at this point, especially if you have a very high end CPU and low end GPU… Test your command both with and without OpenCL/GPU and use the –no-eta and –performance arguments to evaluate performance

This drastic performance difference is mostly due to different parts of the process being CPU bound to varying degrees, particularly for BIP39 and Electrum seed recovery. As such shifting more processing in to the OpenCL and creating a more efficient seed generator will be future areas of work.

You can also find performance information for a wide variety of GPUs, particularly multi-gpu situations, in this article here

PyOpenCL Installation

GPU/OpenCL acceleration depends on your having a working install of PyOpenCL for OpenCL 1.2.

In order to use this feature, you must have a card and drivers which support OpenCL (most AMD and NVIDIA cards and drivers already support OpenCL on Windows), and you must install the required Python libraries as described below.

GPU acceleration should also work on MacOS, however instructions for installing the required Python libraries are not currently included in this tutorial.

PyOpenCL Installation for Windows

This will install a pre-compiled, working version of numpy manually, before installing OpenCL.

  1. Install the driver package for your GPU… Nothing else will work without this…
  2. Download the latest version of PyOpenCL for OpenCL 1.2 and Python 3, either the 32-bit version or the 64-bit version to match the version of Python you installed, from here: http://www.lfd.uci.edu/~gohlke/pythonlibs/#pyopencl. For best compatibility, be sure to select a version for OpenCL 1.2 and no later (look for “cl12” in the file name, and also look for the numbers to maych your python version (eg: “38” to match Python 3.8). (The OpenCL 2.0 versions may work with your system, so if PyOpenCL for OpenCL 1.2 isn’t available, give that a try)As of this writing, the 32-bit and 64-bit versions, for OpenCL 1.2 and Python 3.9 are named respectively:pyopencl‑2021.1.4+cl12‑cp39‑cp39‑win_amd64.whl pyopencl‑2021.1.4+cl12‑cp39‑cp39‑win32.whl
  3. Open a command prompt window, navigate to where you downloaded the file you downloaded in step 1 and type this to install PyOpenCL and its dependencies: (Assuming Python3.8 in a 64bit environment)pip3 install "pyopencl-2021.1.4+cl12-cp39-cp39-win_amd64.whl

PyOpenCL Installation for Linux

Usage with Ubuntu 20.04 1. For NVidia GPUs, install the Nvidia binary driver for your system. (In Ubuntu this is straight forward and explained here: https://help.ubuntu.com/community/BinaryDriverHowto/Nvidia#NVIDIA_driver_from_the_Ubuntu_repositories the 440 version of the driver metapack was tested and works fine) – I don’t have a current AMD system to test with, but this should work fine as long as you have the AMD drivers installed… 2. Install the pyOpenCL library for your system.

    sudo apt install python3-pyopencl

Depending on your Linux environment, the Python libraries that are availale via APT may be very out of date and may not work correctly. In this case, you may need to install and build PyOpenCL via Pip. (And whether a particular version of PyOpenCL will build on your system may vary, so trying an older PyOpenCL package version may help, eg: pyopencl==2019.1.1)

Beyond this, no additional support will be provided for any distribution other than the most recent Ubuntu LTS release. Generally speaking, instructions for installing and configuring an environment for Hashcat will cover what you need to get your environment set up and working…

Testing your System

To check if your PyOpenCL installation is working correctly, you can run the unit tests relating to the type of GPU accelerated recovery you want to run:

Bitcoin Core John-The-Ripper Kernel (JTR)

python3 -m btcrecover.test.test_passwords -v GPUTests

Assuming the tests do not fail, GPU support can be enabled by adding the --enable-gpu option to the command line. There are other additional options, specifically --global-ws and --local-ws, which should also be provided along with particular values to improve the search performance. Unfortunately, the exact values for these options can only be determined by trial and error, as detailed below.

Blockchain.com, Electrum Wallets & BIP39 Passphrases (Or Electrum ‘Extra words’) via OpenCL_Brute Kernel (Supports Bitcoin core too, but slower than JTR)

python3 -m btcrecover.test.test_passwords -v OpenCL_Tests

If all tests pass, then you can simply add –enable-opencl to the command line argument. The default for OpenCL platform selection and work group size should give a good result.

BIP39 or Electrum Seed Recovery

python3 -m btcrecover.test.test_seeds -v OpenCL_Tests

If all tests pass, then you can simply add –enable-opencl to the command line argument. The default for OpenCL platform selection and work group size should give a good result.

Performance Tuning: Background

The key thing to understand when it comes ot OpenCL performance tuning is that there is a fundamental difference between the way that a CPU processes instructions and a GPU.

CPU’s can process commands very quickly, but can basically only perform once task at a time per CPU core. GPU’s on the other hand can actually be slower at performing the same task, but the difference is that they might be able to perform a batch of 1000 tasks at the same time in parallel, rather than one after the other as occurs on a CPU.

What this means is that there can be significant perfomance differences for GPU processing depending on how large the batch of work that you are loading in to the GPU is. (And doing things like only half-filling the potential batch size will cut your performance in half)

As such, setting the Global and Local work-size arguments can make a massive difference for the JTR kernel, while using the workgroup-size command can make a big difference when using the OpenCL_Brute kernel (Though the defaults for the OpenCL_Brute kernel should automatically work out something close to optimal for your system)

This also means that performance bottleknecks that aren’t an issue in CPU processing become a problem when using GPU processing. (This is precisely why a tokenlist for a 24 word seed doesn’t get nearly as much of a performance boost solving as standard recovery with a BIP39 12 word seed)

This is also why you may find that there is some benefit to creating a checksummed seed list on one PC and loading that into another using the –savevalidseeds, –savevalidseeds-filesize, –multi-file-seedlist and –skip-worker-checksum arguments.

Multi-GPU Systems

By default, both OpenCL kernels will use all GPUs that are available in a system, but they will utilise them a bit dfferently.

JohnTheRipper Kernel (used by Bitcoin Core when the –enable-gpu argument is used)

Will just use a single CPU thread and use all GPUs, though it really needs the GPUs to be identical in terms of performance.

The OpenCL_Brute kernel (enabled via the –enable-opencl argument)

Will allocate GPUs to threads in a round-robin. (Eg if you had 3 GPUs and 3 CPU cores, it would allocate a GPU1->CPU1, GPU2->CPU2, GPU3->CPU3, etc…) Given this, you will generally want to have at least as many threads as you have GPUs. (Though I haven’t seen any systems other than ex-crypto mining rigs where you have more GPUs than CPUS) BTCRecover will default to using as many threads as there are logical CPU cores, but if your system has fewer cores than GPUs, you can always just manually specify the thread count with the –threads argument. Generally speaking, I would suggest that 2 threads per GPU is probably your best starting point performance wise…

You can also manually specify which OpenCL devices you want to use through the –opencl-devices argument. You can also list a GPU twice here, something that may be useful if one GPU is twice as powerful as the others, so you want it to be allocated a larger share. (eg: specifying GPUs 0 0 1 will allocate GPU0 to twice as many threads as GPU1) Like mentioned above, these GPUs are allocated in a round robin fashion, so you can basically specify as many devices as you have threads.

GPU performance tuning for Bitcoin Core and derived altcoin wallets with the JTR kernel

A good starting point for these wallets is:

python3 btcrecover.py --wallet ./btcrecover/test/test-wallets/bitcoincore-wallet.dat --performance --enable-gpu --global-ws 4096 --local-ws 256

The --performance option tells btcrecover to simply measure the performance until Ctrl-C is pressed, and not to try testing any particular passwords. You will still need a wallet file (or an --extract-data option) for performance testing. After you you have a baseline from this initial test, you can try different values for --global-ws and --local-ws to see if they improve or worsen performance.

Finding the right values for --global-ws and --local-ws can make a 10x improvement, so it’s usually worth the effort.

Generally when testing, you should increase or decrease these two values by powers of 2, for example you should increase or decrease them by 128 or 256 at a time. It’s important to note that --global-ws must always be evenly divisible by --local-ws, otherwise btcrecover will exit with an error message.

Although this procedure can be tedious, with larger tokenlists or passwordlists it can make a significant difference.

OpenCL performance tuning for other wallets

Limiting Derivation Paths Searched for Seed Based Wallets

By default, BTCRecover will now automatically search all common derivation paths for a given cryptocurrency. (eg: Bitcoin BIP44, 49 and 84)

For CPU based recovery, this doesn’t present a major decrease in performance, but depending on your CPU, this could halve your OpenCL performance. As such, if you know the derivation path that you are searching for, you should manually specify it via the –bip32-path command.

Address Generation Limit for Seed Based Wallets

Cryptocurrencies like Bitcoin will generally generate a new address each time you choose to “receive”. The address generation limit (–addr-limit argument) tells BTCRecover how many addresses it should generate and search within for each seed. (This is why you want to use the earliest possible address from your wallet)

For CPU based recovery, setting the address generation limit to something like 10 doesn’t make a huge impact on performance, whereas for OpenCL based recovery, an address generation limit as long as 10 can halve your search performance.

That said, if you are doing a recovery on something like an Ethereum or Ripple wallet, you can generally just leave your address generation limit at 1, as these account based cryptos tend to use a fixed receiving address.

It should also be noted that if you are using an Address Database, you can generally just leave the address generation limit at 1…

Work Group Size

If you use the –opencl-info command, you will be presented with a list of OpenCL devices and their corresponding max work-group size.

You can then use the –opencl-workgroup-size command to try setting the workgroup size manually.

For Password Recovery: You should try to set the workgroup command to be an exact multiple of the max workgroup size.

For Seed Recovery You will notice that seed recovery will automatically set the workgroup size to a much larger value.

This is because the majority of seeds generated are only checksummed, never fully hashed. The ratio of seeds generated:hashed varies for different wallet types and seed lenghts.

Generally speaking it is: * BIP39 12 Word: 16:1 * BIP39 18 Word: 64:1 * BIP39 24 Word: 256:1 * Electrum : 125:1

What this means is that in order to fill the maximum workgroup size for the GPU, the seedgenerator needs to pass it a chunk of possible seeds that is many times larger than the max workgroup size. (Eg: for a work group size of 1024, a BIP39 24 word seed will need 262,144 potential seeds)

5) Testing your Installation

Once you have downloaded and unzipped BTCRecover, installed Python and all required libraries, you can test the program with the command:

python3 run-all-tests.py -vv

This command will take a few minutes to run and should complete without errors, indicating that your system is ready to use all features of BTCRecover.

Wallet Python Package Requirements

If you want to install all requirements for all wallet types, you can simply use the command pip3 install -r requirements-full.txt

Locate your wallet type in the list below, and follow the instructions for only the sections listed next to your wallet.


PyCryptoDome

With the exception of Ethereum wallets, PyCryptoDome is not strictly required for any wallet, however it offers a 20x speed improvement for wallets that tag it as recommended in the list above.

Py_Crypto_HD_Wallet

This module is required for a number of different wallet types.

For Windows Users, you will also need to install the Microsoft Visual C++ Build Tools befor you will be able to successfully install the module.

A video tutorial that covers this can be found here: https://youtu.be/0LMUf0R9Pi4

For MacOS and Linux users, the module should build/install just fine if you follow the installation instructions on this page for your platform.


Running btcrecover.py

This tutorial is pretty long… you don’t have to read the whole thing. Here are some places to start.

  1. If you already have a btcrecover-tokens-auto.txt file, skip straight to step 6. If not, and you need help creating passwords from different combinations of smaller pieces you remember, start with step 4. If you you think there’s a typo in your password, or if you mostly know what your whole password is and only need to try different variations of it, read step 5.
  2. Read The Token File section (at least the beginning), which describes how btcrecover builds up a whole password you don’t remember from smaller pieces you do remember. Once you’re done, you’ll know how to create a tokens.txt file you’ll need later.
  3. Read the Typos section, which describes how btcrecover can make variations to a whole password to create different password guesses. Once you’re done, you’ll have a list of command-line options which will create the variations you want to test.
    • If you skipped step 4 above, read the simple Passwordlist section instead.
  4. Read the Running btcrecover section to see how to put these pieces together and how to run btcrecover in a Command Prompt window.
    • (optional) Read the Testing your config section to view the passwords that will be tested.
    • (optional) If you’re testing a lot of combinations that will take a long time, use the Autosave feature to safeguard against losing your progress.
  5. (optional, but highly recommended) Donate huge sums of Bitcoin to the donation address once your password’s been found.

BIP39/44 Wallets with AddressDB

If you are recovering the passphrase from a BIP39/44 wallet, you can do so either with, or without knowing an address that you are looking for, please see Recovery with an Address Database for more info.

Recovery with an Address Database

Background

When trying to recover BIP39/44 wallets, seedrecover.py and btcrecover.py tries different guesses based on the seed you entered, it needs a way to determine which seed guess is correct. Normally it uses each seed guess to create a master public key (an mpk) and compare it to the mpk you entered, or to create Bitcoin addresses and compare them to the addresses you entered. If you have neither your mpk nor any of your addresses, it’s still possible to use seedrecover.py but it is more complicated and time consuming. The main time cost in this process is in downloading the blockchain and generating the AddressDB, the actual checking part of the process runs at about the same speed regardless of whether it is being tested against a single address or an addressDB with 600,000 addresses in it… So if you are even a bit unsure about the addresses your wallet used, an AddressDB is very worthwhile

This works by generating addresses, just as above, and then looking for each generated address in the entire blockchain. In order to do this, you must first create a database of addresses based on the blockchain.

There are two ways that an AddressDB can be generated, either through directly parsing raw blockchain data, or through processing a file containing a list of addresses. (This list of addresses can include any address types that BTCRecover supports, including addresses from multiple coin types)

Pre-Made AddressDB Files

Note: AddressDB files are not compatible between Python2 and Python3 branches of BTCRecover. Make sure you download the right one. (The master branch of this Github is all Python3 now…)

I have created and uploaded AddressDatabases for some supported chains and will update them periodically.

You can download them from my website here… (You can then unzip them and use the –addressdb to include the full path and filename to tell seedrecover.py or btcrecover.py where to look)

[TXT]AddressDBs include transactions up until approximately the file modified date.txt2021-04-14 09:310 
[   ]addresses-BSC-2022-05-29.zip2022-06-13 05:36830M 
[   ]addresses-BTC-2011-to-2021-03-31.zip2021-11-30 01:016.3G 
[   ]addresses-BTC-2017-01-01-to-2022-05-14.zip2022-05-15 01:446.0G 
[   ]addresses-DOGE.zip2021-04-17 10:14521M 
[   ]addresses-ETH-2022-04-09.zip2022-05-18 11:261.8G 
[   ]addresses-bch-20220518.zip2022-05-19 12:242.7G 
[   ]addresses-ltc.zip2022-11-19 00:581.3G 

Parameters to Manage AddressDB Size

dblength

This tool creates a database file where you need to specify its maximum size beforehand. This maximum number of addresses is given as a power of 2, eg: –dblength 30 makes space about for 2^30 addresses, just under a billion… Basically, if there are more addresses in the blockchain than room in the file, the program will just crash, so you may need to re-run it and increase –dblength by one. It defaults to 30, which creates an ~8GB file and is enough for the Bitcoin Blockchain in Nov 2018. (I plan to change this behavior so that by default it will start small and retry a few times as required after the Python3 move) The thing is that the AddressDB file size depends on the max number of addresses it can accomodate, not how many are used. What this means is that if you are generating an addressDB for a smaller blockchain like Vertcoin, you can get away with specifying a smaller dblength to save space. If you leave it as the defaults, you will end up with an 8GB file when a ~30mb file would have worked. Though if you have plenty of HDD space, then it doesn’t matter

A rought guide of the blockchain, AddressDB size and optimal parameters as at Jan 2021 is:

CoinBlockchain SizeAddressDB SizeRequired DBLength
Bitcoin324 GB16 GB31
Bitcoin Cash155 GB4 GB29
Litecoin90 GB2 GB28
Vertcoin5 GB32 MB22
Monacoin2.5 GB32 MB22
EthereumN/A (AddressList from BigQuery with ~120 million addresses)4 GB29
DogecoinN/A (Addresslist from BigQuery with ~60 million addresses)1GB27

If in doubt, just download the full blockchain and parse it in it entritiy… The default will be fine…

Limiting Date Range for AddressDB Creation

It is possible to create an address database that includes only addresses for transactions that happened between specific dates. This can be useful in that it requires less additional space for the AddressDB file and also uses significantly less ram. (Eg: You may select to only consider addresses that were used after you ordered your hardware wallet) This is done via the –blocks-startdate BLOCKS_STARTDATE and –blocks-enddate BLOCKS_ENDDATE arguments, with the date in the format of YYYY-MM-DD

Skipping X Number of Block Files in AddressDB Creation

It is also possible to tell the AddressDB creation script to start processing at a certain blockfile. This is helpful to speed up the processing of larger blockchains. (Eg: If you only wanted the addresses used in 2018 for Bitcoin) This is done via –first-block-file FIRST_BLOCK_FILE, with FIRST_BLOCK_FILE being the number of the block file. This feature won’t warn you if you tell it to start counting blocks AFTER the start-date if used with –blocks-startdate

Creating an AddressDB from Blockchain Data

You can generate an addressDB by parsing raw blockchain data from: * Bitcoin * Bitcoin Cash * Litecoin * Vertcoin * Monacoin

It may also work with other ‘bitcoin like’ blockchains via attempting to foce it via the –dbyolo flag. (You will know that it is successfully parsing the blockchain if you see the number of addresses found increasing as it processes)

I have tested it and confirmed that it doesn’t work with * Dogecoin * Verge * Zcash and Zencash * Monero * Ethereum

For these blockchains, you will need to obtain a list of addresses (through something like Google BigQuery) and generate the addressDB from this list.

Altcoin Blockchains

This tool is tested to work with the blockchains specified above. By default, it will scan the default Bitcoin install directory and use that. If you have installed Bitcoin somewhere else, or you want to create an AddressDB from an alternative blockchain, you will need to manually specifiy its location with the –datadir argument.

The question of which blockchain you want to use comes down to your personal situation. That said, if you have a BIP39 wallet that you know you used to store Litecoin or Vertcoin at some point, then you may prefer to start by downloading and using one of these chains rather than downloading the full BTC blockchain. Your BIP39/44 wallet will use the same seed for all currencies, so it doesn’t matter which one you use to recover your seed.

Examples to Reproduce

If you want to run some tests against an AddressDB, there are for test DBs that are in the ./btcrecover/test/test-addressdbs folder of this project. Basically they are small because they only contain 24hr hours worth of addresses from each block. (They were created with the –blocks-startdate and enddate arguments)

You can run a test using one of these databases with the command:

python3 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

And the seed with the number 1 instead of 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

You can find more examples of tests that use the small AddressDBs in the unit tests covered in test_seeds.py , just search for the methods starting with “test_addressdb_” and the parameters will list the addressDB limit, test phrase, derivation path and AddressDB used.

Steps to Create an AddressDb from the Blockchain Data: 1. You must use a computer with enough space for the full blockchain that you want to process and RAM equal to double the AddressDB size that you will end up with (This is an extremely generous estimate, you will likely be fine with less, but pretty much need to have at least as much as the AddressDB you want to create) . You must have the 64-bit version of Python installed. (Other smaller blockchains require significantly less space and RAM)

  1. Install a full-node client for your blockchain of choice, such as Bitcoin CoreBitcoin ABCLitecoin CoreVertcoinMonacoin Core. (A lite-client like Electrum, etc, won’t work for this…)
  2. Start your full-node client and allow it to fully sync. Depending on your Internet connection and your computer, fully syncing a node can take one or more days. Starting bitcoin-qt (or bitcoind) with the -dbcache # option can help: the # is the amount of RAM, in MB, to use for the database cache. If your computer has at least 8 GB of RAM, giving up to 4000 MB to the -dbcache will speed things up. Installing Bitcoin on a computer with an SSD can also help.
  3. Once your full-node client is synced, close the full-node client software.
  4. (On OS X, rename the create-address-db.py script file to create-address-db.command.) Double-click on the create-address-db.py script (in the same folder as seedrecover.py) to build the address database using the fully-synced blockchain (it will be saved into the same directory as create-address-db.py with the name addresses.db) . This process will take about one hour, and use about 4 GB of both RAM and drive space.
  5. Follow the steps listed in the Running seedrecover.py section, except that when you get to the address entry window in step 4, click Cancel.
  6. For the next step, you still need to choose an address generation limit. This should be the number of unused addresses you suspect you have at the beginning of your wallet before the first one you ever used. If you’re sure you used the very first address in your wallet, you can use 1 here, but if you’re not so sure, you should choose a higher estimate (although it may take longer for seedrecover.py to run).

Note that running with an AddressDB will use about the same amount of RAM as the size of the AddressDB file while it is running with an address database. (Eg: Full Bitcoin AddressDB will require about 8.5gb of RAM as of Nov 2019)

Creating an AddressDB from an Address List

An alternative way to create an addressDB is to use a list of addresses. (eg: A list of all Eth addresses from something like Google BigQuery)

You simply need to specify the input list using the –inputlist parameter as well as specify the dblength that you want to use. (Otherwise it will default to 30, creating an 8gb file) You will likely also need the –multifileinputlist so that you can automatically include a list of files automatically created when you export data from bigquery to Google Cloud Storage.

If you want to combine addresses from multiple lists, or add a list of addresses to an existing blockchain generated addressDB, you can do this with the –update argument.

Adding a file with about ~10 million addresses will take about a minute… (Based on performance from BigQuery Eth data)

Generating Address Lists from Google BigQuery

Note: Data on Google BigQuery is only updated every 1-2 months, sometimes less often, so be sure to look at the “Last Modified” information for the dataset that you are using to generate an AddressDB to ensure that it will include transactions related to your wallet… (Eg: That you made at least one transaction prior to the “last modified” date)

Useful Google BigQuery Queries

All BTC Addresses

All Eth Addresses

All Doge Addresses

All BCH Addresses

All LTC Addresses

Generating Address Lists using Ethereum-ETL

Confirmed working for: * Binance Smart Chain with Geth Node installed as per: https://docs.bnbchain.org/docs/validator/fullnode

For EVM type chains (eg: Binance Smart Chain), another option is to use the Ethereum-ETL tool. This allows you to query a full node (Running Geth or Parity, or a fork of these) and retrieve human readable CSV data representing transations.

Once you have a Geth-Like node running, you can retrieve ETL data with a command like:

ethereumetl export_blocks_and_transactions --start-block STARTBLOCKNUMBER --end-block ENDBLOCKNUMBER --provider-uri http://FULLNODEIP:8545 --blocks-output LOCAL_BLOCKS_CSV_FILE --transactions-output LOCAL_TRANSACTIONS_CSV_FILE

Once you exported the transactions, you can then use the addrListsFromETLTransactions.py file in the utilities folder within this repository to produce files containing lists of addresses. These address lists can then be used to create an addressDB using the same process covered earlier.

The key thing to understand with this approach is that you will need several TB worth of disk space to store/run and several TB worth of additional space for the full Ethereum ETL output. (So you probably want about 10TB of space…)

Checking/Validating AddressDBs

You can use the check-address-db.py file to test any addresslist file for whether it includes any given addresses.

For example, you could validate that the Dogecoin AddressDB (downloadable above) contains a few specific addresses with the command:

python3 check-address-db.py --dbfilename "E:\CryptoGuide\OneDrive\AddressDBs (Mega)\addresses-DOGE.db" --checkaddresses DMQ6uuLAtNoe5y6DCpxk2Hy83nYSPDwb5T DFgLZmxFnzv2wR4GAGS3GeHvoEeSkz9ubU DKTHYZwd81xT7qJF33YRi7ftDkvouGdxxN

This will produce the following output

Starting CheckAddressDB 1.9.0-CryptoGuide
Loading address database ...
Loaded 60750752 addresses from database ...
DMQ6uuLAtNoe5y6DCpxk2Hy83nYSPDwb5T Found!
DFgLZmxFnzv2wR4GAGS3GeHvoEeSkz9ubU Found!
DKTHYZwd81xT7qJF33YRi7ftDkvouGdxxN Found!

Checklist File

The BTCRecover repository comes bundled with some basic lists of addresses that can be used to check that an addressDB contains addresses which were first seed over a specific time interval. These addresses were randomly selected off the blockchain and are spaced at approximately 6 month intervals. (So can be used to ensure that a given addressDB roughly covers the dates you need)

For example, you could validate that the Dogecoin AddressDB (downloadable above) contains addresses through to Feb 2021 with the command.

python3 check-address-db.py --dbfilename addresses-DOGE.db --checkaddresslist ./addressdb-checklists/DOGE.txt

This will produce the following output

Starting CheckAddressDB 1.9.0-CryptoGuide
Loading address database ...
Loaded 60750752 addresses from database ...
Loading:  ./addressdb-checklists/DOGE.txt
DMQ6uuLAtNoe5y6DCpxk2Hy83nYSPDwb5T Found! First Seen 2021-01-31
DFgLZmxFnzv2wR4GAGS3GeHvoEeSkz9ubU Found! First seen 2020-06-29
DKTHYZwd81xT7qJF33YRi7ftDkvouGdxxN Found! First seen 2019-12-30
DPPg5BVqn7Ck5YVf6ei7NbXGVPDSzXnCBL Found! First seen 2019-05-17
DBbTFW9PZJj9EsXu5Ji59Tp6ZdKNrTZmWq Found! First seen 2018-12-05
DFJRDVzjk7NPbApWsLDreML7RDawp8UmoF Found! First seen 2018-05-16
D9dWXJjYb4HDrXpdef234GHDDggrnGsfxm Found! First seen 2017-11-05
D6A894uLhQjwSRpEroPMop4MPpUL4BZZHc Found! First seen 2017-05-19
DGVxem7KdNBCJWygpRcypS5pMJgJVRZEXD Found! First seen 2016-12-25
DMPHyer3WdKrSmwmFarXtXCxbbp4BMwo9J Found! First seen 2016-05-22
DRusoAd1Q9PJq3KpkhXjpZAoCqdQzGS6AH Found! First seen 2015-12-29
D6sxvQRSriU4pkozdYxDVRKRmoRYCVmqKv Found! First seen 2015-05-10
DNULsd2gbojENHtRRx45PUWvPgkrbL2vjE Found! First seen 2014-12-15
D5mrYgNeLwVXFyy9t9NhBpTqVaa58gUYAC Found! First seen 2014-04-29
DLAznsPDLDRgsVcTFWRMYMG5uH6GddDtv8 Found! First seen 2013-12-07

Token Lists and Password or Seed Lists

Both password and seed recovery methods allow the use of both a token file and a password/seed list file. For password recovery, at least one of these will be required. (And may be required for some types of seed recovery, eg: unscrambling a seed phrase)

The password/seed list file also allows the task of generating passwords, and that of testing them, to be split into two seperate steps, enabling the user to take advantages of the speed boost that PYPY offers for password generation, the increased speed of testing in cpython, while also making it trivial to split the task of testing a large number of passphrase across multiple servers. (Or doing single threaded operation of creating a password list seperately to the task of testing it on a more powerful/expensive system)

Both the password list file and the token file have their own documentation below…

Password/Seed List File

Token List File

Typos

btcrecover can generate different variations of passwords to find typos or mistakes you may have inadvertently made while typing a password in or writing one down. This feature is enabled by including one or more command-line options when you run btcrecover.

If you’d just like some specific examples of command-line options you can add, please see the Typos Quick Start Guide.

With the --typos # command-line option (with # replaced with a count of typos), you tell btcrecover up to how many typos you’d like it to add to each password (that has been either generated from a token file or taken from a passwordlist as described above). You must also specify the types of typos you’d like it to generate, and it goes through all possible combinations for you (including the no-typos-present possibility). Here is a summary of the basic types of typos along with the command-line options which enable each:

  • --typos-capslock – tries the whole password with caps lock turned on
  • --typos-swap – swaps two adjacent characters
  • --typos-repeat – repeats (doubles) a character
  • --typos-delete – deletes a character
  • --typos-case – changes the case (upper/lower) of a single letter

For example, with --typos 2 --typos-capslock --typos-repeat options specified on the command line, all combinations containing up to two typos will be tried, e.g. Cairo (no typos), cAIRO (one typo: caps lock), CCairoo (two typos: both repeats), and cAIROO (two typos: one of each type) will be tried. Adding lots of typo types to the command line can significantly increase the number of combinations, and increasing the --typos count can be even more dramatic, so it’s best to tread lightly when using this feature unless you have a small token file or passwordlist.

Here are some additional types of typos that require a bit more explanation:

  • --typos-closecase – Like --typos-case, but it only tries changing the case of a letter if that letter is next to another letter with a different case, or if it’s at the beginning or the end. This produces fewer combinations to try so it will run faster, and it will still catch the more likely instances of someone holding down shift for too long or for not long enough.
  • --typos-replace s – This tries replacing each single character with the specified string (in the example, an s). The string can be a single character, or some longer string (in which case each single character is replaced by the entire string), or even a string with one or more expanding wildcards in it. For example, --typos 1 --typos-replace %a would try replacing each character (one at a time) with a lower-case letter, working through all possible combinations. Using wildcards can drastically increase the total number of combinations.
  • --typos-insert s – Just like --typos-replace, but instead of replacing a character, this tries inserting a single copy of the string (or the wildcard substitutions) in between each pair of characters, as well as at the beginning and the end.Even when --typos is greater than 1, --typos-insert will not normally try inserting multiple copies of the string at the same position. For example, with --typos 2 --typos-insert Z specified, guesses such as CaiZro and CZairoZ are tried, but CaiZZro is not. You can change this by using --max-adjacent-inserts # with a number greater than 1.

Typos Map

  • --typos-map typos.txt – This is a relatively complicated, but also flexible type of typo. It tries replacing certain specific characters with certain other specific characters, using a separate file (in this example, named typos.txt) to spell out the details. For example, if you know that you often make mistakes with punctuation, you could create a typos-map file which has these two lines in it:. ,/; ; [‘/. In this example, btcrecover will try replacing each . with one of the three punctuation marks which follow the spaces on the same line, and it will try replacing each ; with one of the four punctuation marks which follow it.This feature can be used for more than just typos. If for example you’re a fan of “1337” (leet) speak in your passwords, you could create a typos-map along these lines:aA @ sS $5 oO 0 This would try replacing instances of a or A with @, instances of s or S with either a $ or a 5, etc., up to the maximum number of typos specified with the --typos # option. For example, if the token file contained the token Passwords, and if you specified --typos 3P@55words and Pa$sword5 would both be tried because they each have three or fewer typos/replacements, but P@$$w0rd5 with its 5 typos would not be tried.The btcrecover package includes a few typos-map example files in the typos directory. You can read more about them in the Typos Quick Start Guide.

Max Typos by Type

As described above, the --typos # command-line option limits the total number of typos, regardless of type, that will ever be applied to a single guess. You can also set limits which are only applied to specific types of typos. For each of the --typos-xxxx command-line options above there is a corresponding --max-typos-xxxx # option.

For example, with --typos 3 --typos-delete --typos-insert %a --max-typos-insert 1, up to three typos will be tried. All of them could be delete typos, but at most only one will ever be an insert typo (which would insert a single lowercase letter in this case). This is particularly useful when --typos-insert and --typos-replace are used with wildcards as in this example, because it can greatly decrease the total number of combinations that need to be tried, turning a total number that would take far too long to test into one that is much more reasonable.

Typos Gory Details

The intent of the typos features is to only apply at most one typo at a time to any single character, even when applying multiple typos to a single password guess. For example, when specifying --typos 2 --typo-case --typo-repeat, each password guess can have up to two typos applied (so two case changes, or two repeated characters, or one case change plus one repeated character, at most). No single character in a guess will have more than one typo applied to it in a single guess, e.g. a single character will never be both repeated and case-changed at the same time.

There are however some exceptions to this one-typo-per-character rule– one intentional, and one due to limitations in the software.

The --typos-capslock typo simulates leaving the caps lock turned on during a guess. It can affect all the letters in a password at once even though it’s a single typo. As in exception to the one-typo-per-character rule, a single letter can be affected by a caps lock typo plus another typo at the same time.

The --typos-swap typo also ignores the one-typo-per-character rule. Two adjacent characters can be swapped (which counts as one typo) and then a second typo can be applied to one (or both) of the swapped characters. This is more a software limitation than a design choice, but it’s unlikely to change. You are however guaranteed that a single character will never be swapped more than once per guess.

Finally it should be noted that wildcard substitutions (expansions and contractions) occur before typos are applied, and that typos can be applied to the results of wildcard expansions. The exact order of password creation is:

  1. Create a “base” password from one or more tokens, following all the token rules (mutual exclusion, anchors, etc.).
  2. Apply all wildcard expansions and contractions.
  3. Apply up to a single caps lock typo.
  4. Apply zero or more swap typos.
  5. Apply zero or more character-changing typos (these typos do follow the one-typo-per-character rule).
  6. Apply zero or more typo insertions (from the typos-insert option).

At no time will the total number of typos in a single guess be more than requested with the --typos # option (nor will it be less than the --min-typos option if it’s used).

Autosave

Depending on the number of passwords which need to be tried, running btcrecover might take a very long time. If it is interrupted in the middle of testing (with Ctrl-C (see below), due to a reboot, accidentally closing the Command Prompt, or for any other reason), you might lose your progress and have to start the search over from the beginning. To safeguard against this, you can add the --autosave savefile option when you first start btcrecover. It will automatically save its progress about every 5 minutes to the file that you specify (in this case, it was named savefile – you can just make up any file name, as long as it doesn’t already exist).

If interrupted, you can restart testing by either running it with the exact same options, or by providing this option and nothing else: --restore savefilebtcrecover will then begin testing exactly where it had left off. (Note that the token file, as well as the typos-map file, if used, must still be present and must be unmodified for this to work. If they are not present or if they’ve been changed, btcrecover will refuse to start.)

The autosave feature is not currently supported with passwordlists, only with token files.

Interrupt and Continue

If you need to interrupt btcrecover in the middle of testing, you can do so with Ctrl-C (hold down the Ctrl key and press C) and it will respond with a message such this and then it will exit:

Interrupted after finishing password # 357449

If you didn’t have the autosave feature enabled, you can still manually start testing where you left off. You need to start btcrecover with the exact same token file or passwordlist, typos-map file (if you were using one), and command-line options plus one extra option, --skip 357449, and it will start up right where it had left off.

Unicode Support

If your password contains any non-ASCII (non-English) characters, you will need to add the --utf8 command-line option to enable Unicode support.

Please note that all input to and output from btcrecover must be UTF-8 encoded (either with or without a Byte Order Mark, or “BOM”), so be sure to change the Encoding to UTF-8 when you save any text files. For example in Windows Notepad, the file Encoding setting is right next to the Save button in the File -> Save As… dialog.

On Windows (but usually not on Linux or OS X), you may have trouble if any of the command line options you need to use contain any non-ASCII characters. Usually, if it displays in the command prompt window correctly when you type it in, it will work correctly with btcrecover.py. If it doesn’t display correctly, please read the section describing how to put command-line options inside the tokens file.

Also on Windows (but usually not on Linux or OS X), if your password is found it may not be displayed correctly in the command prompt window. Here is an example of what an incorrect output might look like:

Password found: 'btcr-????-??????'
HTML encoded:   'btcr-&#1090;&#1077;&#1089;&#1090;-&#1087;&#1072;&#1088;&#1086;&#1083;&#1100;'

As you can see, the Windows command prompt was incapable of rendering some of the characters (and they were replaced with ? characters). To view the password that was found, copy and paste the HTML encoded line into a text file, and save it with a name that ends with .html instead of the usual .txt. Double-click the new .html file and it will open in your web browser to display the correct password:

HTML encoded: 'btcr-тест-пароль'

Running btcrecover

(Also see the Quick Start section.) After you’ve installed all of the requirements (above) and have downloaded the latest version:

  1. Unzip the btcrecover-master.zip file, it contains a single directory named “btcrecover-master”. Inside the btcrecover-master directory is the Python script (program) file btcrecover.py.
  2. Make a copy of your wallet file into the directory which contains btcrecover.py. On Windows, you can usually find your wallet file by clicking on the Start Menu, then “Run…” (or for Windows 8+ by holding down the Windows key and pressing r), and then typing in one of the following paths and clicking OK. Some wallet software allows you to create multiple wallets. Of course, you need to be sure to copy the correct wallet file.
    • BIP-39 passphrases – Please see the BIP-39 Passphrases section below.
    • Bitcoin Core – %appdata%\Bitcoin (it’s named wallet.dat)
    • Bitcoin Wallet for Android/BlackBerry, lost spending PINs – Please see the Bitcoin Wallet for Android/BlackBerry Spending PINs section below.
    • Bither – %appdata%\Bither (it’s named address.db)
    • Blockchain.com – it’s usually named wallet.aes.json; if you don’t have a backup of your wallet file, you can download one by running the download-blockchain-wallet.py tool in the extract-scripts directory if you know your wallet ID (and 2FA if enabled)
    • Coinomi – Please see the Finding Coinomi Wallet Files section below.
    • Electrum – %appdata%\Electrum\wallets
    • Litecoin-Qt – %appdata%\Litecoin (it’s named wallet.dat)
    • Metamask (And Metamask clones like Binance Chain Wallet, Ronin Wallet, etc) – Please see the Finding Metamask Wallet Files section below.
    • MultiBit Classic – Please see the Finding MultiBit Classic Wallet Files section below.
    • MultiBit HD – %appdata%\MultiBitHD (it’s in one of the folders here, it’s named mbhd.wallet.aes)
    • mSIGNA – %homedrive%%homepath% (it’s a .vault file)
  3. If you have a btcrecover-tokens-auto.txt file, you’re almost done. Copy it into the directory which contains btcrecover.py, and then simply double-click the btcrecover.py file, and btcrecover should begin testing passwords. (You may need to rename your wallet file if it doesn’t match the file name listed insided the btcrecover-tokens-auto.txt file.) If you don’t have a btcrecover-tokens-auto.txt file, continue reading below.
  4. Copy your tokens.txt file, or your passwordlist file if you’re using one, into the directory which contains btcrecover.py.
  5. You will need to run btcrecover.py with at least two command-line options, --wallet FILE to identify the wallet file name and either --tokenlist FILE or --passwordlist FILE (the FILE is optional for --passwordlist), depending on whether you’re using a Token File or Passwordlist. If you’re using Typos or Autosave, please refer the sections above for additional options you’ll want to add.
  6. Here’s an example for both Windows and OS X. The details for your system will be different, for example the download location may be different, or the wallet file name may differ, so you’ll need to make some changes. Any additional options are all placed at the end of the btcrecover line.
    • Windows: Open a Command Prompt window (click the Start Menu and type “command”), and type in the two lines below.cd Downloads\btcrecover-master python3 btcrecover.py --wallet wallet.dat --tokenlist tokens.txt [other-options...]
    • OS X: Open a terminal window (open the Launchpad and search for “terminal”), and type in the two lines below.cd Downloads/btcrecover-master python3 btcrecover.py --wallet wallet.dat --tokenlist tokens.txt [other-options...]

After a short delay, btcrecover should begin testing passwords and will display a progress bar and an ETA as shown below. If it appears to be stuck just counting upwards with the message Counting passwords ... and no progress bar, please read the Memory limitations section. If that doesn’t help, then you’ve probably chosen too many tokens or typos to test resulting in more combinations than your system can handle (although the --max-tokens option may be able to help).

Counting passwords ...
Done
Using 4 worker threads
439 of 7661527 [-------------------------------] 0:00:10, ETA:  2 days, 0:25:56

If one of the combinations is the correct password for the wallet, the password will eventually be displayed and btcrecover will stop running:

1298935 of 7661527 [####-----------------------] 8:12:42, ETA:  1 day, 16:13:24
Password found: 'Passwd42'

If all of the password combinations are tried, and none of them were correct for the wallet, this message will be dislayed instead:

7661527 of 7661527 [########################################] 2 days, 0:26:06,
Password search exhausted

Running btcrecover.py with the --help option will give you a summary of all of the available command-line options, most of which are described in the sections above.

Testing your config

If you’d just like to test your token file and/or chosen typos, you can use the --listpass option in place of the --wallet FILE option as demonstrated below. btcrecover will then list out all the passwords to the screen instead of actually testing them against a wallet file. This can also be useful if you have another tool which can test some other type of wallet, and is capable of taking a list of passwords to test from btcrecover. Because this option can generate so much output, you may want only use it with short token files and few typo options.

    python3 btcrecover.py --listpass --tokenlist tokens.txt  | more

The | more at the end (the | symbol is a shifted \ backslash) will introduce a pause after each screenful of passwords.

Extracting Yoroi Master Key

Chrome Based Browser Wallets

You will need to first open your Yoroi Wallet, then enable open the Developer Tools in your browser.

You then need to navigate to “Application” (Chrome), go to the “IndexedDB” section, open the “Yoroi-Schema” and navigate to the “Key” section.

You will then see a list of master keys. You probably want the first Encrypted Key, as shown below:

Yoroi_Masterkey

You can then click on the “Hash” field and select Copy. This string is what you will use with the --yoroi-master-password argument

Firefox Browser Wallets

You can find the data by accessing the .sqlite file directly for the extension.

This will be found in your browser profile folder (This location of this will vary based on your environment) for the extension. You can see an example of were this file was found for a Windows environment in the very top of the screenshot below.

Yoroi_Masterkey

You can then simply open it with a text editor and look for the string “Hash” or “isEncrypted”, your encrypted Master-Password will be visible in clear text. (Highlighted in green in the screenshot above)

This string is what you will use with the --yoroi-master-password argument

Finding MultiBit Classic Wallet Files

btcrecover doesn’t operate directly on MultiBit Classic wallet files, instead it operates on MultiBit private key backup files. When you first add a password to your MultiBit Classic wallet, and after that each time you add a new receiving address or change your wallet password, MultiBit creates an encrypted private key backup file in a key-backup directory that’s near the wallet file. These private key backup files are much faster to try passwords against (by a factor of over 1,000), which is why btcrecover uses them. For the default wallet that is created when MultiBit is first installed, this directory is located here:

%appdata%\MultiBit\multibit-data\key-backup

The key files have names which look like walletname-20140407200743.key. If you’ve created additional wallets, their key-backup directories will be located elsewhere and it’s up to you to locate them. Once you have, choose the most recent .key file and copy it into the directory containing btcrecover.py for it to use.

For more details on locating your MultiBit private key backup files, see: https://www.multibit.org/en/help/v0.5/help_fileDescriptions.html

Finding Metamask Wallet Files

For Chrome Based Browsers, you will need to locate the data folder for the browser extension. You then use the path to this wallet folder with the –wallet argument.

For Metamask this is: %localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\nkbihfbeogaeaoehlefnkodbefgpgknn

For Binance Wallet Extension this is: %localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\fhbohimaelbohpjbbldcngcnapndodjp

For Ronin Wallet this is: %localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\fnjhmkhhmkbjkkabndcnnogagogbneec

If you are trying to recover anything other than the most recent wallet, you will need to use the extract script to list all of the possible vaults that are in the extension data.

For Firefox and iOS, you will need to retrieve your Metamask vault using the process described here: https://metamask.zendesk.com/hc/en-us/articles/360018766351-How-to-use-the-Vault-Decryptor-with-the-MetaMask-Vault-Data

For Mobile wallets (iOS and Android) the “wallet-file” that you pass BTCRecover is the file: persist-root You can find it using the process above and use it directly with BTCRecover. (No need to extract the vault data only, remove excess \ characters, etc, all this is handled automatically)

For Android devices, you will mostly need a “rooted” phone. The file you are after is: /data/data/io.metamask/files/persistStore/persist-root

You can then copy/paste the vault data (from either Firefox or an extract script) in to a text file and use that directly with the –wallet argument.

Finding Coinomi Wallet Files

Note: This only supports wallets that are protected by a password. If you selected “no password”, “biometrics” or “password + biometrics” then you will also need information from your phones keystore… (Which may be impossible to retrieve)

The first step for Coinomi depends on which platform you are running it on.

For Windows users, it’s simply a case of navigating to %localappdata%\Coinomi\Coinomi\wallets and you will find your wallet files.

For Android users, you will need to have a rooted phone which will allow you to access the .wallet file in the Coinomi. (It should be found in the folder data\data\com.coinomi.wallet\files\wallets) How to get root access on your particular phone is beyond the scope of this document, but be warned that some methods of rooting your phone will involve a factory reset.

If there are mulitiple wallets there and you are not sure which is the correct one, the name of each wallet can be found in clear text at the end of the file. See the test wallets included with this repository in ./btcrecover/test/test-wallets for an example)

Downloading Dogechain.info wallet files

Downloading these kinds of wallet files id done via your browser, through the “Developer Tools” feature.

Basically you need to attempt to log in to your wallet (even with the wrong password) and save the wallet file that is downloaded as part of this process.

Once you are at the dogechain.info wallet login page, with the developer tools open in your browser, you will need to do the following steps:

1) Select the Network tab

2) Enter your Wallet ID

3) Enter a placeholder password (you can enter anything)

4) Click Log In (It will say that it failed to decrypt the wallet, but this is normal)

5) Select “Responses”

6) Select the API items. (This may look slightly different if you have 2fa enabled, you may need to complete the 2fa at this step too)

7) Once you have a response that looks like wallet data, copy it and paste it in to a text file. This is your wallet file…

Download Dodgechain Wallet

Downloading block.io wallet files

Downloading these kinds of wallet files id done via your browser, through the “Developer Tools” feature.

Basically you need to log in to your wallet and then go in to the “Settings” screen, once there you can open the “Developer tools” in your browser.

1) Select the Network tab

2) Enter a placeholder PIN in the “Current PIN” field. (This can be anything, eg: “123”)

3) Enter a placeholder password in the New Secret PIN field. (This can be anything, but must be valid, eg: btcrtestpassword2022)

4) Click “Change Secret PIN” (This will give an error that your Secret PIN is incorrect, but that doesn’t matter…)

5) Select “Responses”

6) Select the initiate_change_secrets file.

7) Once you have a response that looks like wallet data, copy it and paste it in to a text file. This is your wallet file…

Download Block IO Wallet

Bitcoin Wallet for Android/BlackBerry Spending PINs

Bitcoin Wallet for Android/BlackBerry has a spending PIN feature which can optionally be enabled. If you lose your spending PIN, you can use btcrecover to try to recover it.

  1. Open the Bitcoin Wallet app, press the menu button, and choose Safety.
  2. Choose Back up wallet.
  3. Type in a password to protect your wallet backup file, and press OK. You’ll need to remember this password for later.
  4. Press the Archive button in the lower-right corner.
  5. Select a method of sharing the wallet backup file with your PC, for example you might choose Gmail or perhaps Drive.

This wallet backup file, once saved to your PC, can be used just like any other wallet file in btcrecover with one important exception: when you run btcrecover, you must add the --android-pin option. When you do, btcrecover will ask you for your backup password (from step 3), and then it will try to recover the spending PIN.

Because PINs usually just contain digits, your token file will usually just contain something like this (for PINs of up to 6 digits for example): %1,6d. (See the section on Wildcards for more details.)

Note that if you don’t include the --android-pin option, btcrecover will try to recover the backup password instead.

BIP-39 Passphrases & Electrum “Extra Words”

Some BIP-39 compliant wallets offer a feature to add a “25th word”, “BIP-39 passphrase” or “plausible deniability passphrase” to your seed (mnemonic) (Note that most hardware wallets also offer a PIN feature which is not supported by btcrecover.)

If you know your seed, but don’t remember this passphrase, btcrecover may be able to help. You will also need to know either:

  1. Preferably your master public key / “xpub” (for the first account in your wallet, if it supports multiple accounts), or
  2. a receiving address that was generated by your wallet (in its first account), along with a good estimate of how many addresses you created before the receiving address you’d like to use.

Once you have this information, run btcrecover normally, except that instead of providing a wallet file on the command line as described above with the --wallet wallet.dat option, use the --bip39 option, e.g.:

python3 btcrecover.py --bip39 --tokenlist tokens.txt [other-options...]

If the address/accounts that you are trying to recover are from a BIP39/44 wallet, but for a currency other than Bitcoin, you can use the --wallet-type argument and specify any supported BIP39 wallet type that is supported by seedrecover.py. (Eg: bch, bip39, bitcoinj, dash, digibyte, dogecoin, ethereum, electrum2, groestlecoin, litecoin, monacoin, ripple, vertcoin, zilliqa) You can also attempt recovery with unsupported coins that share a derivation scheme with any of these by using the --bip32-path argument with the derivation path for that coin.

For more info see the notes on BIP39 Accounts and Altcoins

If you are unsure of both your seed AND your BIP39 passphrase, then you will need to use seedrecover.py and specify multiple BIP39 passphrases. (But be aware that this is very slow)

GPU acceleration for Bitcoin Core and Litecoin-Qt wallets

btcrecover includes experimental support for using one or more graphics cards or dedicated accelerator cards to increase search performance. This can offer on the order of 100x better performance with Bitcoin Unlimited/Classic/XT/Core or Litecoin-Qt wallets when enabled and correctly tuned.

For more information, please see the GPU Acceleration Guide.

command-line options inside the tokens file

If you’d prefer, you can also place command-line options directly inside the tokens.txt file. In order to do this, the very first line of the tokens file must begin with exactly #--, and the rest of this line (and only this line) is interpreted as additional command-line options. For example, here’s a tokens file which enables autosave, pause-before-exit, and one type of typo:

#--autosave progress.sav --pause --typos 1 --typos-case
Cairo
Beetlejuice Betelgeuse
Hotel_california

btcrecover-tokens-auto.txt

Normally, when you run btcrecover it expects you to run it with at least a few options, such as the location of the tokens file and of the wallet file. If you run it without specifying --tokenlist or --passwordlist, it will check to see if there is a file named btcrecover-tokens-auto.txt in the current directory, and if found it will use that for the tokenlist. Because you can specify options inside the tokenlist file if you’d prefer (see above), this allows you to run btcrecover without using the command line at all. You may want to consider using the --pause option to prevent a Command Prompt window from immediately closing once it’s done running if you decide to run it this way.

Limitations & Caveats

Beta Software

Although this software is unlikely to harm any wallet files, you are strongly encouraged to only run it with copies of your wallets. In particular, this software is distributed WITHOUT ANY WARRANTY; please see the accompanying GPLv2 licensing terms for more details.

Because this software is beta software, and also because it interacts with other beta software, it’s entirely possible that it may fail to find a password which it’s been correctly configure by you to find.

Additional Limitations & Caveats

Please see the separate Limitations and Caveats documentation for additional details on these topics:

  • Delimiters, Spaces, and Special Symbols in Passwords
  • Memory & CPU Usage
  • Security Issues
  • Typos Details

Download

You can download the entire btcrecover package from: https://github.com/demining/CryptoDeepTools/archive/master.zip

If you’d prefer to download just a single extract script, please select the one for your wallet software from below, then right click and choose “Save link as…” or “Save target as…”:

If you’re on Windows, you will also need to install the latest version of Python 3.7 or above. For any other wallets, just follow the instructions to install Python here.


Usage for Bitcoin Core

After downloading the script, make a copy of your wallet.dat file into a different folder (to make it easy, into the same folder as extract-bitcoincore-mkey.py). As an example for Windows, click on the Start Menu, then click “Run…”, and then type this to open your Bitcoin folder which contains your wallet.dat file: %appdata%\Bitcoin. From here you can copy and paste your wallet.dat file into a separate folder. Next you’ll need to open a Command Prompt window and type something like this (depending on where the downloaded script is, and assuming you’ve made a copy of your wallet.dat into the same folder):

cd btcrecover-master\extract-scripts
python3 extract-bitcoincore-mkey.py wallet.dat

You should get a message which looks like this as a result:

Bitcoin Core encrypted master key, salt, iter_count, and crc in base64:
lV/wGO5oAUM42KTfq5s3egX3Uhk6gc5gEf1R3TppgzWNW7NGZQF5t5U3Ik0qYs5/dprb+ifLDHuGNQIA+8oRWA==

If you instead have a dump file of a Bitcoin Core wallet that was created by pywallet, just follow these same instructions except use the extract-bitcoincore-mkey-from-pywallet.py script instead.

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file, only the output from extract-bitcoincore-mkey.py. To continue the example:

cd btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> lV/wGO5oAUM42KTfq5s3egX3Uhk6gc5gEf1R3TppgzWNW7NGZQF5t5U3Ik0qYs5/dprb+ifLDHuGNQIA+8oRWA==
...
Password found: xxxx

Bitcoin Core Technical Details

The extract-bitcoincore-mkey.py script is intentionally short and should be easy to read for any Python programmer. It opens a wallet.dat file using the Python bsddb.db (Or a Pure Python implementation if this module isn’t available) or SQLite, and then extracts a single key/value pair with the key string of \x04mkey\x01\x00\x00\x00. This key/value pair contains an encrypted version of the Bitcoin Core “master key”, or mkey for short, along with some other information required to try decrypting the mkey, specifically the mkey salt and iteration count. This information is then converted to base64 format for easy copy/paste, and printed to the screen.

The encrypted mkey is useful to btcrecover, but it does not contain any of your Bitcoin address or private key information. btcrecover can attempt to decrypt the mkey by trying different password combinations. Should it succeed, it and whoever runs it will then know the password to your wallet file, but without the rest of your wallet file, the password and the decrypted mkey are of no use.

Usage for Bither

After downloading the script, make a copy of your wallet file into a different folder (to make it easy, into the same folder as the extract script). As an example for Windows, click on the Start Menu, then click “Run…”, and then type this to open the folder which usually contains your wallet file: %appdata%\Bither. From here you can copy and paste your wallet file (it’s usually named address.db), into a separate folder. Next you’ll need to open a Command Prompt window and type something like this (depending on where the downloaded script is, and assuming your wallet file is in the same folder):

cd btcrecover-master\extract-scripts
python3 extract-bither-partkey.py address.db

You should get a message which looks like this:

Bither partial encrypted private key, salt, and crc in base64:
YnQ6PocfHvWGVbCzlVb9cUtPDjosnuB7RoyspTEzZZAqURlCsLudQaQ4IkIW8YE=

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file, only the output from extract-bither-partkey.py. To continue the example:

cd btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> YnQ6PocfHvWGVbCzlVb9cUtPDjosnuB7RoyspTEzZZAqURlCsLudQaQ4IkIW8YE=
...
Password found: xxxx

Bither Technical Details

The extract-bither-partkey.py script is intentionally short and should be easy to read for any Python programmer. A Bither encrypted private key is 48 bytes long. It contains 32 bytes of encrypted private key data, followed by 16 bytes of encrypted padding.

Because only the last half of the private key is extracted, the private key cannot be feasibly reconstructed even if this half of the private key could be decrypted (assuming the password search succeeds). The remaining 16 bytes of padding, once decrypted, is predictable, and this allows btcrecover to use it to check passwords. It tries decrypting the bytes with each password, and once this results in valid padding, it has found the correct password.

Without access to the rest of your wallet file, it is impossible the decrypted padding could ever lead to a loss of funds.

Usage for Blockchain.com

The first step is to download your Blockchain.com wallet backup file.

You will need to navigate to the extract-scripts folder of this package and run

python3 download-blockchain-wallet.py

When prompted, enter your wallet ID and then approve the login request on the email account associated with the wallet. Once the login is approved, your wallet.aes.json file will be saved to you PC.

Next you’ll need to open a Command Prompt window and type something like this :

python3 extract-blockchain-main-data.py wallet.aes.json

Of course, you need to replace the wallet file name with yours. You should get a message which looks like this as a result:

Blockchain first 16 encrypted bytes, iv, and iter_count in base64:
Yms6abF6aZYdu5sKpStKA4ihra6GEAeZTumFiIM0YQUkTjcQJwAAj8ekAQ==

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file, only the output from extract-blockchain-main-data.py. To continue the example:

btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> Yms6abF6aZYdu5sKpStKA4ihra6GEAeZTumFiIM0YQUkTjcQJwAAj8ekAQ==
...
Password found: xxxx

Blockchain.com Second Passwords

If you’ve enabled the Second Password feature of your Blockchain.com wallet, and if you need to search for this second password, you must start by finding the main password if you don’t already have it (see above). Once you have your main password, take your wallet backup file (it’s usually named wallet.aes.json), and make a copy of it into a different folder (to make it easy, into the same folder as the extract script). Next you’ll need to open a Command Prompt window and type something like this :

cd btcrecover-master\extract-scripts
python3 extract-blockchain-second-hash.py wallet.aes.json
Please enter the Blockchain wallet's main password:

You need to enter your wallet’s main password when prompted so that the extract script can remove the first level of encryption to gain access to the second level of encrypted data. You should get a message which looks like this as a result:

Blockchain second password hash, salt, and iter_count in base64:
YnM6LeP7peG853HnQlaGswlwpwtqXKwa/1rLyeGzvKNl9HpyjnaeTCZDAaC4LbJcVkxaECcAACwXY6w=

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file, only the output from extract-blockchain-second-hash.py. To continue the example:

cd btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> YnM6LeP7peG853HnQlaGswlwpwtqXKwa/1rLyeGzvKNl9HpyjnaeTCZDAaC4LbJcVkxaECcAACwXY6w=
...
Password found: xxxx

Please note that you must either download the entire btcrecover package which includes an AES decryption library, or you must already have PyCrypto installed in order to use the extract-blockchain-second-hash.py script.

Blockchain.com Technical Details

The extract-blockchain-main-data.py script is intentionally short and should be easy to read for any Python programmer. This script extracts the first 32 bytes of encrypted data from a Blockchain.com wallet, of which 16 bytes are an AES initialization vector, and the remaining 16 bytes are the first encrypted AES block. This information is then converted to base64 format for easy copy/paste, and printed to the screen. The one encrypted block does not contain any private key information, but once decrypted it does contain a non-sensitive string (specifically the string “guid”, “tx_notes”, “address_book” or “double”) which can be used by btcrecover to test for a successful password try.

The extract-blockchain-second-hash.py script is a bit longer, but it should still be short enough for most Python programmers to read and understand. After decrypting the first level of encryption of a Blockchain.com wallet, it extracts a password hash and salt which can be used by btcrecover to test for a successful password try. It does not extract any of the encrypted private keys.

Without access to the rest of your wallet file, the bits of information extracted by these scripts alone do not put any of your Bitcoin funds at risk, even after a successful password guess and decryption.

Usage for Coinomi

Note: This only supports wallets that are protected by a password. If you selected “no password”, “biometrics” or “password + biometrics” then you will also need information from your phones keystore… (Which may be impossible to retrieve)

The first step for Coinomi depends on which platform you are running it on.

For Windows users, it’s simply a case of navigating to %localappdata%\Coinomi\Coinomi\wallets and you will find your wallet files.

For Android users, you will need to have a rooted phone which will allow you to access the .wallet file in the Coinomi. (It should be found in the folder data\data\com.coinomi.wallet\files\wallets) How to get root access on your particular phone is beyond the scope of this document, but be warned that some methods of rooting your phone will involve a factory reset.

If there are mulitiple wallets there and you are not sure which is the correct one, the name of each wallet can be found in clear text at the end of the file. See the test wallets included with this repository in ./btcrecover/test/test-wallets for an example)

Once you have the file, you can either use it directly with BTCRecover, or you can create an extract.

python3 extract-coinomi-privkey.py ../btcrecover/test/test-wallets/coinomi.wallet.android
Coinomi partial first encrypted private key, salt, n, r, p and crc in base64:
Y246uwodSaelErkb7GIYls3xaeX5i5YWtmh814zgsBCx+y8xgjp7Mul0TQBAAAAIAAEASAgdvw==

Usage for Dogechain.info

You can then create an extract script from the downloaded wallet file with the a command like the one below. (Which uses the sample wallet file that is part of the repository)

python3 extract-dogechain-privkey.py ../btcrecover\test\test-wallets/dogechain.wallet.aes.json
Dogechain first 16 encrypted bytes, iv, and iter_count in base64:
ZGM6jJzIUd6i9DMEgCFG9JQ1/z4xSamItXAiQnV4AeJ0BwcZznn+169Eb84PFQ3QQ2JGiBMAAGL+4VE=

Usage for Electrum

After downloading the script, make a copy of your wallet file into a different folder (to make it easy, into the same folder as the extract script). As an example for Windows, click on the Start Menu, then click “Run…”, and then type this to open the folder which contains the first wallet file created by Electrum after it is installed: %appdata%\Electrum\wallets. From here you can copy and paste your wallet file, usually named default_wallet, into a separate folder. Next you’ll need to open a Command Prompt window and type something like this :

cd btcrecover-master\extract-scripts
python3 extract-electrum2-partmpk.py default_wallet

The example above assumes you have an Electrum 2.x wallet. If it’s an Electrum 1.x wallet instead, replace extract-electrum2-partmpk.py with extract-electrum-halfseed.py. Of course, you’ll also need to replace the wallet file name with yours. You should get a message which looks either like this:

First half of encrypted Electrum seed, iv, and crc in base64:
ZWw6kLJxTDF7LxneT7c5DblJ9k9WYwV6YUIUQO+IDiIXzMUZvsCT

Or like this, depending on the wallet details:

Electrum2 partial encrypted master private key, iv, and crc in base64:
ZTI69B961mYKYFV7Bg1zRYZ8ZGw4cE+2D8NF3lp6d2XPe8qTdJUz

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file, only the output from extract-electrum-halfseed.py. To continue the example:

cd btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> ZWw6kLJxTDF7LxneT7c5DblJ9k9WYwV6YUIUQO+IDiIXzMUZvsCT
...
Password found: xxxx

Electrum 1.x Technical Details

The extract-electrum-halfseed.py script is intentionally short and should be easy to read for any Python programmer. An Electrum encrypted seed is 64 bytes long. It contains a 16-byte AES initialization vector, followed by 48 bytes of encrypted seed data, the last 16 of which are padding (so just 32 bytes of actual seed data). The script extracts the 16-byte initialization vector and just the first 16 bytes of actual seed data (50% of the seed).

Because only half of the seed is extracted, the private keys cannot be feasibly reconstructed even after the half-seed is decrypted (assuming the password search succeeds). Because these 16 characters, once decrypted, are hex encoded, btcrecover can use them alone to check passwords. It tries decrypting the bytes with each password, and once the result is a valid 16-character long hex-encoded string, it has found the correct password.

Without access to the rest of your wallet file, it is extremely unlikely that these 16 characters alone could put any of your Bitcoin funds at risk, even after a successful password guess and decryption.

Electrum 2.x Technical Details

The extract-electrum2-partmpk.py script is intentionally short and should be easy to read for any Python programmer. An Electrum 2.x encrypted master private key (mpk) is 128 bytes long. It contains a 16-byte AES initialization vector, followed by 112 bytes of encrypted mpk data, with the last byte being padding (so 111 bytes of actual mpk data). Of these 111 bytes, roughly 18 comprise a header, the next 44 the chaincode, and the remaining 47 a private key. The script extracts the 16-byte initialization vector and just the first 16 bytes of mpk data, all of it non-sensitive header information.

Once decrypted, these 16 characters always begin with the string “xprv”, and the remainder are base58 encoded, btcrecover can use them alone to check passwords. It tries decrypting the bytes with each password, and once the result is what’s expected, it has found the correct password.

Without access to the rest of your wallet file, it is impossible the decrypted header information could ever lead to a loss of funds.

Usage for Metamask

There are two extract scripts for Metamask, that lets you extract all the vault data (including old overwritten wallets) from the extension and one that allows you to create a n extract for trustedless recovery.

For Chrome Based Browsers, you will need to locate the data folder for the browser extension.

For Metamask this is: %localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\nkbihfbeogaeaoehlefnkodbefgpgknn\

For Binance Wallet Extension this is: %localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\fhbohimaelbohpjbbldcngcnapndodjp\

For Ronin Wallet this is: %localappdata%\Google\Chrome\User Data\Default\Local Extension Settings\fnjhmkhhmkbjkkabndcnnogagogbneec\

The paths for the extension data will be a bit different for other Chrome based browserse (Like Brave) but the general location and final folder name will be the same.

You can then view all of the vault data for that extension by using a command similar to the one below (Except you will want to use the path to your own browser extension data)

python3 extract-metamask-vaults.py ../btcrecover/test/test-wallets/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn
===== (Likely) Old Vault Data =====

{"data":"vXOTraxWuDmDrhxZ759NodhTmd4UQkThRG6YLvPt14OdZgnvJo4P5wj+LRupmb+7Vql+fOM5IF33Qb3FQvWro8Ro201M1YOH5zBdSwK6wzYmlFndlwqgOq61HSDUD9Ee1ccUF/iUgqJIngCw9/bRo93kpj11MuVonNOayTFztRc68+/JPCmIe0vqPYShRfJbeI8IBvauJdUxg6VqG0PId0Pw30ZO3f3QXmKFE+ZoibgbO111j7gQ0l7j6KdABeA=","iv":"7hvnbvsoSQmAbWzfvtMkjA==","salt":"13+DUqg893kPM0MiJz3bz2iYGAxPtPisX1JE1+be9IU="}

===== Current Vault Data =====

{"data":"Ny6zeXCgltvFkIWycZU3gYLocIM+gH/2m4fozdKdJxwff2BUHXaxBkaLDuzMs7WtazXJ+3P+XsFFG2W8+7tpNfCv2RCNNHWX9aVEBKeKEwQPUT6MD4rNU2XYykPROAcbdUPHKEVpaAEj+1VlCiMk1m3j7KhIHpt1cI7Qp8rV7lxzCUc5FWAWlc+gxvFTfSXOPJd0k23/F9MgRq0vn2h+UJolmLzpQFvEv2BUuL6CoEbog8Vn2N+ktypbR2pnNMA=","iv":"H82DrVooOndR7fk1SKKGwQ==","salt":"cxp0pRtsgyUBjll6MktU2HySubrtnMaPXAwaBsANA1Y="}

For Firefox, you will need to retrieve your Metamask vault using the process described here: https://metamask.zendesk.com/hc/en-us/articles/360018766351-How-to-use-the-Vault-Decryptor-with-the-MetaMask-Vault-Data

Once you have the vault data, you can put it in a text file and you can either use it directly with BTCRecover, or you can create an extract.

python3 extract-metamask-privkey.py ../btcrecover/test/test-wallets/metamask.9.8.4_firefox_vault
Metamask first 16 encrypted bytes, iv, and salt in base64:
bXQ6bB5JP1EW0xwBmWZ9vI/iw9IRkorRs9rI6wJCNrd8KUw61ubkQxf9JF9jDv9kZIlxVVkKb7lIwnt7+519MLodzoK0sOw=

Usage for mSIGNA

After downloading the script, make a copy of your wallet file into a different folder (to make it easy, into the same folder as the extract script). As an example for Windows, click on the Start Menu, then click “Run…”, and then type this to open the folder which usually contains your wallet file: %homedrive%%homepath%. From here you can copy and paste your wallet file (it’s a .vault file), into a separate folder. Next you’ll need to open a Command Prompt window and type something like this (depending on where the downloaded script is, and assuming your wallet file is named msigna-wallet.vault and it’s in the same folder):

cd btcrecover-master\extract-scripts
python3 extract-msigna-partmpk.py msigna-wallet.vault

You should get a message which looks like this:

mSIGNA partial encrypted master private key, salt, and crc in base64:
bXM6SWd6U+qTKOzQDfz8auBL1/tzu0kap7NMOqctt7U0nA8XOI6j6BCjxCsc7mU=

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file, only the output from extract-msigna-partmpk.py. To continue the example:

cd btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> bXM6SWd6U+qTKOzQDfz8auBL1/tzu0kap7NMOqctt7U0nA8XOI6j6BCjxCsc7mU=
...
Password found: xxxx

mSIGNA Technical Details

The extract-msigna-partmpk.py script is intentionally short and should be easy to read for any Python programmer. An mSIGNA encrypted master private key is 48 bytes long. It contains 32 bytes of encrypted private key data, followed by 16 bytes of encrypted padding (the chaincode is stored separately).

Because only the last half of the private key is extracted, the wallet cannot be feasibly reconstructed even if this half of the private key could be decrypted (assuming the password search succeeds). The remaining 16 bytes of padding, once decrypted, is predictable, and this allows btcrecover to use it to check passwords. It tries decrypting the bytes with each password, and once this results in valid padding, it has found the correct password.

Without access to the rest of your wallet file, it is impossible the decrypted padding could ever lead to a loss of funds.

Usage for MultiBit Classic

Warning: Using the extract-multibit-privkey.py script on a MultiBit Classic key file, as described below, can lead to false positives. A false positive occurs when btcrecover reports that it has found the password, but is mistaken—the password which it displays may not be correct. If you plan to test a large number of passwords (on the order of 10 billion (10,000,000,000) or more), it’s strongly recommended that you use btcrecover directly with a key file instead of using extract-multibit-privkey.py.

btcrecover doesn’t operate directly on MultiBit wallet files, instead it operates on MultiBit private key backup files. When you first add a password to your MultiBit wallet, and after that each time you add a new receiving address or change your wallet password, MultiBit creates an encrypted private key backup file in a key-backup directory that’s near the wallet file. These private key backup files are much faster to try passwords against (by a factor of over 1,000), which is why btcrecover uses them. For the default wallet that is created when MultiBit is first installed, this directory is located here:

%appdata%\MultiBit\multibit-data\key-backup

The key files have names which look like walletname-20140407200743.key. If you’ve created additional wallets, their key-backup directories will be located elsewhere and it’s up to you to locate them.

For more details on locating your MultiBit private key backup files, see: https://www.multibit.org/en/help/v0.5/help_fileDescriptions.html

Once you’ve located the correct MultiBit private key backup file, make a copy of it into a different folder (to make it easy, into the same folder as the extract script). As an example for Windows, click on the Start Menu, then click “Run…”, and then type this to open the private key backup folder for the first wallet which MultiBit creates (this might not be the one you want, though…): %appdata%\MultiBit\multibit-data\key-backup. From here you can copy and paste a private key backup file into a separate folder. Next you’ll need to open a Command Prompt window and type something like this (depending on where the downloaded script is, and assuming you’ve made a copy of the private key file into the same folder):

cd btcrecover-master\extract-scripts
python3 extract-multibit-privkey.py multibit-20140407200743.key

Of course, you need to replace the private key file name with yours. You should get a message which looks like this as a result:

MultiBit partial first encrypted private key, salt, and crc in base64:
bWI6sTaHldcBFFj9zlgNpO1szOwy8elpl20OWgj+lA==

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file or the private key file, only the output from extract-multibit-privkey.py. To continue the example:

cd btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> bWI6sTaHldcBFFj9zlgNpO1szOwy8elpl20OWgj+lA==
...
Password found: xxxx

MultiBit Classic Technical Details

Warning: MultiBit Classic data-extracts have a false positive rate of approximately 1 in 3×1011. See the warning above for more information.

The extract-multibit-privkey.py script is intentionally short and should be easy to read for any Python programmer. This script extracts 8 bytes of password salt plus the first 16 encrypted base58-encoded characters (out of 52) from the first private key from a MultiBit private key backup file. Because less than 34% of a single private key is extracted, the private key itself cannot be feasibly reconstructed even after these first 16 bytes are decrypted (assuming the password search succeeds). Because these 16 characters, once decrypted, are base58 encoded, btcrecover can use them alone to check passwords. It tries decrypting the bytes with each password, and once the result is a valid 16-character long base58-encoded private key prefix, it has found the correct password.

Without access to the rest of your private key backup file or your wallet file, these 16 characters alone do not put any of your Bitcoin funds at risk, even after a successful password guess and decryption.

Usage for MultiBit HD

After downloading the script, make a copy of your mbhd.wallet.aes file into a different folder (to make it easy, into the same folder as extract-multibit-hd-data.py). As an example for Windows, click on the Start Menu, then click “Run…”, and then type this: %appdata%\MultiBitHD. From here you can open your wallet folder, and copy and paste your mbhd.wallet.aes file into a separate folder. Next you’ll need to open a Command Prompt window and type something like this (depending on where the downloaded script is, and assuming you’ve made a copy of your mbhd.wallet.aes into the same folder):

cd btcrecover-master\extract-scripts
python3 extract-multibit-hd-data.py mbhd.wallet.aes

You should get a message which looks like this as a result:

MultiBit HD first 16 bytes of encrypted wallet and crc in base64:
bTI6LbH/+ROEa0cQ0inH7V3thbdFJV4=

When you (or someone else) runs btcrecover to search for passwords, you will not need your wallet file, only the output from extract-multibit-hd-data.py. To continue the example:

cd btcrecover-master
python3 btcrecover.py --data-extract --tokenlist tokens.txt
Please enter the data from the extract script
> bTI6LbH/+ROEa0cQ0inH7V3thbdFJV4=
...
Password found: xxxx

MultiBit HD Technical Details

The extract-multibit-hd-data script is intentionally short and should be easy to read for any Python programmer. A MultiBit HD wallet file is entirely encrypted. The extract script simply reads the first 32 bytes from the wallet file.

These 32 bytes optionally (starting with MultiBit HD v0.5.0) start with a 16-byte AES initialization vector followed by the header bytes of a bitcoinj wallet file, specifically the byte string “\x0a?org.bitcoin.” once decrypted (where the ? can be any byte). It tries decrypting the bytes with each password, and once the result is what’s expected, it has found the correct password.

Without access to the rest of your wallet file, it is impossible the decrypted header information could ever lead to a loss of funds.


Source codes

Telegram: https://t.me/cryptodeeptech

Video: https://youtu.be/imTXE4rGqHw

Source: https://cryptodeeptech.ru/btc-recover-crypto-guide


BTC Recover Crypto Guide wallet password and seed recovery tools open source

Crypto Deep Tech