Scoutinternal

Ethereum (ETH) Wallet Common Issues: Unsupported Tokens, Balance Sync, and Spendability

Ethereum (ETH) Wallet Common Issues: Unsupported Tokens, Balance Sync, and Spendability

Problem

Customers using BitGo Ethereum wallets encounter several recurring issues: unexpected "Generic ETH ERC1155" token transfers appearing in their wallet from unknown sources, ETH balances showing as confirmed but not spendable (spendable balance near zero despite confirmed balance being present), and general wallet sync or display problems. These issues affect ETH custody (CUST) and hot wallets and can cause confusion around transaction reports, balance availability, and wallet usability.

Diagnostics

  • Identify the specific symptom: Determine whether the customer is reporting (a) an unexpected/unknown token appearing in the wallet, (b) a balance that is confirmed but not spendable, or (c) a general wallet display or sync issue.
  • Check the wallet details via admin tooling: Look up the wallet by Wallet ID. Inspect the balance, confirmedBalanceString, and spendableBalanceString fields. A large gap between confirmed and spendable balances indicates a consolidation or flush issue.
  • Review the needsConsolidation flag: In the wallet's address details, check if "needsConsolidation": true. This indicates funds are sitting on a receive address and need to be swept to the base address.
  • Check lastConsolidatedTime: Compare the last consolidation timestamp to when the funds were received. A stale timestamp may indicate the consolidation has not run or failed.
  • For unknown token transfers: Check the transaction on Etherscan. Look at whether the transfer is an ERC-20, ERC-721, or ERC-1155 token. If it is ERC-1155 or another unsupported token standard, it is likely a dust/spam transaction.
  • Check the Transfers screen in the UI: Confirm whether the unsupported token transfer is still visible or has been removed (BitGo deployed a fix to hide unsupported token transfers).
  • Review the forwarder version and address details: In the address coinSpecific block, check forwarderVersion, pendingChainInitialization, and pendingDeployment for any address-level issues.

Resolution

Scenario: eth-wallet-wallets-issue#unsupported-erc1155-dust

Trigger: Customer reports receiving an unexpected "Generic ETH ERC1155" token deposit from an unknown source in their ETH wallet.

Signals: Generic ETH ERC1155, unsupported token, dust transaction, unknown deposit, spam transaction, ERC1155, 0.000000000000000000000000000001

Steps:

  1. Look up the transaction hash on Etherscan to confirm the transaction details.
  2. Verify that the transaction is a dust transaction — typically a minimal amount sent to multiple recipients, often involving unsupported token standards like ERC-1155.
  3. Explain to the customer that "dust transactions" for account-based coins like ETH are generally harmless and can be treated as spam. Advise them not to click or open any links associated with the transaction, as they may lead to malware, phishing sites, or advertisements.
  4. Clarify that ERC-1155 is a different token standard from ETH (Ether) or ERC-20 tokens. The ETH wallet can hold all supported ERC-20 tokens, but ERC-1155 tokens are not supported.
  5. Confirm that BitGo deployed a fix that no longer shows unsupported token transfers in the wallet going forward. If the customer previously saw the transfer and it has since disappeared, this is expected behavior.
  6. If the customer asks about discrepancies in reported amounts (e.g., email shows a very small decimal value while the report shows "1"), request the original notification content for review. The discrepancy relates to how the unsupported token amount is interpreted and displayed.

Notes: The ERC-1155 transfer shares the same Wallet ID as the customer's main Ethereum wallet because all token types received at ETH addresses appear under the same wallet. These cannot be "combined" — they are different token standards. The unsupported token transfer is intentionally suppressed from the UI after the fix.

"Dust transaction" for account based coins (like ETH) are generally harmless and can be treated as spam. The transactions might include malicious links leading to malware, phishing sites, or advertisements in the transaction details. You can simply ignore these transactions and not click or open any link associated with the transaction." (ticket #231928)

"We can confirm that the deletion of the 1 Generic ETH ERC1155 transfer is intended. This is due to a fix we deployed which will no longer show unsupported token transfers in the wallet going forward." (ticket #231928)

Scenario: eth-wallet-wallets-issue#confirmed-not-spendable

Trigger: Customer reports that their ETH wallet shows a confirmed balance but the spendable balance is zero or near-zero, preventing them from sending funds.

Signals: ETH not spendable, confirmed but not spendable, spendable 0, consolidation needed, needsConsolidation, flush, balance sync

Steps:

  1. Look up the wallet via admin tooling and compare the confirmedBalanceString and spendableBalanceString values. If confirmed is significantly higher than spendable, the funds are likely on a receive address that needs consolidation.
  2. Check the address details for the flag "needsConsolidation": true.
  3. Direct the customer to consolidate the balance using the consolidation API endpoint documented at: https://developers.bitgo.com/docs/wallets-consolidate
  4. If the customer is unable to run the consolidation themselves (e.g., they do not have BitGo Express set up or API access), escalate to the engineering/operations team to perform a manual flush of funds from the receive address to the base address.
  5. After the flush or consolidation is performed, verify that the wallet balance fields are back in sync — confirmed and spendable balances should match.
  6. Confirm with the customer that funds are now spendable.

Notes: Historically, BitGo support performed flushes on behalf of customers upon request. Customers should be encouraged to use the consolidation API going forward. This issue commonly occurs when ETH is deposited to a forwarding/receive address and the automatic forwarding has not completed or the forwarder version is older (e.g., forwarderVersion: 0).

"Please refer to the below links and request you to consolidate the balance. https://developers.bitgo.com/docs/wallets-consolidate" (ticket #256907)

"Please check now — the balances are in sync. Balance: 2.88890722000000439 ETH, Confirmed: 2.88890722000000439 ETH, Spendable: 2.88890722000000439 ETH" (ticket #256907)

Scenario: eth-wallet-wallets-issue#general-sync-display

Trigger: Customer reports that their ETH wallet state is not updating, balances appear incorrect, or the wallet is not visible/accessible in the UI.

Signals: ETH wallet sync, wallet not updating, wallet not visible, out of sync, wallet display issue, wallet state, cannot see wallet

Steps:

  1. Confirm the customer's enterprise ID and wallet ID.
  2. Look up the wallet in admin tooling to verify its existence and current state.
  3. Check whether the wallet's balanceDetails.updated timestamp is recent. A stale timestamp suggests the wallet balance has not been refreshed.
  4. If the wallet exists but is not visible in the UI, verify that the customer's user account has the correct permissions and is associated with the correct enterprise.
  5. If balances appear out of sync, attempt to trigger a balance rebuild or escalate to the engineering team for a manual resync of the wallet state.
  6. If the issue persists or involves wallet creation failures, check the address coinSpecific fields for pendingChainInitialization, creationFailure, or pendingDeployment flags and escalate to engineering if any are in an error state.

Notes: Many historical tickets in this cluster have minimal detail, suggesting these issues were resolved through backend fixes or manual interventions by engineering. If standard troubleshooting does not resolve the issue, escalate to the platform engineering team with the wallet ID, enterprise ID, and a description of the observed vs. expected behavior.

Related