Introduction
BNB Chain is one of the world’s largest layer-1 blockchain ecosystems, with millions of users holding BNB and BSC-based tokens in software wallets like MetaMask, Trust Wallet, and MathWallet. Forgetting your local wallet password is a frustrating but common issue — and while third-party password recovery tools exist, many carry risks of malware, keystore theft, or asset loss.
Critical Pre-Note: BNB wallet passwords only unlock local wallet files (e.g., Keystore JSON files). If you have your 12/24-word mnemonic recovery phrase, you can simply import it into a new wallet and set a new password without any script required. This guide is designed exclusively for users who have lost their mnemonic but retain access to their wallet’s Keystore file, and remember partial details of their password to narrow down recovery candidates.
Writing a custom BNB wallet password recovery script gives you full control over the process, eliminates third-party risks, and can be tailored to your specific password memory clues. This guide covers core prerequisites, step-by-step script development, non-negotiable security rules, and troubleshooting tips.
Core Prerequisites for BNB Wallet Password Recovery Scripts
Before writing any code, confirm you meet all of the following requirements to ensure a legal, effective recovery process:
- Compliance & Ownership: You may only use this script to recover wallets that you legally own. Unauthorized access to others’ crypto wallets is a serious criminal offense in nearly every jurisdiction, punishable by fines and jail time.
- Keystore File Access: You have a complete, uncorrupted Keystore JSON file exported from your BNB Chain wallet. Because BSC is EVM-compatible, its Keystore files follow the same Web3 Secret Storage standard as Ethereum wallets, so standard web3 libraries will work.
- Partial Password Details: You remember at least some details of your password (e.g., length range, prefix/suffix, character types like numbers or special symbols). Pure brute-force recovery of a strong 8+ character password is computationally infeasible, so narrowing candidates with known clues is mandatory.
- Technical Basics: You have foundational Python development skills and familiarity with web3 library basics.
- Offline Work Environment: You have a clean, air-gapped (permanently offline) device to run the script, to prevent keystore or private key theft via malware or network breaches.
Step-by-Step Guide to Writing the BNB Wallet Password Recovery Script
The core logic of a BNB wallet password recovery script is straightforward: generate a list of candidate passwords based on your known clues, then test each candidate by attempting to decrypt the Keystore file. If decryption succeeds, the candidate is your correct password.
2.1 Set Up a Secure Offline Development Environment
First, prepare your offline device:
- Disconnect all network cables and Wi-Fi, and disable Bluetooth to ensure the device is fully air-gapped.
- Install Python 3.8+ and the
web3.pylibrary (download the package and dependencies on a separate online device, transfer them via a clean USB drive, and install offline). - Copy your Keystore file to the device’s encrypted local storage (never store it on a cloud drive or unencrypted USB).
2.2 Build the Password Candidate Generator
The most efficient recovery method is mask-based dictionary attack, which only generates passwords that match your known clues, drastically reducing the total number of candidates.
For example, if you remember your password starts with Bnb2023, ends with !, and has 2 lowercase letters in the middle, you can generate candidates with Python’s itertools module.
2.3 Implement Password Verification Logic
Use web3.py’s built-in Account.decrypt() method to test each candidate. This method attempts to decrypt the Keystore file with the provided password: if it returns a private key, the password is correct; if it throws an error, the password is wrong.
2.4 Full Working Script Example
from web3 import Web3
import json
import itertools
import string
import multiprocessing
# --------------------------
# CONFIGURE THESE SETTINGS ONLY
# --------------------------
KEYSTORE_PATH = "your_bnb_wallet_keystore.json" # Path to your offline keystore file
PASSWORD_PREFIX = "Bnb2023" # Remembered prefix
PASSWORD_SUFFIX = "!" # Remembered suffix
MIDDLE_CHARACTERS = string.ascii_lowercase + string.digits # Character set for unknown part
MIDDLE_LENGTH = 2 # Number of unknown characters in the middle
# --------------------------
def test_password(candidate, keystore):
"""Test a single password candidate. Returns the candidate if correct, else None."""
try:
# Attempt to decrypt keystore
private_key = Web3().account.decrypt(keystore, candidate)
# Immediately clear private key from memory to reduce leak risk
del private_key
return candidate
except Exception:
return None
if __name__ == "__main__":
# Load keystore file
with open(KEYSTORE_PATH, "r") as f:
keystore = json.load(f)
# Generate all candidate passwords
candidates = [
PASSWORD_PREFIX + "".join(comb) + PASSWORD_SUFFIX
for comb in itertools.product(MIDDLE_CHARACTERS, repeat=MIDDLE_LENGTH)
]
print(f"Total candidates to test: {len(candidates)}")
print("Starting recovery process (offline only)...")
# Use multiprocessing to speed up testing (utilizes all CPU cores)
with multiprocessing.Pool(processes=multiprocessing.cpu_count()) as pool:
results = [pool.apply_async(test_password, args=(cand, keystore)) for cand in candidates]
for res in results:
found = res.get()
if found:
print(f"\n✅ PASSWORD FOUND: {found}")
pool.terminate()
break
else:
print("\n❌ Password not found. Adjust your mask settings and try again.")
# Clear sensitive data from memory
del keystore
del candidates
2.5 Performance Optimization Tips
- Use multiprocessing: The example above uses all available CPU cores to test candidates in parallel, which can speed up recovery by 4-8x depending on your device.
- Narrow your mask: The more password details you remember, the fewer candidates you need to test. Even one extra known character can reduce candidate count by 90%+ for strong passwords.
- GPU acceleration: For very large candidate sets, you can extend the script to use GPU-based decryption with libraries like
pyopencl, though this requires more advanced development skills.
Non-Negotiable Security & Compliance Best Practices
Crypto wallet recovery carries inherent security risks — follow these rules strictly to avoid asset loss or legal consequences:
- Never operate online: Always run the script on an air-gapped device. Even a moment of internet connectivity can expose your keystore or private key to malware.
- Never share sensitive data: Never send your Keystore file, script output, or private key to anyone claiming to be a "crypto recovery expert" — 99% of these services are scams designed to steal your assets.
- Test with a dummy wallet first: Before running the script on your actual wallet, test it with a disposable BNB testnet wallet whose password you know, to confirm the script works correctly and your mask logic is accurate.
- Wipe data after recovery: Once you recover your password (or decide to stop trying), securely delete the Keystore file, script, and all temporary files from the offline device. Use a disk-wiping tool to fully erase traces of sensitive data.
- Prioritize mnemonic recovery: If you later find your mnemonic phrase, abandon the script recovery process immediately — importing the mnemonic into a new wallet is far safer and faster.
Troubleshooting Common Recovery Failures
If your script runs but does not find your password, try these fixes:
- Adjust your mask parameters: Double-check your remembered password details — you may have misremembered the length, prefix, or character set. Even small adjustments (e.g., adding uppercase letters to the character set) can yield results.
- Verify your Keystore file: Confirm the Keystore file is the correct one for the wallet you’re trying to recover, and that it was exported completely without corruption. Try importing it into a wallet app to confirm it is recognized as a valid Keystore.
- Check for typos in the script: A single typo in your password prefix/suffix configuration will cause all candidates to fail. Double-check your settings against any password hints you may have written down.
Conclusion
Writing a custom BNB wallet password recovery script is a secure, cost-effective way to regain access to your BNB Chain wallet if you’ve lost your mnemonic and forgotten your password, as long as you have partial password clues to work with. The process relies on the EVM compatibility of BSC, uses standard web3 libraries, and can be optimized for speed with parallel processing.
That said, the best way to avoid needing password recovery is to securely back up your mnemonic phrase in multiple offline locations — this is the ultimate proof of ownership for your crypto assets. Always prioritize mnemonic backups, and only use recovery scripts as a last resort for wallets you cannot access any other way.