Scoutinternal

Migrating V1 BTC Wallets to V2 BTC Wallets

Migrating V1 BTC Wallets to V2 BTC Wallets

Problem

Customers with legacy V1 BTC wallets contact support asking how to upgrade or migrate to V2. BitGo has deprecated V1 BTC wallets and no longer performs in-place upgrades. The standard migration path requires the customer to create a new BTC wallet (which is V2 by default), then withdraw funds from the V1 wallet to the new V2 wallet. Customers frequently encounter issues during this process including "Insufficient funds" errors, incorrect wallet password errors, inability to see the withdraw button in the V1 wallet UI, confusion about Resource Center access, and V1 wallets not supporting Bech32 destination addresses.

Diagnostics

  • Confirm the wallet is V1: Use the admin tool (bga wallet <wallet_id>) and check the Type field. V1 wallets show Type: safehd. V2 wallets will show the coin type (e.g., Coin: BTC).
  • Check wallet balance and spendable amount: In the admin tool output, compare Balance, Confirmed, and Spendable fields. Also check Spendable (Single Transaction) if available — the mining fee shown there may explain an "Insufficient funds" error.
  • Check wallet unspents: Run bga wallet unspents to see if unspents are missing or if the total unspent amount differs from the reported balance. A missing unspent can cause spend failures.
  • Check enterprise status: Verify the enterprise is not frozen. A frozen enterprise will prevent any withdrawals with the error "enterprise is frozen cannot spend."
  • Check wallet policy: Look for spending limit policies (e.g., transactionLimit:getApproval) that may cap withdrawal amounts per transaction or per hour/day.
  • Check for pending approvals: If the customer has a policy rule requiring admin approval, check the Activity tab for pending approval requests.
  • Check the destination address format: V1 wallets do not support sending to Bech32 (bc1…) addresses. The destination must be a Legacy (1…) or P2SH (3…) BTC address.
  • Check recent UI/engineering JIRA issues: A known issue (BG-72042) caused the withdraw button to disappear from V1 wallets after the UI migration to the React-based interface. If the customer cannot see the withdraw button at all, check whether this has been resolved for their account.

Resolution

Scenario: v2-v1-migrate-wallet#standard-migration

Trigger: Customer asks how to migrate or upgrade from a V1 BTC wallet to V2, and has no specific error blocking them.

Signals: migrate, upgrade, v1, v2, legacy wallet, how to, create new wallet, deprecated

Steps:

  1. Inform the customer that BitGo no longer performs in-place V1-to-V2 upgrades. All new wallets created on the platform are V2 by default.
  2. Instruct the customer to log in at https://app.bitgo.com/auth/log-in.
  3. Click the "Create Wallet" button. Name the wallet, select BTC as the asset type, and proceed through the prompts. Remind them to set a wallet password they will remember and to securely store the generated Keycard.
  4. Navigate to the legacy V1 wallet. Use the Withdraw button within the V1 wallet's view.
  5. For the destination, select "V2 Wallet" and choose the newly created wallet — or select "Any Address" and paste an address from the new V2 wallet.
  6. Enter the withdrawal amount (slightly less than the full balance to account for network fees and any platform fee).
  7. Enter the wallet password that belongs to the V1 wallet (not the V2 wallet password or login password) and the 2FA code.
  8. Once the on-chain transaction confirms, the migration is complete. The customer can then send funds externally from the V2 wallet.

Notes: Standard on-chain fees apply to this transfer. Pay As You Go accounts also incur a 0.25% platform fee per transaction. BitGo will not waive these fees — the window for BitGo-assisted free migrations has expired. Resource Center access is only available to institutional/enterprise account clients; retail users should follow these email-based instructions instead.

