Scoutinternal

Wallet Password Recovery and Reset for BitGo Wallets

Wallet Password Recovery and Reset for BitGo Wallets

Problem

Customers frequently encounter "Incorrect Wallet Password" errors when attempting withdrawals or transfers from BitGo wallets. The core confusion stems from the fact that the BitGo wallet password is separate from the BitGo login (account) password. Customers may have forgotten their wallet password, lost their KeyCard (which is required for self-service password reset), or had their login password reset which desynchronizes their wallet access. This issue affects V1 (legacy) BTC wallets, V2 wallets, and FTX creditor Trade/Go Account wallets across multiple coin types.

Diagnostics

  • Confirm which password is the problem: Ask the customer whether they cannot log in to BitGo at all (login password issue) or whether they can log in but get "Incorrect Wallet Password" when trying to send/withdraw (wallet password issue). These are two separate passwords.
  • Check wallet version: Use the admin tool (bga) to determine if the wallet is V1 (type: safehd) or V2. V1 wallets have different UI navigation and are deprecated; the password reset flow differs.
  • Check if the user recently reset their login password: In admin logs, look for a userPasswordChange event. If the user reset their login password and is not the wallet creator, they must be removed and re-added to the wallet before they can spend again.
  • Determine if the user is the wallet creator or an invited member: Use bga wallet keys or check wallet user list. Non-creators use their login password to spend; creators use the wallet password set at creation. If a non-creator reset their login password, the keychain is desynchronized.
  • Check if the user has their KeyCard: The KeyCard (specifically Box D — the Encrypted Wallet Password) is required for self-service wallet password reset. If lost, recovery options are limited to KRS or third-party brute-force services.
  • Check KRS eligibility: Use the admin tool to determine if the wallet's backup key was stored with a Key Recovery Service partner (e.g., Keyternal, Coincover) or self-managed. Look for KRS indicators on the wallet.
  • Check for "key not found" errors: ErrorIDs like cm723nwtq1pl30ex04rdi9jzt or clrch3hzq3uja0e0zelbk1l80 during wallet password reset may indicate the wallet was created via API (which does not support UI-based password reset) or that the user is not the wallet creator.
  • Check OTP device type: Verify the 2FA device registered (Google Authenticator, Authy, SMS). Ensure the customer is entering a valid 6-digit code, not a 7-digit code or an incorrect OTP device.
  • For FTX creditor wallets: Confirm the customer is logged into the correct FTX-associated Enterprise and is using the "classic view" UI.

Resolution

Scenario: password-wallet-keycard-recovery#has-keycard-forgot-wallet-password

Trigger: Customer can log in to BitGo and has their KeyCard (Box D) but has forgotten their wallet password.

Signals: Incorrect Wallet Password, forgot wallet password, keycard, Box D, v1 wallet, reset wallet password

Steps:

  1. Instruct the customer to log in to their BitGo account.
  2. Navigate to the affected wallet.
  3. Go to the Settings tab of that wallet.
  4. Click the "Forgot Wallet Password" hyperlink (may appear as "Forgot wallet password?" or "Recover your wallet" link).
  5. Enter the current 2FA code when prompted.
  6. Enter the complete information from Box D of the KeyCard into the prompt window.
  7. If the correct Box D info is provided, the system will allow setting a new wallet password. Past passwords will not be revealed.
  8. Use the new wallet password for future withdrawals/transfers.

Notes: - For V1 wallets, the "Forgot Wallet Password" option may only be visible in the classic (old) UI. The customer must switch to classic view first.

  • The wallet password and login password are independent. Changing one does not change the other.
  • This flow is only available to the wallet creator. Non-creators cannot reset the wallet password.
  • Wallets created via API do not have the ability to reset the wallet password through the UI.

"Login to our platform → Goto Wallets & Connections → Choose the wallet you need to restore → Choose Wallet Settings → Choose Recover Wallet Password → Enter your 2FA → Enter the complete information from Box D of your keycard into the prompt window. This will allow you to set a new wallet password. Past used passwords will not be revealed." "To reset your wallet password, log into your account and go to the wallet you're trying to recover password from. Then go to 'Settings', browse down to the Password section, and then click on the 'Forgot Wallet Password' link. Now you'll start the wallet password reset process, and you'll need to supply all of the text info in the Box D of your Keycard."

Scenario: password-wallet-keycard-recovery#ftx-classic-view-required

Trigger: FTX creditor or Trade/Go Account user gets "Incorrect Wallet Password" when attempting withdrawal, and the wallet password settings are not visible in the current UI.

