Scoutinternal

Unable to Send or Receive Bitcoin — General Troubleshooting

Unable to Send or Receive Bitcoin — General Troubleshooting

Problem

Customers report being unable to send or receive Bitcoin (BTC) through the BitGo platform. Symptoms vary widely: the send button may not appear on the dashboard, the transaction may remain stuck at "Sending funds," users may encounter errors or policy violation warnings when attempting to send, or incoming Bitcoin deposits may not appear in the wallet. This is the most commonly reported issue category for BTC wallets and can stem from multiple root causes.

Diagnostics

  • Confirm the wallet type and coin: Open the customer's wallet in the BitGo admin tool and verify it is a BTC wallet (not a test wallet or a different coin).
  • Check wallet balance and unspent outputs: Verify that the wallet has sufficient confirmed balance. Look at the unspents to determine if the balance is composed of many small, unconfirmed, or dust-level UTXOs.
  • Review wallet policies: Check whether any spending policies (e.g., velocity limits, whitelist restrictions) are configured on the wallet that could trigger a "policy might be violated" message.
  • Check transaction history: Look for any pending or stuck outgoing transactions that may be holding the balance in an unconfirmed state.
  • Verify the receive address: If the customer reports not receiving BTC, confirm the receive address belongs to the correct wallet and check the blockchain for incoming transaction status (confirmations, mempool presence).
  • Check for platform-level issues: Review the BitGo status page and internal incident channels for any known outages or delays affecting BTC transaction processing.
  • Review user permissions: Confirm the user has the appropriate role (spender or admin) on the wallet to initiate sends.

Resolution

Scenario: bitcoins-bitcoin-send-sending#send-button-missing-or-send-fails

Trigger: Customer cannot find the send/withdrawal option on the dashboard or clicks send and the transaction does not proceed.

Signals: cant send, no send bitcoin option, send button missing, unable to send bitcoin, sending broken

Steps:

  1. Confirm the customer is logged in and viewing the correct BTC wallet (not a receive-only or watch-only wallet).
  2. Ensure the customer has the "Spender" or "Admin" role on the wallet. If they are a "Viewer," they will not see the send option.
  3. Instruct the customer to navigate to their wallet, then select the "Withdrawal" button (or "Send" button within the transactions page).
  4. Have the customer enter the destination Bitcoin address, the amount in BTC or USD, optionally a message, then click "Preview Withdrawal."
  5. After reviewing the transaction details, the customer should click "Send Funds," then enter their 2-Factor Authentication code and wallet password.
  6. If the transaction still fails or the button is unresponsive, ask the customer to clear browser cache, try a different browser, or disable browser extensions, then retry.
  7. If the issue persists, escalate to engineering with the wallet ID and a description of the observed behavior.

Notes: This scenario covers legacy BitGo web wallet users. The UI flow may differ slightly for enterprise/institutional dashboard users.

Scenario: bitcoins-bitcoin-send-sending#policy-violation-error

Trigger: Customer sees a message indicating that a policy might be violated when attempting to send Bitcoin.

Signals: policy might be violated, policy error, cant send bitcoin policy, error when send bitcoins

Steps:

  1. Open the customer's wallet in the admin tool and review the configured wallet policies (velocity limits, whitelist address restrictions, transaction size limits).
  2. Identify which policy is being triggered by comparing the attempted transaction parameters (amount, destination address, frequency) against the policy rules.
  3. If the destination address is not whitelisted and the wallet has an address whitelist policy, advise the customer (or an admin on the wallet) to add the address to the whitelist.
  4. If a velocity limit is being hit, inform the customer of the limit and advise them to wait until the policy window resets, or have a wallet admin adjust the policy.
  5. If the customer believes the policy is incorrectly configured, a wallet admin can modify or remove the policy from the wallet settings.

Notes: Only users with the Admin role on the wallet can modify policies. Spenders cannot change policy settings themselves.

Scenario: bitcoins-bitcoin-send-sending#transaction-stuck-sending

Trigger: Customer reports that the transaction remains at "Sending funds" status and does not confirm or complete.

Signals: transaction remain at sending funds, stuck sending, pending transaction, bitcoin not released

