Scoutinternal

USDT / TRC-20 Token Consolidation and TRX Wallet Balance Issues on Tron

USDT / TRC-20 Token Consolidation and TRX Wallet Balance Issues on Tron

Problem

Customers using BitGo TRX wallets frequently encounter issues sending or withdrawing TRC-20 tokens (primarily USDT, also USDC). The most common symptom is an error stating "The amount you are trying to send is not available. You may need to consolidate and then retry" or an InsufficientBalance error despite the on-chain balance appearing sufficient. Related problems include negative or incorrect spendable balances shown by the BitGo platform, failed consolidation attempts returning "Failed to create any transactions" or "No funds to consolidate among the checked addresses", and wallets stuck in "Pending Chain Initialization". These issues affect TRX wallets holding TRC-20 tokens and occasionally other account-based chains (SOL, DOT) with similar consolidation models.

Diagnostics

  • Identify the wallet: Obtain the wallet ID and root address. Look up the wallet using internal admin tooling (bga w <walletId> or bga w <rootAddress>). Note the Balance, Confirmed, Spendable, and TRS Balance fields. Check for discrepancies (e.g., negative Spendable, or Spendable much lower than Balance).
  • Compare with on-chain data: Search the root address and each receive address on https://tronscan.org/ to verify the actual on-chain TRX and TRC-20 token balances. Note whether each address is activated (has ever received TRX).
  • Check wallet initialization status: Look for "pendingChainInitialization": true in the wallet's coinSpecific data. If true, the wallet has not been initialized on-chain.
  • Check receive address activation: Use bga wallet addresses to list all addresses. Cross-reference each address on Tronscan to see if it is activated (has received at least 1 TRX) and whether it holds TRC-20 tokens with insufficient TRX for consolidation fees.
  • Check for stuck/failed transactions: Look for transactions stuck in signed or attempted state in the send queue (bga sendq). Check for broadcast errors such as SIGERROR Validate signature error or insufficient balance.
  • Check account type: Confirm whether the enterprise is an Institutional/paid account. TRX wallets on production are only fully supported for business/paid accounts. Free/starter accounts cannot create TRX wallets via UI and may not be able to consolidate successfully.
  • Check token type in API calls: Confirm the customer is using the correct coin identifier (e.g., trx:usdt for USDT consolidation, not just trx). Consolidating TRX alone does not consolidate TRC-20 tokens.
  • Check Express version: Ask the customer for their bitgoJsVersion and bitgoExpressVersion. Older versions may lack support for certain coins or tokens.

Resolution

Scenario: usdt-trx-tron-consolidation#receive-address-not-activated-or-underfunded

Trigger: Customer cannot consolidate TRC-20 tokens (USDT/USDC); receive addresses holding tokens have zero or insufficient TRX, or are not activated on-chain.

Signals: consolidate, USDT, TRC20, not activated, insufficient balance, Failed to create any transactions, No funds to consolidate, consolidation fee, TRX needed

Steps:

  1. List all wallet receive addresses using bga wallet addresses or the API endpoint GET /api/v2/trx/wallet/{walletId}/addresses?includeBalances=true.
  2. For each receive address holding a TRC-20 token balance, check on https://tronscan.org/ whether the address is activated. An unactivated address shows no transaction history.
  3. Instruct the customer to activate each unactivated address by sending it approximately 3 TRX (at minimum 1 TRX) from an external source. TRC-20 tokens cannot activate an address.
  4. After activation, instruct the customer to fund each receive address that holds TRC-20 tokens with enough TRX to cover the consolidation fee. Recommend 50–100 TRX per address. Consolidation fees for TRC-20 tokens typically range from 10–15 TRX but can reach as high as 30 TRX. The platform requires approximately 100 TRX on the address for the consolidation request to proceed.
  5. Ensure the root address also has sufficient TRX (at least 100 TRX).
  6. Once TRX is confirmed on-chain on the receive addresses, the customer should use the Consolidate Funds button in the wallet Overview tab (for native TRX and TRC-20 via UI) or the API endpoint. When consolidating TRC-20 tokens, the customer must select the specific token (e.g., USDT) rather than TRX.
  7. A successful consolidation creates two transactions per address: an internal movement of the TRC-20 token reflecting 0 TRX moved, and a TRX fee transaction. Both must show as confirmed before consolidated funds are usable.
  8. Warn the customer: if the address does not have enough TRX to cover the consolidation fee, the TRX will still be consumed and the consolidation will fail.

