Scoutinternal

Token Flush Failures, Wrong Chain Recoveries, and Unsupported Asset Recovery

Token Flush Failures, Wrong Chain Recoveries, and Unsupported Asset Recovery

Problem

Customers encounter issues when tokens fail to flush from receive/forwarder addresses to the wallet base address, when funds are sent to an address on the wrong blockchain (e.g., LTC sent to a BTC address or BTC sent to an LTC address), or when unsupported tokens are received into a BitGo wallet and cannot be moved through normal means. These scenarios span multiple chains including BTC, LTC, BSV, ETH, BSC, Polygon, Arbitrum, and others. Customers may also request recovery of ERC-20/BEP-20 tokens from cross-chain deposits, flushing of tokens stuck in fee/gas tank addresses, or movement of tokens that BitGo does not natively support.

Diagnostics

  • Identify the request type: Determine whether this is (a) a token flush failure, (b) a wrong-chain recovery (UTXO-based), (c) a cross-chain recovery (EVM-based), (d) a gas tank / fee address token sweep, or (e) an unsupported token recovery.
  • Check chain support: Confirm whether the chain and token are supported by BitGo. Use internal tooling or check with Engineering if unsure. Some chains (e.g., Sonic/S) are not supported and not on the roadmap.
  • For flush issues: Use bga search with the transaction hash to check on-chain status. Verify whether the transaction is confirmed on-chain but missing from the wallet record. Check if the forwarder address has balance and whether the flush transaction was broadcast.
  • For wrong-chain recoveries (UTXO): Confirm the source coin, destination coin, wallet ID, and transaction ID. Determine whether the customer has their wallet passphrase or private key (xprv) and keycard. Check if the Wallet Recovery Wizard supports the coin pair (BTC ↔ LTC, BTC ↔ BCH, BTC ↔ BSV).
  • For cross-chain / EVM recoveries: Confirm the token contract address, the chain it was received on (e.g., BSC vs. ETH), and whether BitGo supports the token on that chain. Verify the TXID on the appropriate block explorer.
  • For gas tank / fee address sweeps: Confirm the enterprise ID, the gas tank / fee address, the token(s) and amount(s), and the destination address. Verify the customer's identity and authorization level.
  • For security tokens (e.g., PASS): Check whether the token contract has transfer restrictions (whitelisting). Determine if the forwarder address or fee address needs to be whitelisted at the contract level before a flush can succeed.
  • For unsupported tokens: Check whether the token can be onboarded by Engineering or if the customer can use the Wallet Recovery Wizard for self-service recovery.

Resolution

Scenario: flush-chain-recovery-wrong#wrong-chain-utxo

Trigger: Customer sent funds to an address belonging to a different UTXO-based chain (e.g., BTC sent to LTC address, LTC sent to BTC address, or BSV wrong-chain sends).

Signals: wrong chain, recover LTC from BTC, recover BTC from LTC, BSV wrong chain, wrong chain recovery, source coin, destination coin

Steps:

  1. Collect from the customer: source coin, destination coin, wallet ID of the receiving wallet, transaction ID(s), destination address for recovered funds, wallet passphrase or private key (xprv).
  2. Direct the customer to the BitGo Wallet Recovery Wizard (available on GitHub). The "Wrong Chain Recoveries" option is available in older versions (e.g., v3.1.3).
  3. In the Wallet Recovery Wizard, the customer selects the correct environment (Testnet or Mainnet), then "Wrong Chain Recoveries."
  4. The customer fills in: Source Coin, Destination Coin, Wallet ID, Transaction ID, Destination Address, API Key (BlockChair), Wallet Passphrase (or Private Key).
  5. If the customer cannot self-serve (e.g., missing keycard, complex multi-sig), escalate to Engineering with all collected details.
  6. For BitGo-assisted recoveries, Engineering may generate a recovery file that requires the customer's signature before broadcast.

Notes: Applicable to BTC, BCH, LTC, and BSV. The wrong-chain recovery option in the Wallet Recovery Wizard is only available in older versions (e.g., v3.1.3). Each recovery request should be submitted as a separate ticket.

Scenario: flush-chain-recovery-wrong#cross-chain-evm

Trigger: Customer sent EVM-based tokens to a BitGo wallet address on the wrong EVM chain (e.g., ERC-20 tokens sent over BSC, or tokens bridged to an unexpected token contract on Polygon).

