Scoutinternal

Wallet Balance Discrepancies: UI, API, and Report Mismatches

Wallet Balance Discrepancies: UI, API, and Report Mismatches

Problem

Customers report that wallet balances displayed in the BitGo UI, returned via API, or shown in holdings/wallet reports do not match expected values, on-chain balances, or each other. This affects multiple coins and chains (BTC, ETH/ERC-20 tokens, SOL, STX, DOT, NEAR, AVAXC, XLM, BCH, SUI, SEI, and others). Symptoms include: balance showing as zero despite confirmed deposits, spendable balance being lower than confirmed balance, reports returning different figures than the UI, and API endpoints returning zero or incorrectly formatted values. These discrepancies can block withdrawals and disrupt reconciliation workflows.

Diagnostics

  • Identify the wallet and coin: Obtain the wallet ID, coin ticker, and enterprise ID from the customer. Confirm which balance field is affected (total balance, confirmed balance, spendable balance, or report balance).
  • Check wallet balances via admin tooling (bga): Run bga w <walletID> to compare Balance, Confirmed, Spendable, and TRS Balance fields. Note any differences between these values.
  • Compare with on-chain balance: Look up the wallet's base/root address on the appropriate block explorer (e.g., Etherscan, mempool.space, Solscan, Stacks Explorer, Subscan for DOT). Compare the on-chain balance to what BitGo reports.
  • Check for unconfirmed transactions: Look for transactions stuck in mempool or in state=attempted in the send queue. For BTC, run bga w <walletID> unspents to inspect unspent status and confirmation count.
  • Check for unflushed token balances (ETH/ERC-20): Compare the spendable balance to the total balance. If spendable is lower, tokens may be sitting on receive (forwarder) addresses and have not been flushed to the base address. Use bga admin getNonZeroBalanceForwarderAddresses to identify unflushed addresses.
  • Check for unconsolidated funds (SOL, DOT, SUI, BCH, BTC): For account-based coins (SOL, DOT, SUI), funds on receive addresses need consolidation to the root address. For UTXO coins (BTC, BCH), check the unspents tab for frozen unspents or excessive fragmentation.
  • Check for locked/frozen unspents (BTC): In the wallet's Unspents tab, verify whether any unspents are frozen, which makes them non-spendable.
  • Check gas tank / fee address balance (ETH/ERC-20): If flush transactions are failing, the fee address may have insufficient ETH. Check the fee address balance on Etherscan.
  • Check token enablement (SOL tokens): For newer SOL tokens (e.g., TRUMP, ai16z), verify the token is enabled in the wallet's Settings tab. If the token was received before enablement, it may not appear.
  • Check for indexer lag or known outages: Review https://status.bitgo.com/ for active or recent incidents. BTC fee spikes can cause indexer delays. Check internal Slack channels for known indexer issues.
  • Check report configuration: For holdings report discrepancies, confirm which report the customer is using (Holdings by Account, Holdings by Address, Looker report), the timestamp/timezone used, and whether there is a known ~2-hour latency between UI and reports.
  • Check for deprecated tokens: If a token (e.g., EOS ERC-20) appears unexpectedly in a wallet or report, verify whether it is a deprecated token that should have been removed.
  • Check for v1 wallet issues: If the coin is v1btc, the wallet may not display correctly in the modern UI. Verify via admin tooling whether the balance exists and whether the wallet needs to be upgraded or migrated.

Resolution

Scenario: balance-balances-discrepancy-wallet#unflushed-erc20-tokens

Trigger: ETH wallet shows total/confirmed balance higher than spendable balance for ERC-20 tokens (USDC, USDT, etc.), and tokens are sitting on forwarder/receive addresses rather than the base address.

Signals: spendable balance lower than confirmed, ERC-20, USDC, USDT, token flush, forwarder address, ETH wallet, receive address