Notes: - Each consolidation requires approximately 100 TRX on the address, not just the first time. This is a maximum fee approach to avoid burning fees on-chain if consolidation fails.

  • Consolidating TRX via the UI Consolidate Funds button does NOT consolidate TRC-20 tokens. The customer must explicitly choose the token.
  • The Tron Gas Tank feature can be enabled to auto-fund wallet addresses with TRX when they receive deposits, but the receive address must have been previously activated before receiving funds. Contact the customer's account team or sales to enable the Gas Tank on the enterprise. Even with Gas Tank enabled, consolidation must still be initiated manually or via API.

"For bypassing OTP, you will need to configure Lifetime Spending Limits on your API Access Token for any coin/token the API key will be using/spending. Of note, consolidation of TRC20 tokens is limited to Institutional Enterprises." "When you encounter consolidation issues such as this, your team will want to perform the following: Review each receive address on the wallet to see if it holds a coin balance and if the address is initialized. This can be done by searching the address at the following Tron site: https://tronscan.org/#/" "That is correct, for every consolidation the address will need to have a 100 TRX otherwise the consolidation request will fail."

Scenario: usdt-trx-tron-consolidation#negative-or-incorrect-spendable-balance

Trigger: The BitGo platform shows a negative or incorrect spendable balance for a TRX wallet, even though on-chain balance on Tronscan is correct.

Signals: negative spendableBalance, wrong balance, insufficient balance, balance mismatch, -92099990, spendableBalanceString negative

Steps:

  1. Confirm the discrepancy by comparing the wallet's spendableBalance from the BitGo API (GET /api/v2/trx/wallet/{walletId}) with the on-chain balance on https://tronscan.org/.
  2. Run the following internal indexer commands against the wallet's root address to re-synchronize the balance:
    • bga indexer execute CONSOLIDATE_ADDRESS_STATE <rootAddress>
    • bga indexer execute CONSOLIDATE_WALLET_STATE <rootAddress>
  3. If there are specific transactions that appear confirmed on-chain but stuck as signed or pending on the BitGo platform, also run:
    • bga indexer execute INDEX_TRANSACTION <txid>
    • bga indexer rebroadcast <txid> (if needed)
  4. After running the commands, verify the wallet balance is corrected: Balance, Confirmed, and Spendable should match.
  5. Inform the customer that the balance has been corrected and ask them to verify on their end.

Notes: - This issue has been observed on multiple customer wallets and is typically caused by the TRX indexer failing to properly update after transactions confirm on-chain.

  • Engineering has deployed fixes for the TRX indexer in the past, but the issue can recur.

"balance corrected after running below cmds to consolidate wallet address/wallet: bga indexer execute CONSOLIDATE_ADDRESS_STATE TXKDgqFnr3QEs8teGYdZHGuyHQrUntu92E / bga indexer execute CONSOLIDATE_WALLET_STATE TXKDgqFnr3QEs8teGYdZHGuyHQrUntu92E" "I fixed the balance for the reported wallet. I will check with our engineering team regarding if other wallets have the same issue."

Scenario: usdt-trx-tron-consolidation#pending-chain-initialization

Trigger: A TRX wallet shows "Pending Chain Initialization" status and cannot be used for transactions.

Signals: Pending Chain Initialization, pendingChainInitialization, wallet activation, 100 TRX, wallet not active

Steps:

  1. Check the wallet's coinSpecific.pendingChainInitialization field. If true, the wallet has not been initialized on-chain.
  2. Instruct the customer to send 100 TRX to the wallet's root address to initialize the wallet on-chain. This is the minimumFunding amount (100000000 sun).
  3. Once the 100 TRX deposit is confirmed on-chain, the wallet status should change to active.
  4. If the wallet remains in pending state after the TRX deposit is confirmed, check for creationFailure entries in the wallet's coinSpecific data. These indicate the wallet activation transaction failed on-chain.
  5. If the activation transaction is stuck in the send queue with a SIGERROR or similar error, update the send queue entry to done and set pendingChainInitialization to false using internal tooling (e.g., bga sendq v2update <id> --state done).
  6. Confirm the wallet is now active and inform the customer.

Notes: - The 100 TRX initialization deposit is separate from the TRX needed for transaction fees or consolidation.

  • On testnet (TTRX), the same initialization process applies using testnet TRX.
  • Known JIRA reference for activation failures: EA-576.

"Once you have your TRX wallet created, you will need to create the account on-chain by sending it 100 TRX. Once the 100 TRX is deposited and confirm on chain your wallet is activated."

Scenario: usdt-trx-tron-consolidation#consolidation-api-requires-wallet-passphrase