Signals: cross chain recovery, BSC, ERC20, BEP20, hETH, Polygon, bridging, wrong chain EVM

Steps:

  1. Collect from the customer: token name and contract address, chain the tokens were received on, TXID, wallet ID, destination address.
  2. Verify the transaction on the appropriate block explorer (e.g., bscscan.com, polygonscan.com, etherscan.io).
  3. Check whether BitGo supports the token on the chain where it was received. If not, the token may need to be onboarded by Engineering before recovery can proceed.
  4. Escalate to the Engineering team with all collected details. Cross-chain EVM recoveries typically require Engineering intervention.
  5. Follow up with the customer on Engineering's timeline. These recoveries may take days to weeks.
  6. Once Engineering completes the recovery, provide the customer with the on-chain transaction link as confirmation.

Notes: For unsupported tokens received on an EVM chain, Engineering may need to onboard the token before recovery is possible. Each recovery request should be submitted as a separate ticket.

"This recovery request has been referred to our engineering team. We will follow up as soon as possible." (ticket #175400)

"Checked with Kamlesh in the office and looks like we need to onboard this token in order for us to be able to bridge the gap." (ticket #271392)

"We have further reindexed the transaction and it should reflect in the wallet. You may proceed with the recovery." (ticket #271392)

Scenario: flush-chain-recovery-wrong#security-token-flush-blocked

Trigger: A security token (e.g., PASS Token) is not flushing from a forwarder/receive address to the wallet base address due to contract-level transfer restrictions.

Signals: PASS token, security token, not flushing, whitelist, forwarder address, contract level

Steps:

  1. Confirm with the customer that the token in question is a security token with transfer restrictions at the smart contract level.
  2. Identify the correct forwarder address that needs to be whitelisted. Do NOT provide the fee address — provide the forwarder address.
  3. Instruct the customer's team to whitelist the forwarder address on the token's smart contract.
  4. Once whitelisting is complete, the flush should proceed without issue. If it does not, escalate to Engineering.

Notes: Initial responses may mistakenly provide the fee address for whitelisting. Always verify and provide the forwarder address instead.

"For the PASS Token issue, in order to flush these to the base address of the wallet, since this is a security token, your team will need to to whitelist this address on the contract level." (ticket #231778)

"Apologies for the confusion. Please whitelist the forwarder address instead of the fee address previously provided." (ticket #231778)

Scenario: flush-chain-recovery-wrong#gas-tank-token-sweep

Trigger: Customer requests recovery/sweep of ERC-20 tokens that have accumulated in the ETH gas tank (fee address) of their wallet.

Signals: gas tank, fee address, token sweep, fee wallet, IMX, USDC, recoverfromfeeaddress, video verification, Calendly

Steps:

  1. Collect from the customer: Enterprise Name, Enterprise ID, Enterprise Email, ETH Gas Tank Balance, ETH Gas Tank Address, Destination Address, Token name(s) and amount(s).
  2. Inform the customer that a video verification call is required for security purposes.
  3. Send the customer the Calendly scheduling link: https://calendly.com/bitgo-client-delivery/videoid. Ask them to reference their ticket number when scheduling.
  4. During the video call, verify the customer's government-issued photo ID. If the person on the call is not initially verified by BitGo, they must bring a previously verified and authorized person onto the call.
  5. After successful verification, escalate to Engineering to execute the gas tank recovery using the bga wallet recoverfromfeeaddress tool.
  6. Engineering generates recovery JSON files per token and submits them with AOK signatures.
  7. Provide the customer with on-chain transaction links as confirmation once complete.

Notes: Each token type in the gas tank may require a separate recovery transaction. Video verification is mandatory regardless of amount.

"If you wish to empty your gas tank then you have to schedule a video verification call with and have to verify the below mentioned information." (ticket #233256)

"Please use the following link to schedule a time to meet with us and verify the request: https://calendly.com/bitgo-client-delivery/videoid" (ticket #233256)

Scenario: flush-chain-recovery-wrong#unsupported-chain-or-token

Trigger: Customer requests flush or recovery of tokens on a chain that BitGo does not support and has no plans to support.

Signals: unsupported, not supported, not on the roadmap, Sonic, sonicscan, flush unsupported, unsupported token

Steps:

  1. Verify the chain and token by checking internal tooling and confirming with Engineering if needed.
  2. If the chain is confirmed unsupported and not on the roadmap, inform the customer clearly that BitGo does not support the chain at this time.
  3. For tokens on supported EVM chains that are simply not yet onboarded, check with Engineering on whether onboarding is feasible.
  4. If the customer has tokens on a supported chain but in a wallet that needs reindexing/rebroadcasting, attempt rebroadcasting the transaction first. Use bga search <txhash> to check status.

Notes: Some requests may involve a mix of supported and unsupported chains. Handle each chain separately — resolve what can be resolved and communicate clearly about what cannot.

"With regards to SONIC, we don't support it as of now" (ticket #315248)

"We have rebroadcasted the ETH transactions... This should now be reflected on the wallet record and balance" (ticket #315248)

Scenario: flush-chain-recovery-wrong#flush-rebroadcast

Trigger: Tokens appear on-chain at the forwarder/receive address but are not reflected in the BitGo wallet balance, or the flush transaction was not broadcast.

Signals: flush, not flushing, tokens stuck, forwarder, rebroadcast, reindex, wallet record, balance not reflecting

Steps:

  1. Use bga search <txhash> to check whether the transaction is found on-chain and whether it has a corresponding wallet transfer record.
  2. If the transaction is on-chain but not in the wallet record, attempt reindexing/rebroadcasting the transaction.
  3. After rebroadcasting, confirm with the customer that the balance now reflects in their wallet.
  4. If rebroadcasting does not resolve the issue, escalate to Engineering with the wallet ID, transaction hash, and forwarder address details.

Notes: Common for ERC-20 tokens on ETH and other EVM chains. Rebroadcasting typically resolves the issue when the transaction is confirmed on-chain but missing from the wallet record.

Scenario: flush-chain-recovery-wrong#funds-sent-to-sending-address

Trigger: Customer sent funds to a BitGo-controlled address that appears as the "From" address on a prior BitGo withdrawal in a block explorer, rather than to a designated deposit address from the wallet's Receive section. Funds are confirmed on-chain but are not auto-credited to the wallet.

Signals: from address, sending address, hot wallet address, withdrawal address, not credited, not detected, Receive section, deposit address, "From" on explorer

Steps:

  1. Ask the customer for the exact address used, the wallet ID they intended to deposit into, the transaction hash, the amount, and a screenshot showing where they obtained the address.
  2. Cross-reference the address against the wallet's historical transaction list and determine whether it is a designated deposit address (listed under the wallet's Receive section) or a sending/hot wallet address used for outgoing transactions.
  3. If the address is a sending address, explain to the customer that BitGo maintains two distinct address types. Designated deposit addresses are generated within the wallet UI under the Receive section and are configured to automatically detect and credit incoming transactions. Sending addresses are internal hot wallet addresses used to broadcast outgoing transactions and may appear as the "From" address on withdrawal transactions in block explorers, but they are not configured to automatically credit incoming deposits.
  4. Inform the customer that the funds are not lost but will not be auto-credited because the platform does not monitor sending addresses for inbound transactions. Escalate to the backend/infrastructure team for manual recovery assessment, providing the wallet ID, address, transaction hash, and amount. Flag this as a non-standard recovery scenario that may require manual intervention.
  5. Educate the customer to only use the deposit addresses provided in the wallet's Receive section for future inbound transfers, and to never derive an address from the "From" field of a block explorer withdrawal record.

Notes: This is a recurring support-desk scenario distinct from wrong-chain and cross-chain recoveries. The funds are on the correct chain and at a BitGo-controlled address, but the address type is wrong. The distinction between deposit addresses (Receive section, auto-credit) and sending/hot addresses (outgoing transaction sources, no auto-credit) must be communicated explicitly. Do not promise recovery before backend confirms feasibility.

"BitGo maintains separate address types: designated deposit addresses (for receiving funds) and sending/hot addresses (used for outgoing transactions). Funds sent to sending addresses are not automatically detected or credited to the wallet. Deposit Addresses are specifically designated for receiving funds and are generated within the BitGo wallet interface under the Receive section. Sending Addresses are internal hot wallet addresses used by BitGo to broadcast outgoing transactions; these addresses may appear in blockchain explorers as the From address on withdrawal transactions, but they are NOT configured to automatically credit incoming deposits." (ticket #360865)

Related