Steps:

  1. Confirm the discrepancy by running bga w <walletID> and comparing Spendable vs. Confirmed balances for the affected token.
  2. Check the fee address (gas tank) balance on Etherscan. If the gas tank has insufficient ETH (recommended minimum ~0.5–0.7 ETH), advise the customer to fund it before flush can succeed.
  3. Identify unflushed forwarder addresses using: bga admin getNonZeroBalanceForwarderAddresses --baseAddress <baseAddress> --tokenAddresses <tokenContractAddress> --outputFile <file> --errorFile <errorFile> --forwarderVersion 1
  4. Perform a manual token flush using: bga admin forwardToken --wallet <walletID> --tokenAddress <tokenContractAddress> --addresses <forwarderAddresses>
  5. If there are stuck flush transactions in the send queue due to insufficient gas, the customer must fund the fee address first, then the stuck transaction will confirm and new flushes can proceed.
  6. Verify the spendable balance now matches the confirmed balance after flush transactions confirm on-chain.

Notes: Token flush is automatic but can fail silently if the fee address is underfunded or the forwarder address contract is not yet deployed on-chain. Customers can also call the Forward Token API themselves: https://developers.bitgo.com/api/v2.wallet.forwardToken

"This is standard as we need to perform what we call a 'flush' of the tokens in all the receive addresses to the wallet's base address, so they can be spendable." "We could see there are some addresses which has not been flushed on the base address. We need to perform the manual flush on our end." "This was because of an issue that affected deploying receive addresses in Aug 1. The root cause was fixed then, I just completed the flush to the base addresses."

Scenario: balance-balances-discrepancy-wallet#unconsolidated-account-based

Trigger: For account-based coins (SOL, DOT, SUI, STX), the wallet balance does not match the on-chain balance, or spendable is zero while confirmed shows a balance, because funds are on receive addresses that have not been consolidated to the root address.

Signals: SOL, DOT, SUI, STX, consolidation, spendable zero, receive address, unconsolidated, root address

Steps:

  1. Verify the discrepancy by comparing bga w <walletID> output with the on-chain explorer balance for the root address.
  2. For STX wallets, run the indexer consolidation commands:
    • bga indexer execute CONSOLIDATE_WALLET_STATE <rootAddress>
    • bga indexer execute CONSOLIDATE_ADDRESS_STATE <rootAddress>
  3. For SOL wallets with tokens (e.g., TRUMP, ai16z), the customer must consolidate the wallet to move tokens from Associated Token Addresses to the base address. Advise the customer to trigger consolidation via the API or UI.
  4. Re-check the wallet balance after consolidation completes and confirm it matches the on-chain balance.

Notes: For SOL tokens that fail to enable, a workaround is to send a small amount of the token to the wallet's base address to enable the token, then consolidate previously received amounts. STX balance discrepancies are a recurring issue and may require manual indexer consolidation by support.

"Balance should be matching now with chain... Balance: 103001.980142 STX, Confirmed: 103001.980142 STX, Spendable: 103001.980142 STX" "These tokens are still residing on the Associated Token Addresses which correspond to the receive addresses where they were sent. This wallet needs to be consolidated once more to move these to the base address of the wallet." "As a workaround, your team can send a small amount of the token to the wallet's base address to enable the token on the wallet. From there, your team should then be able to consolidate the previously received amounts to the base address."

Scenario: balance-balances-discrepancy-wallet#btc-indexer-delay

Trigger: BTC wallet balances are delayed in updating after transactions are broadcast or confirmed on-chain, often correlated with BTC network fee spikes or known platform outages.

Signals: BTC, balance delay, indexer, mempool, fee spike, unconfirmed, status.bitgo.com, balance not updating

Steps:

  1. Check https://status.bitgo.com/ for active or recent BTC-related incidents.
  2. Verify in admin tooling whether the customer's transactions are confirmed on-chain but not yet reflected in the wallet balance.
  3. If the issue aligns with a known incident, inform the customer and advise them to subscribe to the status page for updates.
  4. If the issue persists after the incident is resolved, escalate to engineering via JIRA with the wallet ID and affected transaction IDs.

