Skip to main content
If you mostly know your password but may have made a mistake when typing or writing it down, BTCRecover can generate variations automatically using its typo simulation system.

​
How typos work

Use --typos N to tell BTCRecover how many typos to apply at once to each password candidate. You must also specify which types of typos to try. BTCRecover generates all combinations up to the specified count, including the no-typo case. 
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt \
  --typos 2 --typos-capslock --typos-repeat
With --typos 2 --typos-capslock --typos-repeat, BTCRecover tries:
  • Cairo (no typos)
  • cAIRO (one typo: caps lock)
  • CCairoo (two typos: both repeats)
  • cAIROO (two typos: one of each)
Combining many typo types or increasing --typos beyond 3–4 can produce billions of combinations. Start with --typos 2 and a small set of typo types, then expand only if needed. Use --listpass to preview the candidate count before running against a wallet.

​
Typo order of operations

BTCRecover applies typos in a fixed order:
  1. Build a base password from tokens (or take from a passwordlist)
  2. Apply wildcard expansions and contractions
  3. Apply at most one --typos-capslock typo
  4. Apply zero or more --typos-swap typos
  5. Apply zero or more character-changing typos (--typos-case, --typos-delete, etc.)
  6. Apply zero or more insertion typos (--typos-insert)
The total number of typos applied never exceeds the value of --typos. The --min-typos option sets a lower bound, skipping guesses with fewer typos than specified.

​
Typo types

Simulates typing the entire password with Caps Lock turned on. This is a single typo that affects every letter in the password at once.
--typos 1 --typos-capslock
Input Cairo → also tries cAIRO
Caps Lock is an exception to the one-typo-per-character rule. A character can be affected by both a Caps Lock typo and another typo in the same guess.
Swaps two adjacent characters. Each swap counts as one typo.
--typos 2 --typos-swap
Input Cairo → also tries aCiro, Caior, Cairoo, etc.
Swap typos also ignore the one-typo-per-character rule. A swapped character can still have a second typo applied to it.
Doubles a single character (as if a key was held down too long).
--typos 2 --typos-repeat
Input Cairo → also tries CCairo, Caairoo, etc.
Deletes a single character from the password.
--typos 2 --typos-delete
Input Cairo → also tries airo, Ciro, Caio, Cair, etc.
Changes the case (upper/lower) of a single letter in the password.
--typos 2 --typos-case
Input Cairo → also tries cairo, CAIRO, cAIRO, CaIro, etc.
Like --typos-case, but only changes the case of a letter if it is adjacent to a letter of a different case, or if it’s at the beginning or end of the password. This produces fewer combinations and runs faster while still catching the most likely case errors.
--typos 2 --typos-closecase
Use --typos-closecase instead of --typos-case when the password has a recognizable capitalization pattern.
Replaces each character one at a time with a specified string s. The replacement can be a single character, a longer string, or a wildcard expression.
# Replace each character with a lowercase letter
--typos 1 --typos-replace %a

# Replace each character with any ASCII letter, digit, or symbol
--typos 1 --typos-replace %p
Using wildcards in the replacement string dramatically increases the number of combinations.
Inserts a string (or wildcard substitution) between each pair of characters, as well as at the beginning and end. Unlike replace, the original character is kept.
# Insert a lowercase letter at any position
--typos 2 --typos-insert %a
By default, --typos-insert will not insert multiple copies of the string at the same position. To allow this, use --max-adjacent-inserts N.Input Cairo with --typos-insert Z → also tries ZCairo, CZairo, CaZiro, CaiZro, CairZo, CairoZ
Replaces specific characters with specific alternatives, defined in a map file. Each line in the map file has a character (or characters) to match in the first column, and one or more replacement characters in the second column, separated by whitespace.
typos/us-with-shifts-map.txt
.    ,/;
;    ['/.
BTCRecover tries replacing each . with ,, /, or ;, and each ; with [, ', /, or ..A leet-speak map is also included:
typos/leet-map.txt
aA    @
sS    $5
oO    0
With --typos 3 and the leet map, P@55words and Pa$sword5 would be tried from Passwords, but P@$$w0rd5 (5 replacements) would not.Included map files:
FileDescription
typos/us-map.txtAdjacent keys on a US ANSI keyboard (no shifted characters)
typos/us-with-shifts-map.txtAdjacent keys including shifted characters
typos/leet-map.txtCommon leet-speak substitutions
typos/leet-uncommon-map.txtAdditional less-common leet substitutions
--typos 2 --typos-map typos/us-with-shifts-map.txt

​
Per-type limits (—max-typos-xxxx)

For each --typos-xxxx option there is a corresponding --max-typos-xxxx N option that caps how many of that specific typo type can appear in a single guess, even if the total --typos budget is not yet exhausted. 
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt \
  --typos 3 --typos-delete --typos-insert %a --max-typos-insert 1
This tries up to 3 typos total, but at most 1 can be an insert. This turns what might be billions of combinations into a manageable search. Per-type limits are especially important with --typos-insert and --typos-replace when combined with wildcards.

​
Quick start recommendations

The table below gives example command-line option sets along with rough estimates of the number of passwords checked and time taken per input password.
OptionsWallet typePassword lengthPasswords checkedEst. hours
--typos 2 --typos-capslock --typos-swap --typos-repeat --typos-delete --typos-case --typos-map typos/us-with-shifts-map.txtArmory2015,0000.2
--typos 3 --typos-capslock --typos-swap --typos-repeat --typos-delete --typos-closecase --typos-map typos/us-with-shifts-map.txt --max-typos-map 1Armory20200,0003.0
--typos 3 --typos-capslock --typos-swap --typos-repeat --typos-delete --typos-closecase --typos-map typos/us-with-shifts-map.txt --max-typos-map 2Bitcoin Core15200,0002.0
--typos 2 --typos-capslock --typos-swap --typos-repeat --typos-delete --typos-closecase --typos-map typos/us-with-shifts-map.txt --typos-insert %aBitcoin Core15230,0002.0
--typos 4 --typos-capslock --typos-delete --typos-insert %P --max-typos-insert 2 --no-dupchecksMultiBit/Electrum15125,000,0000.2
--typos 3 --typos-capslock --typos-delete --typos-insert %P --max-typos-insert 2 --typos-replace %P --max-typos-replace 1 --no-dupchecksMultiBit/Electrum151,700,000,0002.3
For GPU-accelerated runs (Bitcoin Core, Litecoin-Qt), higher typo counts and wildcard replacements become feasible. See the GPU Acceleration guide for setup details.

​
Previewing combinations

Before running a full search, use --listpass to print all candidate passwords to the terminal: 
python btcrecover.py --listpass --tokenlist tokens.txt \
  --typos 2 --typos-case --typos-swap | more
The | more pauses after each screenful. This lets you verify that your configuration generates the kinds of variations you expect without spending time on an actual wallet search.

Build docs developers (and LLMs) love

Get started for freeTalk to us