Scoutinternal

BTC Send / Transaction Failures on BitGo Wallets

BTC Send / Transaction Failures on BitGo Wallets

Problem

Customers report being unable to send BTC from their BitGo wallets. The symptoms vary: "denied by Policy" errors, transactions not broadcasting to the blockchain, failed transactions due to platform issues, inability to withdraw due to high miner fees or insufficient spendable balance, incorrect wallet passwords, and deprecated V1 wallet limitations. These issues span both the BitGo web UI and API (e.g., sendmany) and affect individual as well as batch BTC transactions.

Diagnostics

  • Identify the wallet version. Check the wallet ID: V1 wallets use the wallet root address as the ID; V2 wallet IDs begin with 5. V1 BTC wallets have been deprecated and sending is disabled.
  • Check wallet policies. Open the wallet in the admin tool and inspect whether a wallet policy (e.g., address whitelist) is configured and locked. Wallet Policy locks 48 hours after first configuration and cannot be unlocked. Confirm whether the destination address is on the whitelist.
  • Check who is approving. If a whitelist policy requires admin approval, verify whether the transaction creator is also the sole admin — admins cannot approve transactions they themselves create.
  • Review spendable balance vs. total balance. A wallet may show a BTC balance but have a spendable balance of zero if the balance is too small to cover current on-chain miner fees. Check current fee environment at https://mempool.space/graphs/mempool#1m.
  • Check for platform-wide BTC incidents. Review https://status.bitgo.com/ for any active or recent BTC processing incidents or scheduled maintenance.
  • Verify the wallet password. If the error indicates an incorrect wallet password, confirm the customer is using the correct wallet-level passphrase (distinct from the account login password).
  • For API users: Request the full endpoint and method, full payload (omitting passwords), full log response including errors and requestIDs, BitGo Express/SDK version, and the email address of the user who created the Access Token used to authenticate the call.

Resolution

Scenario: btc-send-sending-transaction#whitelist-policy-denied

Trigger: The customer sees a "denied by Policy" error when attempting to send BTC to an address not on the wallet's whitelist.

Signals: denied by Policy, wallet policy, whitelist, policy locked, admin approval, cannot send