Notes: BTC miner fee spikes cause a pile-up of stuck low-fee transactions, which delays the BitGo indexer's ability to process and index transactions. This is a platform-level issue resolved by engineering. The root cause in past incidents was that total wallet balance was including pending transactions stuck in mempool due to low fees; engineering updated the system to exclude those from the total balance.

"Due to recent changes on our end the total wallet balance was showing including all previously pending transactions that are coming to your wallet but the transactions are stuck in mempool due to less fees and need to rebase the fees on those transactions. Our engineering team made updates and now they are not including those transactions in our total wallet balance." "Due to the abrupt BTC miner fee spike last week, there were a pile up of stuck low fee transactions which causes a delay in our indexer to processed and indexed transactions."

Scenario: balance-balances-discrepancy-wallet#frozen-unspents-btc

Trigger: BTC cold wallet shows a total balance but available/spendable balance is zero or significantly lower, and the Unspents tab reveals frozen unspents.

Signals: BTC, frozen unspent, spendable zero, available balance zero, cold wallet, unspents tab

Steps:

  1. Check the wallet's Unspents tab in the UI or via bga w <walletID> unspents to identify any frozen unspents.
  2. Advise the customer that frozen unspents are not spendable and can be unfrozen from the Unspents tab in the wallet UI.
  3. Once unfrozen, the spendable balance should update to include those unspents.

Notes: Customers may have frozen unspents intentionally or unknowingly. This is a self-service resolution.

"The first unspent of 99.99777872 is frozen, which is why it is not spendable/withdraw-able. You should be able to see the same in the Unspents tab of the wallet. If required, you can unfreeze the unspent in the same tab to make it spendable."

Scenario: balance-balances-discrepancy-wallet#indexer-sync-issue-engineering

Trigger: Wallet balance in BitGo UI or API shows zero or incorrect value despite confirmed on-chain transactions, and the issue cannot be resolved by flushing, consolidation, or unfreezing — typically requires engineering intervention to resync or fix the indexer.

Signals: balance zero, deposit not reflected, confirmed transaction missing, indexer, JIRA, engineering escalation, resync

Steps:

  1. Verify the transaction is confirmed on-chain via the block explorer.
  2. Check in admin tooling whether the transfer record exists and is marked as confirmed.
  3. Attempt to resync addresses: bga admin resyncAddresses for the wallet.
  4. If the balance still does not update, create a JIRA ticket for the engineering team with the wallet ID, affected transaction IDs, and diagnostic findings.
  5. Inform the customer that the issue has been escalated to engineering and provide updates as they become available.

Notes: This scenario covers cases where the BitGo indexer has failed to properly index a transaction or update the wallet state. It has been observed across multiple chains (ETH, SOL, NEAR, DOT, STX). Resolution typically requires a server-side fix deployed by engineering. The customer's funds are safe on-chain even if the UI/API balance is incorrect.

"resync'd addresses, still not showing the coins in the wallet balance... I need to create a jira for this" "Our team were able to locate the root cause and are working on a fix. The fix should be deployed and live by 11/4."

Scenario: balance-balances-discrepancy-wallet#report-discrepancy

Trigger: Holdings report, wallet report, or Looker report shows different balances compared to the UI or on-chain, including missing fiat columns, truncated wallet IDs, incorrect token balances, or stale data.

Signals: holdings report, Looker report, wallet report, report discrepancy, reporting tool, balance mismatch, fiat currency missing, wallet ID 24 characters