Signals: FTX, wallet password, withdrawal error, classic view, Trade, Go Account, switch to classic view

Steps:

  1. Click on the profile icon in the top right corner of the BitGo UI.
  2. Click on "Switch to classic view".
  3. Once in the classic view, navigate to: Trade > Wallet Details > Settings.
  4. To update the wallet password (if current password is known): Click Update Wallet Password.
  5. If the wallet password is forgotten: Click "Forgot Wallet Password" and follow the reset flow using the KeyCard.
  6. Confirm the customer is logged into the correct FTX-associated Enterprise.

Notes: - The BitGo wallet password is separate from the login password. FTX creditors who did not explicitly set a wallet password during account setup may not recall it.

  • Recovery codes (the 10 alphanumeric codes provided during account setup) are for 2FA recovery, not for wallet password reset.
  • If the customer never consciously created a wallet password and has no KeyCard, escalate to determine if the wallet was auto-provisioned with a default configuration.

"Please be informed that access to the specified options requires the switch to the old UI. We've attached screenshots to guide you through the process. Step 1 :- Click on the profile icon in the top right corner Step 2:- Click on Switch to classic view... If you happened to forgot the wallet password you may goto Trade > Wallet Details > Settings > Forgot Wallet Password" "Please note that your BitGo wallet password is separate from your BitGo login password. This wallet password is required, along with 2FA, to authorize transactions such as withdrawals."

Scenario: password-wallet-keycard-recovery#login-password-reset-desync

Trigger: Customer reset their BitGo login password and now gets "Incorrect Wallet Password" when spending, even though they are entering the correct password.

Signals: Incorrect Wallet Password, password change, userPasswordChange, removed and re-added, login password reset, keychain mismatch

Steps:

  1. Confirm via admin logs that a userPasswordChange event occurred recently for this user.
  2. Determine whether the affected user is the wallet creator or an invited member.
  3. If the user is an invited member (not the creator): A wallet admin must remove the user from the wallet and then re-invite them. Once the user accepts the re-invite, their new login password keychain will be synchronized and they can spend again.
  4. If the user is the wallet creator: The wallet password itself is unaffected by a login password reset. The creator should use the original wallet password (not the new login password) to spend. If they have forgotten the wallet password, they must use the KeyCard (Box D) to reset it via wallet Settings.

Notes: - When a user is invited to a wallet, an internal keychain is created using the user's login password. If the login password changes, the keychain becomes mismatched. Removing and re-adding the user creates a new matching keychain.

  • This is communicated onscreen when the Forgotten Password prompt is used for login password reset.
  • For enterprise wallets with multiple admins, another admin must perform the remove/re-add action.

"If you reset your login password, you will need to be removed and re-added to all wallets you need to spend from. To resolve this issue, have a wallet admin uninvite you from the wallet and then send a re-invite. Once you accept the invite, you should once again be able to spend from the wallet using your login password." "If a user resets their login password, that user must be removed and re-added to wallets before they can spend from these again. When a user is invited to a wallet, a keychain is created using the user's login password and private key of the wallet... By removing the user and re-adding them to the wallets, keychain A1 is removed and keychain B1 is created."

Scenario: password-wallet-keycard-recovery#lost-password-and-keycard-krs

Trigger: Customer has lost both the wallet password and the KeyCard, and cannot perform self-service password reset.

Signals: lost keycard, lost password, no keycard, Key Recovery Service, KRS, Keyternal, wallet recovery, $99 fee