Steps:

  1. Locate the transaction in the wallet's transaction history and retrieve the transaction ID (txid).
  2. Check the transaction on a public blockchain explorer to see if it has been broadcast to the Bitcoin network.
  3. If the transaction is in the mempool but unconfirmed, it may be due to a low fee rate. Check the fee rate used and compare it against current network conditions.
  4. If the fee was too low, consider whether a child-pays-for-parent (CPFP) transaction or fee bumping (RBF, if enabled) can be used to accelerate confirmation.
  5. If the transaction does not appear on the blockchain at all, escalate to engineering to investigate whether the transaction was fully signed and broadcast.
  6. Advise the customer that BTC network congestion can cause delays and that unconfirmed transactions will eventually either confirm or be dropped from the mempool.

Notes: BitGo's fee estimation uses third-party fee sources and targets confirmation within a default of 2 blocks. During high-congestion periods, even estimated fees may be insufficient.

Scenario: bitcoins-bitcoin-send-sending#bitcoin-not-received

Trigger: Customer reports that Bitcoin sent to their BitGo wallet has not arrived or is not visible in their balance.

Signals: bitcoin not received, bitcoins does not arrived, not receiving bitcoins, havent receive bitcoin, bitcoin did not come

Steps:

  1. Obtain the transaction ID (txid) or the sending address from the customer.
  2. Verify the destination address belongs to the customer's BitGo wallet by checking the wallet's receive address list (any address shown on the Deposit page is valid).
  3. Look up the txid on a blockchain explorer to confirm the transaction's confirmation count.
  4. If the transaction has zero confirmations, advise the customer to wait — BTC deposits typically require at least 1-2 confirmations before appearing in the wallet balance.
  5. If the transaction is confirmed but the balance does not reflect the deposit, check for any consolidation transactions or wallet sync issues and escalate to engineering if needed.
  6. If the customer sent funds to an address that does not belong to their BitGo wallet, BitGo cannot recover those funds. Advise the customer to contact the owner of the destination address.

Notes: Customers may see multiple receive addresses on their Deposit page. All displayed addresses are valid for receiving Bitcoin to that wallet. New addresses can be generated for each transaction for privacy purposes.

Scenario: bitcoins-bitcoin-send-sending#send-error-generic

Trigger: Customer encounters a generic or unspecified error when attempting to send Bitcoin via the UI or API.

Signals: error with send bitcoins, error when send, problem sending bitcoin, issue sending bitcoin

Steps:

  1. Ask the customer for the exact error message or error code displayed.
  2. Verify the wallet has sufficient confirmed balance to cover both the send amount and the estimated network fee.
  3. Check whether the wallet has a large number of small unspents. If so, the transaction may fail to build due to excessive inputs — recommend running a consolidation using BitGo SDK tools before retrying.
  4. If using the API (e.g., sendcoins), confirm the customer is passing the correct parameters including walletPassphrase and a valid destination address.
  5. If the error is intermittent or not reproducible, ask the customer to retry. If it persists, collect the full error response and escalate to engineering.

Notes: For consolidation, ensure regular transactions enforce confirmations by adding { minConfirms: 1, enforceMinConfirmsForChange: true } to the transaction call so they do not conflict with pending consolidation outputs.

Scenario: bitcoins-bitcoin-send-sending#bitcoinbuilder-distribution

Trigger: Customer contacts BitGo regarding Bitcoin distributions related to BitcoinBuilder (e.g., Mt. Gox creditor distributions).

Signals: BitcoinBuilder, distribution, bitcoinbuilder distribution

Steps:

  1. Confirm with the customer that their account information and receiving details are up to date on their BitGo profile.
  2. Verify internally that the customer's information has been submitted or is queued for submission to BitcoinBuilder for the upcoming distribution cycle.
  3. If the customer reports having received the BTC successfully, mark the case as resolved.
  4. If the distribution has not yet occurred, advise the customer that the timing is dependent on BitcoinBuilder's distribution schedule and that BitGo has forwarded the necessary information.
  5. If there is a discrepancy or delay, coordinate with the relevant internal team handling BitcoinBuilder distributions.

Notes: These cases are specific to creditor distributions through BitcoinBuilder and are not standard send/receive issues. The customer's case may be resolved once the distribution is confirmed on-chain.

"Please disregard! I got the BTC. All is well. Thank you for everything. I am in tears finally after a decade. Case closed and good luck to you!" (ticket #275327)

Related

  • bitcoin-transaction-fees — Fee estimation and network congestion may cause send failures or delayed confirmations.
  • bitcoin-consolidation — Wallets with many small unspents may encounter errors when building send transactions; consolidation can resolve this.
  • wallet-policy-configuration — Policy violations during sends are governed by wallet-level spending policies that admins can modify.