Steps:

  1. Confirm the wallet has a whitelist policy configured by checking the wallet's policy settings in the admin tool.
  2. Determine when the policy was locked. Wallet Policy locks 48 hours after it is first configured. Once locked, BitGo does not permit the wallet policy to be unlocked.
  3. Inform the customer that sending to any address other than those on the whitelist will result in the policy error.
  4. Advise the customer that they can still send to addresses already on the whitelist.
  5. If the customer needs to send to a non-whitelisted address, advise them to add another Admin to the wallet. This allows the second admin to approve transactions created by the first admin, working around the restriction that admins cannot provide approval for transactions they create.
  6. If the customer wants a wallet without policy restrictions, advise them to create a new wallet and transfer funds from the policy-locked wallet to a whitelisted address (or the new wallet's address, if it is added to the whitelist first).

Notes: Admins cannot provide approval for transactions they create. This is by design. The workaround is to add a second admin who can approve the first admin's transactions.

"It appears you have configured a wallet policy on this wallet. Wallet Policy locks 48 hours after it is configured for the first time. Once locked, we do not permit the wallet policy to be unlocked." (ticket #83952)

"The funds on this wallet are usable as long as the receiver address being used is the same address added to the wallet's Whitelist. Sending to any other address will result in the Policy Error previously received. Adding another Admin to this wallet will allow you to workaround this error." (ticket #83952)

Scenario: btc-send-sending-transaction#v1-wallet-deprecated

Trigger: The customer has a V1 BTC wallet (wallet ID is a BTC address rather than a string starting with 5) and cannot send.

Signals: V1 wallet, deprecated, v1 BTC, wallet root address, cannot withdraw, v2 wallet

Steps:

  1. Identify the wallet version by examining the wallet ID. V1 wallets use the wallet root address (a BTC address) as the ID. V2 wallet IDs begin with 5.
  2. Inform the customer that BitGo has deprecated V1 BTC wallets and completely disabled the creation of new V1 wallets both via API and web UI.
  3. Instruct the customer to create a new BTC wallet (which will be a V2 wallet).
  4. Have the customer transfer the V1 balance to the new V2 wallet.
  5. From the new V2 wallet, they can deposit and withdraw as normal.

Notes: This applies only to BTC V1 wallets. Other coins are not affected by V1 deprecation in the same way.

"This is a V1 BTC wallet. We have deprecated v1 BTC wallets and completely disabled the creation of new v1 wallets both via API and web UI. You will need to create a new BTC wallet, which will be a v2 wallet, and you can transfer the v1 balance to the new v2 wallet." (ticket #228192)

"You can identify the wallet version by looking at the wallet ID. V1 wallets will have the wallet root address (the first wallet address created for the wallet) and v2 Wallet ID's will begin with a 5." (ticket #228192)

Scenario: btc-send-sending-transaction#high-miner-fees-insufficient-spendable

Trigger: The customer's wallet shows a BTC balance but spendable balance is zero or insufficient because the balance is too small relative to current on-chain miner fees.

Signals: spendable balance zero, high miner fee, cannot withdraw, insufficient funds, small balance, fee too high

Steps:

  1. Check the wallet's spendable balance in the admin tool. If it is zero while the total balance is non-zero, the issue is that miner fees exceed the available amount.
  2. Direct the customer to monitor on-chain miner fees and attempt the withdrawal when fees come down. Recommended monitoring links:
  3. Advise the customer that they must have enough funds to cover the sending amount plus BTC network fees charged by miners.
  4. If the customer previously submitted a transaction with a very low fee rate that is stuck, point them to the mempool explorer to check confirmation status.

Notes: This commonly affects wallets with small balances (e.g., under ~$50 equivalent in BTC) during periods of high network congestion. BitGo does not control miner fees.

"Spendable balance is zero because current BTC miner fee is high and the amount you are trying to withdraw is more than the fee required. You might want to monitor on-chain miner fee and withdraw when fee comes down" (ticket #228192)

"Once the on-chain fees drop, you should be able to spend from the wallet as long as you have enough funds to cover the sending amount plus the BTC network fees charged by miners." (ticket #228192)

Scenario: btc-send-sending-transaction#incorrect-wallet-password

Trigger: The error message indicates that the wallet password used during the withdrawal request is incorrect.

Signals: incorrect wallet password, wrong password, wallet passphrase, cannot withdraw, error password

Steps:

  1. Confirm with the customer that the error is about an incorrect wallet password (not account login password).
  2. Ask the customer to try again with the correct wallet password.
  3. If the customer has forgotten the wallet password, instruct them to reset it:
    • Navigate to Trade > Wallet Details > Settings > Forgot Wallet Password.
    • Note: Access to this option requires switching to the old UI.
  4. To switch to the old UI:
    • Step 1: Click on the profile icon in the top right corner.
    • Step 2: Click on Switch to classic view.
  5. In the settings on the classic view, the customer will find the option to update the wallet password.

Notes: The wallet password is distinct from the BitGo account login password. The "Forgot wallet password" flow requires the KeyCard or backup key.

"The error message indicates that the wallet password used during the withdrawal request is incorrect. Please try again and make sure to use the correct wallet password. If you happened to forgot the wallet password you may goto Trade > Wallet Details > Settings > Forgot Wallet Password" (ticket #319079)

"Please be informed that access to the specified options requires the switch to the old UI... Step 1 :- Click on the profile icon in the top right corner Step 2:- Click on Switch to classic view" (ticket #319079)

Scenario: btc-send-sending-transaction#platform-btc-processing-issue

Trigger: BTC transactions are signed and submitted but do not appear on the blockchain, and BitGo engineering has confirmed a platform-wide technical issue with BTC wallets.

Signals: not broadcasted, failed transaction, transaction not on blockchain, technical issue, system issue, cancelled transaction

Steps:

  1. Check https://status.bitgo.com/ for any active BTC incidents.
  2. If an incident is confirmed, inform the customer that the platform has experienced a technical issue affecting BTC transaction processing and that the engineering team is working on a fix.
  3. If transactions were cancelled by BitGo due to the issue, communicate this to the customer and confirm that the funds have been returned to the wallet.
  4. Monitor the status page for resolution and follow up with the customer once the issue is resolved.
  5. If no platform incident is listed but the customer reports a transaction not appearing on-chain, request the Transfer ID and Wallet ID and escalate to the engineering team for investigation.

Notes: During platform incidents, customers may open multiple tickets for the same transactions. Check for duplicate tickets before responding.

"Unfortunately, our platform has ran into some technical issues with our BTC wallets. Our engineering team is working on the fix right now. We will get back to you as soon as they fixed the issue." (ticket #225136)

"our system recently experienced a technical issue that affected the processing of BTC transactions, including the one you initiated. As a result, we were compelled to cancel the transaction to ensure the integrity and security of our platform." (ticket #225681)

Scenario: btc-send-sending-transaction#api-batch-send-failures

Trigger: An API customer reports that BTC batch sends via the sendmany method fail intermittently, requiring multiple retries and long wait times.

Signals: sendmany, batch, package, API, multiple retries, 30 minutes, intermittent failure

Steps:

  1. Ask the customer to provide the following information for triage:
    • Full endpoint exactly as it is being called and method
    • Full payload omitting passwords
    • Full log response including errors and requestIDs
    • BitGo Express/SDK version
    • Email address of the user who created the Access Token used to authenticate the call
  2. Check https://status.bitgo.com/ for any reported API or BTC processing issues.
  3. Once the above information is received, escalate to the engineering team for investigation.
  4. If no platform issue is found, investigate whether the failures are related to UTXO availability, fee estimation, or rate limiting.

Notes: Without the requested diagnostic information, the support team cannot properly triage intermittent API send failures.

"We will need your team to provide the following information to properly triage: Full endpoint exactly as it is being called and method Full payload omitting passwords Full Log response including errors and requestIDs Bitgo Express/SDK Version Email Address of the user who created the Access Token used to authenticate the call" (ticket #149798)

Related

  • bitcoin-consolidation — Small UTXOs can cause high effective fees and spendability issues; consolidation may help wallets with many small unspents.
  • keycards-and-private-keys — Wallet password recovery requires the KeyCard; relevant when customers have forgotten their wallet passphrase.
  • go-network-overview — Customers looking for off-chain transfer alternatives may benefit from Go Network if they are institutional users.