Steps:

  1. Confirm which report the customer is using (Holdings by Account, Holdings by Address, Looker report, or wallet transaction report).
  2. Note that there is a general latency of approximately 2–3 hours between the UI balance and the report balance. Advise the customer to re-generate the report after waiting.
  3. If the discrepancy persists beyond the latency window, gather the wallet IDs, report timestamps, and specific balance values that differ.
  4. Check if there are known reporting tool issues or migrations (e.g., older reporting tool producing 24-character wallet IDs instead of 32).
  5. Escalate to the data/reporting team or engineering via internal channels (Slack #prod-ops or JIRA) with the report details and customer-provided comparison data.
  6. If the reporting tool issue is known and a manual workaround is available (e.g., manually augmented reports, Looker reports as interim), provide the workaround to the customer.

Notes: Report discrepancies can stem from: indexer issues affecting TRS Balance, deprecated tokens appearing in reports, staking payouts being sent to forwarder addresses (unsupported scenario causing over-crediting), or reporting tool migrations. The Holdings report may not include fiat balances during certain periods if the report format changed — this is a known engineering issue that requires a fix. Report balances use TRS Balance which can differ from the wallet balance if there are indexing issues.

"The reason for the 24 wallet ID's as opposed to the full 32 character ID's within the Capital Wallet Pty report is due to the fact that we have had to revert back to an older reporting tool whilst we continue to troubleshoot the new Looker report." "Our engineering team fixed the issue, can you please double check again and let us know if you are still seeing any issues?" "The root cause of the report discrepancy is that one of the wallet's forwarders... is used as ETH staking payout addresses. BitGo does not support this scenario and so our indexer does not work accurately under this scenario."

Scenario: balance-balances-discrepancy-wallet#api-balance-format-or-endpoint

Trigger: API returns zero balances, balances in scientific notation, or 404/400 errors when querying balance-related endpoints.

Signals: API, zero balance, scientific notation, 404, 400, maximumSpendable, feeAddressBalance, wallet balances endpoint, CoinUnsupported

Steps:

  1. Verify the customer is using the correct coin ticker in lowercase in the API path (e.g., avaxc not AVAXC).
  2. Verify the customer is calling the correct endpoint and that it is supported for the specified coin. The staked balance endpoint (/balances/staked) is not implemented for all coins — check documentation at https://developers.bitgo.com/.
  3. For the enterprise fee address balance endpoint (/api/v2/{coin}/enterprise/{enterpriseId}/feeAddressBalance), confirm it works against the production domain (https://app.bitgo.com/ or https://app.bitgo-test.com/) rather than only through BitGo Express, as some endpoints may not be proxied correctly through Express.
  4. If the API is returning values in scientific notation (e.g., 7.818930396539131977142e+21 instead of a plain integer string), this is a known bug. Escalate to engineering — the fix is server-side and does not require a BitGo Express update.
  5. For gas tank transaction history, there is no API path for retrieving transactions associated with gas tanks. Advise the customer to reference the fee address on the appropriate block explorer (e.g., Etherscan).

Notes: Coin tickers must always be passed in lowercase in API paths. The CoinUnsupported error typically means the coin ticker is incorrect or the coin is no longer supported (e.g., BSV). Scientific notation in balance responses was a server-side bug affecting AVAXC that was fixed without requiring a client-side update.

"A fix had been tested and deployed in production today to fix this maximum spendable balance issue for AVAX... Fix was at our end and so BitGo Express update is not required." "There is no path for that. Your team will need to reference the fee address within Etherscan for that record." "The staked balance endpoint... 'endpoint not implemented for this coin: avaxc'... When passing the cointype, it will need to be lowercase."

Scenario: balance-balances-discrepancy-wallet#deprecated-unsupported-coin

Trigger: Balance shows zero or the coin cannot be accessed because the coin has been deprecated or is no longer supported on BitGo (e.g., BSV, EOS ERC-20 token).

Signals: BSV, EOS, deprecated, CoinUnsupported, balance zero, coin removed, unsupported

Steps:

  1. Confirm whether the coin is still supported on BitGo. BSV is no longer supported; EOS ERC-20 is a deprecated token.
  2. For deprecated tokens appearing in the UI or reports, escalate to engineering to have them removed from the wallet display and reports.
  3. For BSV, advise the customer that BitGo no longer supports BSV wallets, the block explorer API used does not support BSV, and recovery is not available.
  4. If the deprecated coin is causing UI loading errors (e.g., pending approvals failing to load), engineering can remove it from the UI.

Notes: BSV support was dropped because the block sync and explorer APIs no longer support BSV. The coin was removed from the UI to prevent errors.

Scenario: balance-balances-discrepancy-wallet#locked-balance-not-showing

Trigger: Wallet has locked tokens (e.g., from a Token Management platform) but the locked balance line item does not appear in the BitGo UI.

Signals: locked balance, SEI, Token Management, locked line item, UI missing

Steps:

  1. Confirm that the locked balance is shown in the Token Management platform but not in the BitGo wallet UI.
  2. Verify that the available balance reconciles correctly with the total balance minus the locked amount.
  3. Escalate to engineering — this is a known UI display bug. A fix should be tracked via an internal JIRA ticket.
  4. Inform the customer of the expected fix timeline if available.

Notes: This was observed for SEI wallets where locked tokens were not displayed as a separate line item in the BitGo UI, even though the Token Management platform showed them correctly.

Scenario: balance-balances-discrepancy-wallet#settlement-pending-go-account

Trigger: Customer recently traded on BitGo Go and the spendable balance shows zero or less than expected because traded funds have not yet settled.

Signals: spendable zero, Go account, traded funds, settlement, daily settlement, withdrawal blocked

Steps:

  1. Confirm the customer recently executed a trade on BitGo Go.
  2. Advise the customer that traded funds are only available for withdrawal after daily settlement, which begins at noon ET every weekday (excluding US public holidays) and can last up to 4 hours.
  3. Ask the customer to retry the withdrawal after settlement is complete.

Notes: This applies specifically to BitGo Go trading accounts, not standard custody or hot wallets.

"Please note that traded funds will only be available for withdrawal after daily settlement which begins at noon ET every weekday (excluding US public holiday) and can last for up to 4 hours."

Scenario: balance-balances-discrepancy-wallet#cross-chain-deposit-gas-tank

Trigger: Customer sent funds to the wrong network's gas tank address (e.g., ETH sent to an AVAXC gas tank address), and the gas tank balance is not reflecting the deposit.

Signals: gas tank, wrong network, cross-chain, AVAXC gas tank, ETH gas tank, funds not recoverable

Steps:

  1. Verify the transaction on the block explorer to confirm funds were sent to the wrong chain's gas tank address.
  2. Confirm the customer's correct gas tank address for the intended network.
  3. Escalate to engineering to determine if recovery is possible. Note that historically, BitGo did not support recovery from gas tanks, though this may change over time.
  4. If recovery is possible, request a recovery destination address from the customer on the correct network. The recovered asset type will be the asset originally sent (e.g., ETH), not a different asset.
  5. If recovery is not possible, inform the customer and advise them to ensure transactions are sent on the correct chain going forward.

Notes: Recovery from gas tanks was historically not supported. In some cases, engineering has later developed the capability. Always check with engineering for the current state of gas tank recovery support.

Scenario: balance-balances-discrepancy-wallet#v1-btc-wallet

Trigger: A v1btc wallet balance is not visible in the modern BitGo UI.

Signals: v1btc, v1 wallet, balance missing, legacy wallet, upgrade wallet

Steps:

  1. Verify the wallet type is v1btc via admin tooling (bga coin v1btc ; bga w <walletID>).
  2. If the wallet is not associated with the enterprise, add it using bga ent addwallet <walletAddress>.
  3. Spoof the user to verify if the wallet and balance are now visible in the UI.
  4. Note that v1 wallets may take a long time to load in the UI and may display a message about v1 wallets needing attention.
  5. Advise the customer they can upgrade the wallet or withdraw funds to a v2 wallet.
  6. If the balance still does not display, escalate to engineering via JIRA.

Notes: v1btc wallets are legacy wallets that may not render properly in the current UI. The upgrade path is available through the UI's Resource Center link.

Related