Trigger: Customer receives a wallet_passphrase_incorrect error or an empty failure object when calling the consolidation API without providing walletPassphrase.

Signals: wallet_passphrase_incorrect, All transactions failed, walletPassphrase, consolidateAccount, API consolidation error

Steps:

  1. Confirm the customer is calling the BitGo Express consolidation endpoint: POST /api/v2/{coin}/wallet/{walletId}/consolidateAccount.
  2. The walletPassphrase parameter is required for hot wallets when using this endpoint. Instruct the customer to include it in the request body:
    {
  "walletPassphrase": "string",
  "consolidateAddresses": ["address1", "address2"]
}
  3. For consolidating TRC-20 tokens specifically (e.g., USDT), the coin type must be trx:usdt (not trx).
  4. Ensure the customer is running the latest version of BitGo Express. Older versions may not properly surface the error or may lack support. Latest versions available at: https://hub.docker.com/r/bitgo/express/tags
  5. To bypass OTP requirements, the customer should configure Lifetime Spending Limits on their API Access Token for the relevant coin/token.

Notes: - The developer documentation at https://developers.bitgo.com/api/express.wallet.consolidateAccount previously did not list walletPassphrase as a required parameter. BitGo has acknowledged this and planned to update the docs.

  • Consolidation of TRC20 tokens is limited to Institutional Enterprises.
  • For custody (cold) wallets, the consolidation flow uses build → sign → send endpoints instead.

"Apologies, we have checked that the walletPassphrase parameter is required for consolidate call on hot wallets. We will be updating our docs on this." "To consolidate, the following Bitgo Express endpoint can be used as a single call: POST api/v2/{coin}/wallet/{walletId}/consolidateAccount BODY { "walletPassphrase": string "consolidateAddresses": array[string] // Optional }"

Scenario: usdt-trx-tron-consolidation#stuck-transactions-on-trx

Trigger: TRX transactions show as pending/signed on the BitGo platform but are confirmed on-chain, or transactions are stuck in the send queue with broadcast errors.

Signals: stuck transaction, pending, signed, confirmed on chain, SIGERROR, send queue, reindex, INDEX_TRANSACTION

Steps:

  1. Check the transaction status using internal tooling. Look for the transaction in the send queue and compare with on-chain status on Tronscan.
  2. If the transaction is confirmed on-chain but stuck as signed or pending on BitGo, run:
    • bga indexer execute INDEX_TRANSACTION <txid>
    • bga indexer rebroadcast <txid> (if applicable)
  3. If the transaction is stuck in the send queue with a SIGERROR error and confirmed on-chain, update the send queue state to done:
    • bga sendq v2update <id> --state done --comment "confirmed on chain"
  4. Run CONSOLIDATE_WALLET_STATE and CONSOLIDATE_ADDRESS_STATE on the root address to correct the wallet balance after reindexing.
  5. Confirm transactions now show as confirmed and balances are correct. Inform the customer.

Notes: - This has been observed as a recurring issue related to the TRX indexer notification delay. Engineering has deployed fixes previously.

  • For cold wallet consolidation stuck with SIGERROR, the issue may have been fixed in the latest version of WRW and OVC. Ask the customer to update.

"txns stuck in signed but confirmed on chain... all confirmed after reindexing" "Our team has informed this have been fixed latest version of WRW and OVC."

Scenario: usdt-trx-tron-consolidation#trc20-consolidation-only-via-api-for-custody

Trigger: Customer with a custodial (cold) wallet cannot find a consolidation option in the UI for TRC-20 tokens, or the UI only supports native TRX consolidation.

Signals: custodial wallet, cold wallet, consolidation UI, API only, custody, TRC20 consolidation not in GUI

Steps:

  1. Inform the customer that consolidation of Tron tokens (TRC-20) for custodial wallets is API only. The UI Consolidate Funds button currently only supports consolidation for native TRX, not TRX tokens, for some wallet types.
  2. Direct the customer to the consolidation API documentation: https://developers.bitgo.com/api/v2.wallet.consolidateaccount.build
  3. For custody wallets, the flow is:
    • Build the consolidation transaction: POST /api/v2/{coin}/wallet/{walletId}/consolidateAccount/build
    • Sign the transaction: POST /api/v2/{coin}/wallet/{walletId}/sign (or via Express express.wallet.signtx)
    • Send the half-signed transaction: POST /api/v2/{coin}/wallet/{walletId}/tx/send
  4. The customer must have BitGo Express installed and configured. Direct them to:
  5. Each address needs to be initialized with 1 TRX and funded with 50–100 TRX to cover consolidation fees. The base address must also have enough TRX.