Steps:

  1. Inform the customer that BitGo does not store wallet passwords and cannot reset them without the KeyCard.
  2. Check whether the wallet's backup key was stored with a Key Recovery Service (KRS) partner (e.g., Keyternal, Coincover) during wallet creation. Use the admin tool to verify.
  3. If KRS was used: BitGo and the KRS can work together to recover the wallet. The KRS charges a fee of $99. Collect the following information from the customer:
    • User ID (email address used to log into BitGo)
    • Wallet Address of the wallet to recover
    • Wallet Name
    • Destination address (must be a BitGo wallet)
    • Date the account was created
    • Estimated balance of the account in coin
  4. Submit the recovery request to the KRS partner via the internal KRS processing sheet.
  5. If KRS was NOT used: Inform the customer that there is no way for BitGo alone to recover access. The alternative is a third-party password cracking/wallet recovery service which can attempt to brute-force the password. This option is feasible if:
    • The wallet holds more than $250 worth of crypto.
    • The customer has some idea of what the password may be.
    • The customer is willing to pay a fee (typically ~20% of the wallet's total funds).
  6. If neither option is viable, there is no recovery path available.

Notes: - BitGo cannot regenerate lost KeyCards.

  • BitGo cannot reset wallet passwords on behalf of customers for self-custody wallets.
  • For V1 wallets specifically, the Wallet Recovery Service (WRS) is recommended as the recovery path. For V2 wallets, KRS is the recommended path.
  • The KRS fee ($99) may exceed the wallet balance for small-value wallets; advise the customer accordingly.

"If you have lost or forgotten the passcode to your wallet and you've lost your Keycard then there is no way for you or for BitGo alone to recover access to your wallet. If you chose to store your wallet's backup key with one of our Key Recovery Service partners, then it's possible for BitGo and the KRS to work together to recover your wallet. The KRS will charge a fee of $99 for this service." "For V1 Wallets (Legacy Bitcoin BitGo Wallets): We recommend using Wallet Recovery Service (WRS) to recover your wallet. For V2 Wallets: We suggest leveraging the Key Recovery Service (KRS). If your wallet's backup key is stored with one of our KRS partners, BitGo and the KRS provider can collaborate to recover your wallet."

Scenario: password-wallet-keycard-recovery#non-bitgo-recovery-wrw

Trigger: Customer cannot access their BitGo account at all (lost email access, lost 2FA) but has the KeyCard and wants to recover funds without BitGo services.

Signals: wallet recovery wizard, WRW, non-bitgo recovery, lost account access, keycard recovery, cross-chain recovery, Blockchair API key

Steps:

  1. Direct the customer to download the BitGo Wallet Recovery Wizard (WRW) from: https://github.com/BitGo/wallet-recovery-wizard
  2. The WRW supports:
    • Recovering coins without BitGo services via the Recovery KeyCard
    • Recovering funds sent to addresses on the wrong chain (cross-chain recovery)
  3. When using the WRW, select "Non-BitGo Recoveries" to enter the tool without logging into BitGo.
  4. The customer will need to provide their KeyCard information (User Key, Backup Key, BitGo Public Key) and a destination address.
  5. If the WRW prompts for an API key, this is an API key token from blockchair.com required for broadcasting the recovery transaction. The customer should create an account at https://blockchair.com/api/plans and obtain a pay-as-you-go API key.
  6. Once the WRW generates a recovery JSON file, the customer should:
  7. If the WRW output needs further processing by BitGo engineering (e.g., for cross-chain recoveries), the customer should share the generated file with support for escalation.

Notes: - The customer must NOT rename or modify the recovery file generated by the WRW before sharing it with support.

  • If the backup key was stored with a third-party KRS like Coincover, the wallet must have been created using Coincover's key storage option — not "your own key" — for Coincover-based recovery to work.
  • For ARM64 macOS users, there may be a known issue requiring a workaround (referenced in Apple support discussions).

"To verify, please open the file, and confirm that you see the half-signed transaction hex ('halfSignedTx'), and the complete transaction hex ('completeTx'). For further verification, you will want to check the destination addresses and amounts. You can decode your transactions using a public blockchain explorer." "It seems you will need to create an account at Blockchair and once completed, create a 3rd-party API key which will be used in that field... you will need to use Blockchair.com to broadcast the transaction JSON."

Scenario: password-wallet-keycard-recovery#2fa-reset-for-account-access

Trigger: Customer cannot log in due to lost 2FA device and needs 2FA reset before they can access wallet settings to reset the wallet password.

Signals: 2FA reset, frozen account, too many failed attempts, lost phone, Authy discontinued, first 8 / last 8 characters

Steps:

  1. Before initiating a manual 2FA reset, verify wallet ownership by requesting the following:
    • Date of BitGo email verification (search for "Your BitGo Email Verification" in inbox)
    • 3 transaction hashes either to or from the wallet (if unavailable, customer should contact the exchange they used)
    • Wallet balance in cryptocurrency (with wallet name)
  2. If the customer does not have the above information, accept the first 8 characters and the last 8 characters of the BitGo Public Key from the KeyCard. The customer must also provide the wallet name the KeyCard applies to.
  3. Verify the provided information matches internal records.
  4. Once verified, perform the 2FA reset.
  5. Instruct the customer to log back in and set up 2FA again.
  6. After regaining account access, the customer can proceed with the wallet password reset using their KeyCard (Box D) if needed.

Notes: - Authy has been discontinued as a supported 2FA method on BitGo. Customers previously using Authy will need a manual 2FA reset.

"If you do not have the above information, we can also accept the First 8 characters and the Last 8 Characters of the Bitgo Public Key from your keycard. Please provide the name of the wallet the keycard info applies to." "Our platform discontinued the support of Authy which was your 2FA method."

Scenario: password-wallet-keycard-recovery#api-created-wallet-no-ui-reset

Trigger: Wallet was created via API, and the UI-based wallet password reset is not available.

Signals: created by API, not web UI, cannot reset wallet password, API wallet, walletPassphrase

Steps:

  1. Confirm via admin tools that the wallet was created via API (not the web UI).
  2. Inform the customer that wallets created via API do not have the ability to reset the wallet password through the BitGo web UI.
  3. The wallet passphrase (walletPassphrase) used during API-based wallet creation is the only password that will work. This must be retrieved from the customer's own records or systems.
  4. If the password is truly lost and the wallet was created via API, the same KRS or third-party recovery options apply as in the "lost password and keycard" scenario.

Notes: - The KeyCard name and wallet name must match for UI-based password reset. Mismatches (e.g., "UniCOIN - ETHEREUM - wallet 1" vs "UniCOIN ETH - wallet 1") will cause the reset to fail.

  • API-created wallets are common for enterprise/integration use cases.

"It looks like this wallet was created by API and not web UI. Wallets created via API does not have ability to reset the wallet password."

Scenario: password-wallet-keycard-recovery#v1-wallet-migration-to-v2

Trigger: Customer needs to migrate funds from a deprecated V1 wallet to a V2 wallet but cannot spend from V1 due to a forgotten wallet password.

Signals: V1, V2, migrate, upgrade, legacy, deprecated, v1btc

Steps:

  1. Inform the customer that it is not possible to upgrade a V1 wallet to V2 directly. They must create a new BTC wallet (which will be V2 by default) and transfer funds from the V1 wallet.
  2. Transferring funds from the V1 wallet requires the wallet password.
  3. If the customer has their KeyCard, guide them to reset the wallet password via the V1 wallet's Settings tab → "Forgot Wallet Password" using Box D from the KeyCard. This may require switching to "classic view" in the UI.
  4. If the customer does not have the KeyCard or wallet password, follow the "lost password and keycard" recovery scenario (KRS or third-party recovery).
  5. Once the wallet password is recovered/reset, the customer can send funds from the V1 wallet to their new V2 wallet address.
  6. After migration, the customer can use the V2 wallet going forward.

Notes: - V1 wallets are deprecated and no longer receive new features. BitGo strongly recommends migrating to V2.

"It is not possible to upgrade to a v2 wallet directly. Instead, you can simply create a new BTC wallet, which will be the latest version by default, and move your coins over." "For your wallet, you can navigate to that wallet and then to the Settings tab of that wallet. From there, you should see a hyperlink for 'Forgot Wallet Password'. Follow the instructions, providing the requested keycard info into the prompt. If the correct info is provided, you will be able to set a new Wallet Password."

Scenario: password-wallet-keycard-recovery#key-not-found-error

Trigger: Customer receives a "NotFound: key not found" error when attempting to use the "Forgot Wallet Password" flow in the UI.

Signals: key not found, NotFound, ErrorID, forgot wallet password error, password reset error

Steps:

  1. Ask the customer to retry using a desktop/laptop with the latest version of Google Chrome.
  2. Verify the customer is the wallet creator — only the creator can use the "Forgot Wallet Password" flow. Non-creators will not have the required keychain.
  3. Check if the wallet was created via API. API-created wallets do not support the UI-based password reset.
  4. Verify the customer is providing the correct KeyCard for the specific wallet (check first 8 and last 8 characters of the BitGo Public Key against the wallet's key records using bga wallet keys).
  5. If the error persists and the wallet is eligible, escalate to engineering with the ErrorID provided.

Notes: - Common ErrorID patterns include strings like cm723nwtq1pl30ex04rdi9jzt or clrch3hzq3uja0e0zelbk1l80.

  • If the backup key was stored with a third-party KRS (e.g., Coincover) whose portal is no longer accessible, the customer may need to coordinate directly with that KRS provider.

Related

  • managing-wallet-users — Covers the remove/re-add process required after login password resets for non-creator wallet members.
  • keycards-and-private-keys — Details on KeyCard generation, storage best practices, and the distinction between hot and warm wallets.
  • passcodes — Explains the relationship between login passwords and wallet passwords, and the consequences of losing both the passcode and KeyCard.