Skip to main content
A token list (tokens.txt) is a text file containing fragments — called tokens — that you remember from your password, even if you don’t remember their exact order or position. BTCRecover combines these tokens in different ways to generate full password guesses.
If your password contains non-ASCII (non-English) characters, add the --utf8 flag to enable Unicode support.

​
Basics

Create a plain text file with one token per line. BTCRecover will try all possible combinations using one or more of the listed tokens:
tokens.txt
Cairo
Beetlejuice
Hotel_california
This generates guesses like Hotel_california, BeetlejuiceCairo, CairoHotel_californiaBeetlejuice, and so on. Lines beginning with # at the very start are treated as comments and ignored:
tokens.txt
# This line is a comment, it's ignored.
# The line below is NOT a comment because the first character is a space:
 #a_single_token_starting_with_the_#_symbol
Run btcrecover with your token list: 
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt

​
Token features

Tokens placed on the same line, separated by spaces, are mutually exclusive — they will never appear together in a single password guess. Use this when you’re unsure about the exact spelling or capitalization of a fragment:
tokens.txt
Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california
BTCRecover will try Cairo and BeetlejuiceCairoHotel_california, but will skip Betelgeusebetelgeuse since those two variants are on the same line.This can dramatically reduce the search space. In this example, all four spelling variants on one line produces 48 combinations instead of 1,956 if each were on its own line.
Prefix a line with + (followed by a space) to mark one of its tokens as required in every password guess:
tokens.txt
+ Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california
Every generated password will include Cairo. You can combine required tokens with mutual exclusion:
tokens.txt
Cairo cairo Katmai katmai
+ Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california hotel_california
Here, exactly one token from the second line is required in every guess. Tokens on the same line are still mutually exclusive. This configuration produces 244 combinations instead of 9,864,100 if all tokens were on separate lines.
Use ^ at the start of a token to force it to appear only at the beginning of a password. Use $ at the end of a token to force it to appear only at the end:
tokens.txt
^Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california$
Cairo, if included, is only tried at the beginning. Hotel_california, if included, is only tried at the end. Neither is required.You can combine anchoring with required tokens:
tokens.txt
Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
+ ^Hotel_california ^hotel_california
This requires either Hotel_california or hotel_california at the beginning of every password.
A positional anchor forces a token to appear at a specific position in the password (counted by number of preceding tokens):
tokens.txt
^2^Second_or_bust
^3^Third_or_bust
Cairo
Beetlejuice
Hotel_california
Second_or_bust is only tried as the second token; Third_or_bust is only tried as the third. Neither is required (no +).
A middle anchor restricts a token to appear within a range of positions, and it is never tried as the first or last token:
tokens.txt
^2,3^Second_or_third_(but_never_last)
^2,4^Second_to_fourth_(but_never_last)
Cairo
Beetlejuice
Hotel_california
You can omit either number in the range:
tokens.txt
^3,^Third_or_after_(but_never_last)
^,3^Third_or_earlier_(but_never_first_or_last)
^,^Anywhere_in_the_middle
Cairo
Beetlejuice
Hotel_california
To allow a middle-anchored token to also appear at the beginning or end, add a second copy on the same line with an appropriate anchor:
tokens.txt
^,^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 control the ordering of tokens relative to each other without fixing their absolute position:
tokens.txt
^r1^Earlier
^r2^Middlish_A
^r2^Middlish_B
^r3^Later
Anywhere
When two or more relative-anchored tokens appear together, they appear in their specified order. Earlier Anywhere Later would be tried, but Later Earlier would not. Tokens with equal relative values (like Middlish_A and Middlish_B) can appear in either order relative to each other.
A single token cannot have both a positional and a relative anchor.
Use --max-tokens to cap the number of tokens combined into a single guess. Use --min-tokens to skip combinations already tried in a previous run:
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --max-tokens 3
With --max-tokens 2, a guess made from three tokens is skipped. This is useful when you have a large token file and need to keep the search manageable.

​
Wildcards

Wildcards expand a single placeholder into many possible characters, letting you express uncertainty within a token without listing every variant explicitly.

​
Common wildcards

WildcardExpands to
%dA single digit (0–9)
%2dExactly 2 digits
%1,3dBetween 1 and 3 digits
%aA single lowercase ASCII letter
%AA single uppercase ASCII letter
%nA single digit or lowercase letter
%NA single digit or uppercase letter
%iaA single lower or uppercase letter (case-insensitive)
%sA single space
%tA single tab
%yAny single ASCII symbol
%pAny single ASCII letter, digit, or symbol
%qAny letter, digit, symbol, or space (common BIP39 passphrase set)
%HA single hexadecimal character (0-9, A-F)
%BA single Base58 character
%[chars]Exactly one of the listed characters
%1,3[chars]Between 1 and 3 of the listed characters
%[0-9a-f]Exactly one hex digit
%%A literal %
%^A literal ^
%SA literal $
Example: If you know Cairo is followed by a single digit:
tokens.txt
Cairo%d
Beetlejuice
Hotel_california
This replaces writing out Cairo0 Cairo1 Cairo2 ... Cairo9 on a single line.

​
Custom character sets

Use --custom-wild characters to define a custom set, then reference it with %c (or %C for uppercase, %ic for case-insensitive): 
python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --custom-wild "abc123"

​
Expanding wildcards with ranges

Add a length range between % and the wildcard letter to expand to multiple characters: 
%1,3d   → between 1 and 3 digits
%0,2a   → between 0 and 2 lowercase letters (including none)
%2i[0-9a-f]  → exactly 2 hex characters (case-insensitive)

​
Backreference wildcards

Backreference wildcards (%b) copy one or more characters that appear earlier in the password. They are useful for passwords with repeating patterns: 
%A%b     → two identical uppercase letters: AA, BB, ..., ZZ
Test%d%b → Test00, Test11, ..., Test99 (never Test12)
You can specify a copy length and how far back to look: 
Test%2;4b  → copies 2 characters starting 4 positions back → "TestTe"
Test%8;4b  → "TestTestTest"
When combined with a map file, backreference wildcards enable keyboard walking patterns — for example, generating sequences where each character is a neighbor of the previous one on the keyboard.

​
Contracting wildcards

Contracting wildcards remove characters from a guess, useful for modeling copy-paste truncation errors:
WildcardBehavior
%0,5-Removes 0–5 adjacent characters from either side
%0,5<Removes 0–5 characters from the left only
%0,5>Removes 0–5 characters from the right only
%0,20-A/Long/Password/with/symbols/that/maybe/was/partially/copy/pasted%0,20-
This tries different versions of the password with up to 20 characters removed from either end.
Wildcards significantly expand the number of passwords to test. Use them in moderation, and combine with --max-tokens or per-type limits to keep runtimes manageable.

​
Special symbols reference

SymbolSpecial when…
%Always special; use %% for a literal %
^At the start of a token; use %^ for a literal ^
$At the end of a token; use %S for a literal $
#At the very start of a line (comment); use a leading space to avoid
+First character on a line followed by a space (required token marker)

​
Embedding command-line options

You can place command-line options directly in the token file. The first line must begin with #--:
tokens.txt
#--autosave progress.sav --pause --typos 1 --typos-case
Cairo
Beetlejuice Betelgeuse
Hotel_california

Build docs developers (and LLMs) love

Get started for freeTalk to us