Notes: - The developer documentation at https://developers.bitgo.com/coins/TRON provides Tron-specific guidance.

  • Consolidation calls for each asset (TRX vs. TRX:USDT) are separate API calls and separate transactions.

"There is no possibility to consolidate Tron tokens in the GUI. This is for the native asset only." "walletPassphrase is the wallet password. When a consolidation is done, yes funds move from the accounts at the sub addresses to the account at the main address. You can then spend from that base address."

Scenario: usdt-trx-tron-consolidation#token-wallet-creation-use-base-coin

Trigger: Customer tries to create a separate wallet for a token (e.g., BSC:USDT, ETH:USDT) and cannot find the token as a wallet creation option.

Signals: create wallet, BSC:USDT, token wallet, ERC20, TRC20, base coin, cannot create

Steps:

  1. Explain to the customer that on the BitGo platform, wallets are created for the base coin only (e.g., TRX, ETH, BSC, SOL). Tokens (USDT, USDC, etc.) are received on the same addresses as the base coin.
  2. For TRC-20 tokens: create a TRX wallet. USDT and USDC will be receivable on the same TRX addresses.
  3. For ERC-20 tokens: create an ETH wallet. USDT and USDC will be receivable on the same ETH addresses.
  4. For BEP-20 tokens: create a BSC wallet. BSC:USDT will be receivable on BSC addresses.
  5. For SPL tokens (Solana): create a SOL wallet. SOL:USDT and SOL:USDC are receivable on SOL addresses. The customer should enable the specific token under the wallet's Settings > Token Enablement section.
  6. The customer may need to fund the wallet with the base coin (e.g., ETH for gas, TRX for fees) before tokens can be sent.

Notes: - For testnet ERC-20 tokens, the supported list is at: https://developers.bitgo.com/coins/test-ethereum-terc20-tokens

  • BitGo does not provide testnet USDT (TUSDT) tokens. Customers should obtain test tokens from external faucets if available.
  • TRX wallets on production are only available for business/paid (Institutional Enterprise) accounts.

"You want to create a BSC wallet. Once that is done, the BSC:USDT can be sent to those addresses. On our platform, we only allow the creation of wallets for the base coin (BSC). Tokens of base coins are received on the same addresses."

Scenario: usdt-trx-tron-consolidation#ui-consolidation-batch-scan-no-funds-message

Trigger: Customer clicks Consolidate Funds in the UI and receives "No funds to consolidate among the checked addresses. Please try again to check remaining addresses."

Signals: ApiResponseError, No funds to consolidate among the checked addresses, UI consolidation, retry

Steps:

  1. Explain that the consolidation from the UI scans addresses in batches. The message indicates that no balances were found in the current batch scanned.
  2. Instruct the customer to click Consolidate Funds again to check the remaining addresses. Multiple attempts may be needed for wallets with many addresses.
  3. If repeated attempts continue to show no funds, verify that the receive addresses are activated and funded with sufficient TRX (see scenario on address activation).

Notes: - This is expected behavior for wallets with a large number of addresses where only some hold balances.

"The consolidation from UI scans addresses in batches, the msg you saw just means that no balances were found in the current batch scanned, please try to consolidate again."

Scenario: usdt-trx-tron-consolidation#free-account-trx-wallet-limitations

Trigger: Customer on a free/starter account created a TRX wallet via API but cannot consolidate or withdraw TRC-20 tokens.

Signals: free account, starter, Pay As You Go, cannot consolidate, TRX wallet not available

Steps:

  1. Confirm the customer's account tier. TRX wallets are not available for free accounts and cannot be created via the UI for free-tier users.
  2. Inform the customer that even though the wallet may have been created via API, consolidation and withdrawal of TRC-20 tokens will not work correctly on a free account.
  3. Advise the customer not to send additional funds to the wallet, as they will not be able to consolidate or withdraw without upgrading.
  4. Explain the TRC-20 consolidation requirements: each receive address needs activation (1 TRX) and funding (50–100 TRX) for consolidation fees, plus the base address needs sufficient TRX. Without an upgraded account, these operations are not supported.
  5. Direct the customer to https://www.bitgo.com/connect-with-us to inquire about upgrading to an Institutional Enterprise account.

Notes: - The 0.25% fee applies to Pay As You Go/Starter accounts and is non-negotiable.

"Please note that TRX wallets are not available for free accounts thus you are not able to create one via UI, please hold on adding any funds to your wallet."

Related