"Once you are logged in, choose the big blue button which reads, 'Create Wallet'... Once completed, choose Withdraw within the Legacy v1 wallets screen. For TO, choose V2 Wallet and choose the new wallet you just created. For Amount, choose BTC and set the amount you wish to send. Choose Preview Withdrawal. Input the Wallet Password that pertains to this v1 wallet when prompted as well as your 2FA." (ticket #211131)

"Please be informed that our BitGo Resource Center is only available for clients with a paid Enterprise account." (ticket #235808)

"Users had the chance to have us migrate these wallets for them years ago, but that window expired. These fees must be paid to move coins between addresses external and/or internal to our platform." (ticket #199138)

Scenario: v2-v1-migrate-wallet#insufficient-funds-error

Trigger: Customer receives "Insufficient funds" error when attempting to withdraw from V1 wallet to V2 wallet.

Signals: insufficient funds, error, cannot withdraw, amount too small, not enough funds, fee

Steps:

  1. Ask the customer to reduce the withdrawal amount to leave room for the network (miner) fee and any platform fee. Suggest reducing by approximately 0.0003 BTC or more depending on current on-chain fee conditions.
  2. If the wallet has a very small balance, check current BTC miner fees at https://mempool.space/graphs/mempool#1m — during high-fee periods, small balances may be uneconomical to move. Advise the customer to wait for fees to drop.
  3. Use the admin tool to check wallet unspents (bga wallet unspents). If the total unspent amount differs significantly from the reported balance, there may be a missing unspent. Escalate to engineering if a discrepancy is found.
  4. If the error persists at any amount (including small test amounts), escalate to the engineering team with the wallet ID, the attempted amount, and any error/request IDs.

Notes: The BTC minimum send amount is 2730–2750 satoshi. Amounts below this will be rejected regardless of balance. During fee spikes, even wallets with moderate balances may show this error when trying to send the full amount. It is safe for the customer to leave funds in the V1 wallet until fees decrease.

"This is due to recent spike in BTC miner fees — https://mempool.space/graphs/mempool#6m It is fine to leave your funds in your v1 wallet for now but any new feature we have will not apply for v1 wallet. You can move your funds when miner fees drop." (ticket #218504)

"The minimum amount allow to send for BTC is 2750 satoshi." (ticket #215459)

Scenario: v2-v1-migrate-wallet#incorrect-wallet-password

Trigger: Customer receives an authentication or incorrect password error when attempting to withdraw from the V1 wallet.

Signals: incorrect password, authentication error, wrong password, wallet password, incorrect otp, keycard, Box D

Steps:

  1. Clarify that the wallet password for the V1 wallet may differ from the BitGo login password and from any V2 wallet password. The V1 wallet password was set when the wallet was originally created (potentially years ago) and does not change when the login password is changed.
  2. Ask the customer to try entering the V1 wallet's original password carefully (manually, not via password manager if possible).
  3. If the password is forgotten, direct them to reset it using their wallet Keycard: navigate to the V1 wallet → Settings tab → click "Forgot Wallet Password" (or "Recover Wallet Password"). They will need their 2FA code and the full information from Box D of the Keycard.
  4. The customer must be logged in with the email address of the user who originally created the wallet for the password reset to work.
  5. If the Keycard is lost, BitGo cannot regenerate it. The customer may need to use the Wallet Recovery Service (WRS) at https://www.walletrecoveryservices.com/contact/ — a third-party service that typically charges a 20% recovery fee and requires the customer to have some idea of the password.

Notes: BitGo support cannot reset wallet passwords on behalf of customers and cannot regenerate lost Keycards. Only the Keycard generated for that specific wallet can be used to reset that wallet's password.

"What I didn't realise was that the password I had given to the V1 wallet in 2017, was very different to the V2 and Bitgo passwords that I am using now, but I had never changed the V1 wallet password. I didn't understand that when transferring from one wallet to another you have to have the right password for the 'transferor' wallet." (ticket #203512)

"To start the wallet password recovery process, log into your account and go to the wallet you're trying to recover 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 recovery process, and you'll need to supply all of the text info in the Box D of your Keycard." (ticket #255367)

Scenario: v2-v1-migrate-wallet#withdraw-button-missing

Trigger: Customer cannot see the Withdraw button on the V1 wallet page, or the V1 wallet balances are unclickable, or the V1 wallet form does not load.

Signals: no withdraw button, unclickable, balances not clickable, form doesn't load, react, UI broken, v1 wallets interface

Steps:

  1. This was a known issue (JIRA BG-72042) caused by the migration to the React-based UI. Engineering has deployed fixes for affected wallets.
  2. Ask the customer to clear their browser cache and try again, or try a different browser (Chrome recommended) and/or a different device.
  3. Confirm the customer is viewing the correct enterprise. V1 wallets may be under a different enterprise than the one currently selected. Instruct them to switch enterprises using the dropdown at the top of the page.
  4. If the withdraw button is still missing after cache clearing and enterprise switching, escalate to the engineering team referencing BG-72042 with the customer's wallet ID.
  5. Once engineering resolves it, instruct the customer: "For v1 wallets, please go into the wallet and use the Withdraw button shown there."

Notes: The old UI cannot be restored for individual accounts. Adding V1 wallets to an enterprise may make them visible in the new UI. If the customer's V1 wallets are personal (not under an enterprise), support may need to add them to an enterprise to restore visibility.

"We have fixed this issue and you should be able to see the withdraw button in the wallet now." (ticket #207591)

"This should be fixed now. For v1 wallets, please go into the wallet and use the Withdraw button shown there." (ticket #215459)

"known issue of not able to withdraw from v1btc after migrate to react. JIRA - https://bitgoinc.atlassian.net/browse/BG-72042" (ticket #209491)

Scenario: v2-v1-migrate-wallet#bech32-address-unsupported

Trigger: Customer receives an "invalid bitcoin address" error when trying to send from a V1 wallet to a bc1… (Bech32) address.

Signals: invalid bitcoin address, bech32, bc1, unsupported address, v1 wallet address format

Steps:

  1. Explain that V1 wallets do not support sending to Bech32 (bc1…) addresses.
  2. The customer must use a Legacy (starting with 1) or P2SH/SegWit-compatible (starting with 3) BTC address as the destination.
  3. If sending to an external exchange, advise the customer to check whether the exchange can provide a Legacy or P2SH deposit address.
  4. Alternatively, the customer should first transfer funds to their V2 BTC wallet (which supports Bech32), and then send from the V2 wallet to the bc1… address.

Notes: This limitation is specific to V1 wallets. V2 BTC wallets support all standard address formats.

"You need to send these funds to a Legacy BTC address. Our v1 wallets do not support sending to Bech32 address." (ticket #229150)

Scenario: v2-v1-migrate-wallet#spending-limit-policy

Trigger: Customer hits a spending limit when trying to withdraw from V1 wallet, receiving an error about exceeding a limit.

Signals: spending limit, exceeded limit, transaction limit, daily limit, policy, getApproval

Steps:

  1. Ask the customer to check their V1 wallet's policy settings for any spending limits (transaction limit, hourly limit, daily limit).
  2. If a spending limit is set, the customer can send multiple smaller withdrawals that each stay under the limit to gradually empty the wallet.
  3. Note that it may not be possible to change or remove a spending limit once set on a V1 wallet. The customer should plan withdrawals accordingly.
  4. If the customer has set a policy requiring admin approval, direct them to the Activity tab to approve pending withdrawal requests.

Notes: V1 wallet policies may have been set years ago and forgotten. Check the policy version and date in the admin tool output.

Scenario: v2-v1-migrate-wallet#frozen-enterprise

Trigger: Customer receives "enterprise is frozen cannot spend" error when trying to withdraw from V1 wallet.

Signals: frozen, enterprise is frozen, cannot spend, frozen enterprise

Steps:

  1. Verify the frozen status of the enterprise in the admin tool.
  2. Check internal records for any compliance or other reason the enterprise was frozen.
  3. Coordinate with the compliance or internal team (as applicable) to determine if the enterprise can be unfrozen.
  4. Once unfrozen, the customer can proceed with the standard migration steps.

Notes: Do not unfreeze an enterprise without confirming there is no compliance hold. Check internal Slack channels or escalation records for context.

Related