Scoutinternal

BCH (Bitcoin Cash) Transaction and Address Issues on BitGo

BCH (Bitcoin Cash) Transaction and Address Issues on BitGo

Problem

Customers encounter a range of issues when sending, receiving, or viewing Bitcoin Cash (BCH) transactions on the BitGo platform. The most common problems include: receiving "invalid address" errors when sending BCH to CashAddr-format addresses, small balance discrepancies caused by BCH replay protection inputs, "InsufficientBalance" errors due to UTXO availability, confusion over on-chain transaction amounts versus BitGo UI amounts due to the UTXO change model, platform-level BCH withdrawal outages, BTC accidentally sent to BCH wallet addresses requiring cross-chain recovery, incorrect wallet password errors during BCH withdrawal, and BTC address format changes when generating addresses via API.

Diagnostics

  • Identify the address format in use: Determine whether the customer is using a BCH CashAddr (starts with q or bitcoincash:) or a legacy address (starts with 1 or 3). BitGo's outgoing transaction flow only supports legacy BCH addresses natively; CashAddr must be converted or prefixed.
  • Check the error message and Error ID: Look up the Error ID in Kibana logs. Common errors include error 400: invalid address, InsufficientBalance, wallet not found, and incorrect wallet password errors.
  • Verify wallet balance and unspents: Use the List Wallet Unspents endpoint (https://developers.bitgo.com/api/v2.wallet.unspents) to check whether the spendable balance matches the confirmed balance, and whether unspents are tied up in unconfirmed transactions.
  • Check the BitGo status page: Visit https://status.bitgo.com/history for any active BCH withdrawal incidents before troubleshooting further.
  • Compare on-chain vs. UI amounts: If the customer reports a balance or amount discrepancy of approximately 0.00001 BCH (1000 satoshis), this is likely the replay protection taint input. If the on-chain amount is much larger than the UI withdrawal amount, this is UTXO change behavior.
  • Confirm wallet version: Ask whether the customer is using a v1 or v2 wallet. V1 BTC wallets do not support newer address formats (e.g., bc1/Bech32).
  • Identify cross-chain sends: If BTC was sent to a BCH address (or vice versa), confirm the TXID and destination address on a block explorer for both chains. The Wallet Recovery Wizard will be needed.
  • Check wallet password vs. login password: Confirm the customer understands that their BitGo login password may differ from their wallet passphrase, and that only the wallet creator uses the wallet passphrase while other users use their BitGo platform password.

Resolution

Scenario: bch-btc-bcc-address#cashaddr-invalid-address

Trigger: Customer receives an "invalid address" error (e.g., error 400: invalid address) when attempting to send BCH to a CashAddr-format destination address.

Signals: invalid address, CashAddr, cashaddr, error 400, BCH send error, q-prefix address, bitcoincash: prefix

Steps:

  1. Confirm the destination address is in CashAddr format (starts with q or p without a prefix, or bitcoincash: with a prefix).
  2. Advise the customer to convert the CashAddr address to a legacy BCH address using one of these tools:
    • https://cashaddr.bitcoincash.org/
    • https://bch.btc.com/tools/address-converter
  3. Alternatively, for UI sends, the customer can try adding the bitcoincash: prefix before the CashAddr address (e.g., bitcoincash:qqaqeduanynxt9j3yclczmgc9er6xk8zgyhwahjr8k). Note: the UI may still show an "Invalid" message, but the transaction may proceed as normal.
  4. For API sends, the same bitcoincash: prefix format can be used in the destination address field.
  5. After conversion or prefixing, retry the withdrawal.

Notes: BitGo converts incoming CashAddr addresses to legacy addresses in the background for deposits, but outgoing transactions require legacy format or the bitcoincash: prefix. This is a known platform limitation. An SDK bug related to CashAddr validation was identified and fixed in October 2024; customers on older SDK versions may still encounter issues. If the bitcoincash: prefix approach returns an error like "has no matching Script," escalate to engineering with the Error ID.

"Unfortunately, we do not support BCH cashAddr address format on our platform. We are converting incoming CashADDR addresses to the legacy addresses in the background. However, for outgoing transactions, you can use the following tool to convert the new CashADDR format to the legacy BCH addresses before sending: https://bch.btc.com/tools/address-converter" "As an interim you may use this prefix format when sending Cash Address bitcoincash:{Cash_address_here} Currently, while testing from our UI, you may still see an 'Invalid' message, but the transaction will proceed as normal." "Can you use the following link to convert the address and then retry with the new address? https://cashaddr.bitcoincash.org/"

Scenario: bch-btc-bcc-address#replay-protection-discrepancy

Trigger: Customer reports a small discrepancy (approximately 0.00001 BCH or 1000 satoshis) between the withdrawal amount shown in the BitGo UI and the on-chain transaction amount, or between the intended send amount and what the UI displays.

Signals: 0.00001 BCH, 1000 satoshi, replay protection, taint, balance discrepancy, amount difference, BCH display

Steps:

  1. Explain to the customer that BitGo adds tainted unspents to all BCH transactions to prevent replay attacks (protection against the BCH hard fork).
  2. Clarify that the approximately 0.000001–0.00001 BCH discrepancy is the taint input, which is paid for by BitGo, not by the customer. The customer is not responsible for returning this amount.
  3. The correct amount is sent to the intended recipient on-chain. The UI display difference is cosmetic and relates to how the replay protection input is accounted for.
  4. Reference: https://www.circle.com/blog/preventing-replay-attacks-after-the-bch-hard-fork
  5. If the customer requires exact UI reconciliation, note that a JIRA ticket (CS-327) was filed to add an explanatory line in the UI for replay protection inputs. Check with engineering for current status of this fix.

Notes: This is expected behavior and does not represent a loss of funds. The taint input can be thought of as a mandatory "gift" from BitGo to ensure proper replay protection on BCH transactions.

"This is because we add tainted unspents on all BCH transactions to prevent replay attack... It seems that the 1000 satoshi discrepancy is actually our taint input which is paid for by BitGo and not the user. That being said, clients are not responsible for returning any of the balance of tainted unspents, you can think of them as a 'gift' that is mandatory to make sure we have proper reply protection on BCH transactions." "We have verified that these are display problems related to Replay Protection inputs. We are working on the ticket internally to add an extra line explaining where these extra 0.0001 BCH come from in the UI, which should prevent the confusion you see here."

Scenario: bch-btc-bcc-address#insufficient-balance-utxo

Trigger: Customer receives an "InsufficientBalance" or "400: Insufficient Funds" error when attempting a BCH withdrawal despite appearing to have adequate wallet balance.

Signals: InsufficientBalance, Insufficient Funds, 400, unspents, UTXO, spendable balance, BCH withdrawal error

Steps:

  1. Use the List Wallet Unspents endpoint (https://developers.bitgo.com/api/v2.wallet.unspents) to check the wallet's current unspent state.
  2. Determine whether unspents are tied up in unconfirmed transactions, making funds temporarily unspendable.
  3. If the wallet has very few large unspents, recommend using the Fanout endpoint (https://developers.bitgo.com/guides/wallets/unspents/fan-out) to break apart larger unspents into smaller ones, enabling higher transaction throughput.
  4. If the wallet has too many small unspents (a transaction can only consume a maximum of 200 unspents), recommend using the Consolidate Unspents API endpoint to merge small unspents into larger ones.
  5. Recommend using the Send Many endpoint (https://developers.bitgo.com/guides/wallets/transact/send-to-many) to batch multiple recipients into a single transaction, reducing UTXO contention.

Notes: A transaction can only consume a maximum of 200 unspents. If the sum of the 200 highest-value unspents is not sufficient to cover the transaction amount plus fees, the "insufficient funds" error will occur even if the total wallet balance is adequate.

"This might occur if you have very few unspents in your wallet, and those unspents are currently tied up in unconfirmed transactions. Essentially, the amount of funds that are CURRENTLY available in your wallet are not sufficient to complete the transaction."

Scenario: bch-btc-bcc-address#utxo-change-amount-confusion

Trigger: Customer reports that the on-chain transaction amount (visible on a block explorer) is significantly larger than the withdrawal amount shown in the BitGo UI.

Signals: on-chain amount, block explorer, change, UTXO model, amount different, BCH transaction amount mismatch

Steps:

  1. Explain that Bitcoin Cash operates on a UTXO (Unspent Transaction Output) model. When a transaction is made, the wallet spends the entire UTXO and returns the remainder as change to the sender's wallet.
  2. Clarify that the blockchain explorer displays the total value of all transaction outputs, which includes both the amount sent to the recipient and the change returned to the sender.
  3. Confirm that only the intended withdrawal amount plus the network fee was deducted from the customer's wallet. The remaining balance was safely returned as change.

Notes: This is standard UTXO-based blockchain behavior and not a BitGo-specific issue.

"Bitcoin Cash operates on a UTXO (Unspent Transaction Output) model. This means that when a transaction is made, the wallet must spend the entire available balance (UTXO) associated with it. Any remaining balance after sending the intended amount is automatically returned to the sender as change."

Scenario: bch-btc-bcc-address#bch-withdrawal-outage

Trigger: Multiple customers report BCH send_many or withdrawal failures simultaneously, and the BitGo status page shows an active BCH incident.

Signals: BCH withdrawal, send_many, outage, status.bitgo.com, known issue, engineering investigating

Steps:

  1. Check https://status.bitgo.com/history for any active BCH withdrawal incidents.
  2. If an active incident is confirmed, inform the customer that engineering is actively investigating and provide the status page link.
  3. Monitor the status page for resolution. Once engineering confirms the fix, notify the customer that withdrawals should now be working correctly.
  4. If no active incident is listed but multiple customers are reporting failures, escalate to engineering via the internal BTC Slack channel with wallet IDs and error details.

Notes: Historical BCH withdrawal outages have been resolved within hours. If the customer has stuck transactions (status "Signed" but not broadcast), engineering may need to manually fail them upon request.

"We currently have a known issue with BCH withdrawals: https://status.bitgo.com/history Engineering is actively investigating." "The transactions have been updated as failed."

Scenario: bch-btc-bcc-address#cross-chain-btc-to-bch

Trigger: Customer reports that BTC was accidentally sent to a BCH wallet address and needs to recover the funds.

Signals: wrong chain, BTC sent to BCH, cross-chain, recovery, Wallet Recovery Wizard, WRW

Steps:

  1. Direct the customer to the BitGo Wallet Recovery Wizard (WRW), which supports recovering funds sent to addresses on the wrong chain (e.g., BTC sent to a BCH address).
  2. The WRW can be downloaded from its GitHub page.
  3. Provide installation instructions:
    • MacOS: Double-click the downloaded .dmg file. Drag 'BitGoWalletRecoveryWizard' to the 'Applications' folder. Right-click the icon and select 'Open'. If a publisher-unknown notification appears, click 'Open'.
    • Windows: Double-click the downloaded .exe file. Follow the Setup wizard instructions.
  4. When using the WRW, the customer can log into 'Testnet' (https://test.bitgo.com/), 'Mainnet' (https://www.bitgo.com/), or 'Non-BitGo Recoveries'.
  5. The customer will need their Recovery KeyCard to perform the recovery.

Notes: The WRW also supports recovering funds from legacy migrated Bitcoin Cash wallets and recovering ERC20 tokens not officially supported by BitGo. The customer should confirm they have their KeyCard before starting the process.

Scenario: bch-btc-bcc-address#incorrect-wallet-password

Trigger: Customer receives a wallet password error when attempting a BCH withdrawal.

Signals: wallet password, incorrect password, BCH withdrawal error, wrong password, Forgot Wallet Password

Steps:

  1. Clarify that the BitGo login password can be different from the wallet passphrase.
  2. Explain that the creator of the wallet must use the wallet passphrase they originally set. Any other user with spend permission must use their BitGo platform password.
  3. If the customer has changed their login password, their wallet passphrase has not changed.
  4. If they cannot remember their wallet password, instruct them to reset it via: Wallet > Settings > "Forgot Wallet Password?"
  5. After completing the wallet password reset, retry the withdrawal.

Notes: This applies to all UTXO-based wallets, not just BCH.

"Please also note that your login password can be different from your wallet password and if you had changed your login password, your wallet passwords will not change. Also, Please note the creator of the wallet will need to use the wallet passphrase they set for the wallet. Any other user will use their BitGo platform password. You can reset your wallet password from Wallet > Settings > Forgot Wallet Password?"

Scenario: bch-btc-bcc-address#btc-address-format-api

Trigger: Customer reports that BTC addresses generated via API have changed format (e.g., from P2SH "3"-prefix addresses to P2WPKH "bc1"-prefix addresses) without prior notice.

Signals: BTC address format, P2SH, P2WPKH, bc1, address type, chain code, address generation API

Steps:

  1. Direct the customer to the BitGo address types documentation: https://developers.bitgo.com/coins/address-types
  2. Explain that the customer should use chain codes when calling the Create Address API endpoint to control the address type generated.
  3. For BTC address creation, reference the coin-specific documentation at https://developers.bitgo.com/coins/bitcoin.
  4. Note that the UI wallet setting (e.g., "Legacy P2SH") may not affect API-generated addresses; the chain code must be explicitly passed in the API request payload.

Notes: This change may not have been communicated via a dedicated email notification. Updates are typically included in SDK/package release notes. The UI may still generate P2SH addresses by default even when the API behavior has changed.

"The issue has been resolved by providing the chaincode to the getAddress request as you suggested."

Scenario: bch-btc-bcc-address#v1-wallet-invalid-address

Trigger: Customer using a v1 BTC wallet receives an "invalid address" error when trying to send to a valid BTC address (e.g., a Bech32/bc1 address).

Signals: v1 wallet, invalid address, BTC, bc1, legacy wallet, migrate, v2 wallet

Steps:

  1. Confirm the customer is using a v1 BTC wallet, which does not support newer address formats such as Bech32 (bc1).
  2. Advise the customer to migrate to a v2 wallet by creating a new BTC wallet on the UI and then withdrawing funds from the v1 wallet to the newly created v2 wallet.
  3. Once funds are in the v2 wallet, the customer can withdraw to the intended address.

Notes: Migration from v1 to v2 is performed by creating a new wallet and transferring funds; there is no in-place upgrade mechanism.

"The address may be valid but you may also be withdrawing from an older v1 btc wallet that does not support similar addresses. You can migrate to a new v2 wallet and then withdraw to this address. (migrating to a v2 wallet is done simply by creating a new btc wallet on UI and then withdrawing the funds from the older v1btc wallet to the newly created one)."

Scenario: bch-btc-bcc-address#kraken-receive-address-rejected

Trigger: Customer is unable to deposit BCH from an external exchange (e.g., Kraken) to their BitGo BCH wallet because the exchange rejects the BitGo receive address.

Signals: Kraken, deposit, receive address, rejected, external exchange, address converter, BCH deposit

Steps:

  1. BitGo BCH wallets generate legacy-format receive addresses. Some external exchanges may require or only accept CashAddr-format addresses.
  2. Advise the customer to convert their BitGo legacy BCH receive address to CashAddr format using: https://bch.btc.com/tools/address-converter
  3. Provide the converted CashAddr address to the external exchange for the deposit.
  4. Note: the customer uses this conversion tool at their own risk.
  5. Suggest sending a small test transaction first before transferring the full amount.

Notes: BitGo converts incoming CashAddr addresses to legacy in the background, so BCH deposited to either format will arrive correctly in the BitGo wallet.

"You may need to use the following tool to convert old style BCH addresses to the new CashADDR format: https://bch.btc.com/tools/address-converter. However, please note that you are using this conversion tool at your own risk."

Scenario: bch-btc-bcc-address#no-swap-feature

Trigger: Customer asks how to convert BCH to another cryptocurrency (e.g., VET) within their BitGo wallet.

Signals: convert, swap, exchange, BCH to VET, BCH to BTC, trade, within wallet

Steps:

  1. Inform the customer that in-wallet cryptocurrency conversion/swapping is not supported on BitGo.
  2. If the customer has a BitGo Go Account with trading enabled, they may be able to use the "Trade" feature. If the trading feature is not yet enabled, instruct the customer to click on the "Trade" feature and complete the agreement. The KYC team will verify details and notify them of the trade account status.
  3. For withdrawal to an external exchange for conversion, guide the customer through the standard withdrawal process: Wallet > Withdrawal > enter destination address and amount > Preview Withdrawal > Send Funds > enter 2FA code and wallet password.

Notes: Not all customers will have trading features available. Bank account linking requires a fully activated Go Account and trading feature.

Scenario: bch-btc-bcc-address#bch-api-deposit-txhash-missing

Trigger: Customer's software stops recording transaction hashes for BCH deposits received via API, while withdrawals and other cryptocurrencies work normally.

Signals: transaction hash, deposit, API, BCH, software, webhook, missing txid

Steps:

  1. Ask the customer to provide:
    • Full endpoint and method used
    • Full payload
    • BitGo Express/SDK version
    • User email who created the API Access Token
  2. Advise the customer's development team to check their software's interaction with the BitGo API and review relevant logging for any BitGo error or requestID.
  3. Note that it is possible the team is not using Express and is calling endpoints directly. The logging should indicate the source of the issue.
  4. If no BitGo-side error is found, the issue is likely in the customer's integration code.

Notes: This type of issue is typically on the customer's integration side. BitGo support can help investigate if the customer provides the necessary API details and logs.

Related