Scoutinternal

Testnet Wallet Issues: Creation, Transactions, and Coin Visibility (TBTC, TETH, TARBETH, and Others)

Testnet Wallet Issues: Creation, Transactions, and Coin Visibility (TBTC, TETH, TARBETH, and Others)

Problem

Customers using the BitGo testnet environment (https://app.bitgo-test.com/) encounter a range of issues including: inability to create wallets for specific testnet coins (e.g., TARBETH, HTETH), transaction failures or spinning loading wheels when sending TBTC, incorrect or zero balances on testnet wallets, certain testnet coins not appearing in the wallet creation list, and production wallets unexpectedly displaying as testnet (TBTC) wallets. These issues span multiple testnet coin types including TBTC, TETH/GTETH/HTETH, TSTX, and TARBETH.

Diagnostics

  • Identify the testnet environment and coin: Confirm the customer is using https://app.bitgo-test.com/ and clarify which testnet coin they are working with (TBTC, HTETH, GTETH, TARBETH, TSTX, etc.).
  • Check account type: Determine whether the customer's account is a BitGo Trust account or a BitGo Inc account. BitGo Inc accounts may not have access to certain coins (e.g., ETH/HTETH). Check the enterprise pricing plan — starter plan enterprises may lack access to specific testnet coins like TARBETH.
  • Check enterprise association: Verify whether the user has an enterprise (organization) created in testnet. Some testnet coins require an enterprise to create wallets.
  • Spoof the account: Use account spoofing to replicate what the customer sees in the UI. Confirm whether the coin type appears in the wallet creation list and whether balances display correctly.
  • Check wallet type (v1 vs v2): If a customer reports their production BTC wallet suddenly shows as "Testnet Bitcoin Self Custody" (TBTC), check whether they have v1BTC wallets. This was a known UI bug affecting users with v1btc wallets.
  • Verify transaction on-chain: For balance discrepancies, check whether the referenced transaction actually sent funds to the customer's wallet address. Use a testnet block explorer (e.g., https://mempool.space/testnet/) to confirm the recipient addresses in the transaction.
  • Check indexer/backend health: For address generation failures or transactions not appearing, check internal Slack channels (e.g., BTC OnCall, notify-btc) and Grafana for indexer issues or stuck services.
  • Review error messages and error IDs: Collect the exact error message and ErrorID from the customer. Look up the ErrorID in Grafana logs to identify the specific API path and root cause (e.g., "address type not enabled for [WALLET_ID]" on path /api/v2/tbtc/wallet/[WALLET_ID]/tx/build).
  • Confirm SDK version: If the customer uses the BitGo SDK via API, ask which version they are running. Some transaction build errors on TBTC required an SDK update to resolve.

Resolution

Scenario: testnet-tbtc-teth-wallets#coin-not-visible-account-type

Trigger: Customer cannot see a testnet coin (e.g., HTETH, TARBETH) in the wallet creation list, and the root cause is their account type or enterprise plan.

Signals: wallet creation, coin not visible, HTETH, TARBETH, TETH, starter plan, BitGo Inc, BitGo Trust, enterprise, testnet coin missing

Steps:

  1. Confirm which testnet coin the customer is trying to create (e.g., HTETH, TARBETH).
  2. Check the customer's account type (BitGo Trust vs. BitGo Inc) and enterprise pricing plan (e.g., starter plan).
  3. If the account type or plan does not include access to the requested coin, manually enable the coin for the user's account for testing purposes.
  4. Inform the customer and ask them to retry wallet creation.
  5. If Ethereum testnet is the issue, clarify that BitGo has transitioned from Goerli (GTETH) to Holesky (HTETH). The customer should select hteth instead of gteth when creating an Ethereum testnet wallet.

Notes: BitGo Inc accounts may not have access to ETH-related testnet coins by default. Starter plan enterprises do not have access to TARBETH. For testnet/testing purposes, support can manually activate specific coin types for the user's account.

"This is because [the account] is on a BitGo Trust account while [the other account] has a BitGo Inc account which does not has access to ETH. Since this is for testnet, we have enabled Holesky for [the account] now." "The enterprise in question is a starter plan enterprise which do not have access to TARBETH. However, for testing purpose, we have activate this coin type for user account [EMAIL], and this account should now be able to create TARBETH wallet." "You should still be able to create both wallets, we are moving towards holesky ethereum in testnet to replace Goerli. You need to select the coin hteth instead of gteth."

Scenario: testnet-tbtc-teth-wallets#address-type-not-enabled

Trigger: Customer receives error "address type not enabled for [WALLET_ID]" when attempting to send TBTC, occurring in both UI and API.

Signals: address type not enabled, tbtc send error, tx build 400, testnet send failure, ErrorID, SDK update

Steps:

  1. Collect the wallet ID, destination address, the user's email, and the exact ErrorID from the customer.
  2. Confirm whether the issue occurs in both UI and API.
  3. Look up the ErrorID in Grafana (testnet Loki datasource, app=wallet-platform) to confirm the error path (e.g., /api/v2/tbtc/wallet/[WALLET_ID]/tx/build).
  4. Escalate to Engineering (BTC OnCall) with the wallet ID, error log, and destination address details.
  5. Engineering may need to make backend changes to enable the address type for the wallet.
  6. If the fix requires an SDK update, inform the customer that a new SDK version must be downloaded and retried once released.
  7. After Engineering confirms the fix, ask the customer to retry the transaction.

Notes: In at least one case, an initial backend fix resolved the issue partially, but a full resolution required a new SDK release. If the customer is on an older SDK version, the fix may not take effect until they upgrade.

"Error: 'v2.wallet.tx.build 400 error: address type not enabled for [WALLET_ID]' Path: '/api/v2/tbtc/wallet/[WALLET_ID]/tx/build'" "Our engineering team has implemented a fix for this in our SDK which is pending release."

Scenario: testnet-tbtc-teth-wallets#indexer-stuck-address-generation

Trigger: Customer cannot generate a new address on a testnet wallet (e.g., testnet STX), and the root cause is a stuck indexer on BitGo's backend.

Signals: address generation, STX testnet, indexer stuck, cannot generate address, TSTX

Steps:

  1. Confirm the wallet ID and coin type from the customer.
  2. Check internal Slack channels and monitoring tools for reports of a stuck indexer for the relevant testnet coin.
  3. Escalate to Engineering if an indexer issue is confirmed.
  4. Once Engineering resolves the indexer issue, verify by testing address generation on a testnet wallet of the same coin type.
  5. Inform the customer and ask them to retry.

Notes: This was observed specifically on testnet STX but could apply to any coin where the testnet indexer becomes unresponsive.

"indexer seems stuck to me" "We have fixed this issue on our STX testnet. Please try to generate an address again and let us know if you are still not able to."

Scenario: testnet-tbtc-teth-wallets#v1btc-tbtc-display-bug

Trigger: Customer's production account unexpectedly displays "Testnet Bitcoin Self Custody" with TBTC instead of BTC, and the customer has v1BTC wallets.

Signals: Testnet Bitcoin Self Custody, TBTC instead of BTC, v1btc, v1BTC, production wallet, display bug

Steps:

  1. Spoof the customer's account to confirm the UI is displaying TBTC for what should be production BTC wallets.
  2. Check the customer's wallet counts — look for v1btc wallets in the account metadata.
  3. This is a known UI bug where v1btc wallets cause the platform to incorrectly show a TBTC wallet with a mirrored balance. Creating a new wallet will not resolve the issue.
  4. Escalate to Engineering via the appropriate Slack channel (e.g., notify-btc).
  5. Once Engineering deploys a fix, spoof the account again to confirm the correct display.
  6. Inform the customer that the issue is resolved. If they need to recover v1BTC funds, advise them to use the BitGo Wallet Recovery Wizard (https://github.com/BitGo/wallet-recovery-wizard/releases) with the "v1BTC Sweep" option and their wallet Keycard.

Notes: This bug was confirmed and resolved by Engineering. It specifically affected accounts that had legacy v1btc wallets. The TBTC balance shown was a mirror of the v1btc balance, not real testnet coins.

"This is a bug affecting users with v1btc wallets on the platform. Our Engineering team is still investigating the issue. Creating a new wallet likely won't resolve the problem, as the balance on the TBTC wallet appears to mirror the balance on v1btc wallets." "Since this wallet was deprecated a while ago, we recommend trying to sweep the v1btc balance using the BitGo Wallet Recovery Wizard: https://github.com/BitGo/wallet-recovery-wizard/releases. Select the 'v1BTC Sweep' option, and you will need your wallet Keycard to proceed with the process."

Scenario: testnet-tbtc-teth-wallets#testnet-balance-discrepancy

Trigger: Customer reports a zero balance on a testnet wallet despite a transaction showing as confirmed on a block explorer.

Signals: zero balance, testnet balance incorrect, TBTC balance, transaction not showing, mempool

Steps:

  1. Collect the wallet ID and transaction ID from the customer (request plaintext if images are unreadable).
  2. Look up the transaction on a testnet block explorer (e.g., https://mempool.space/testnet/) and verify the actual recipient addresses in the transaction outputs.
  3. Cross-reference the transaction's output addresses with the addresses that belong to the customer's BitGo wallet (check via admin tools or API).
  4. If the transaction did not send to any of the wallet's addresses, inform the customer that the transaction did not use their wallet address as a recipient. Provide the explorer link and the wallet's address list as evidence.
  5. If the transaction did send to a wallet address but the balance is not reflected, escalate to Engineering as a potential indexer or balance tracking issue.

Notes: In observed cases, the root cause was that the on-chain transaction did not actually include the customer's wallet address as a recipient, despite the customer's expectation. Always verify on-chain before escalating.

"While the walletID/address provided does belong to our platform, the transaction did not make use of the address as a recipient. Here is the explorer link for the transaction: https://mempool.space/testnet/tx/fc832d64ca9642a6424f9ea66e97124d519c57c84a2bd99f16b6baef7abc945d"

Scenario: testnet-tbtc-teth-wallets#general-testnet-tx-failure

Trigger: Customer reports testnet transaction failures (spinning wheel, pending status, or generic errors) without a specific error code, and no other scenario matches.

Signals: testnet transaction, spinning wheel, pending, TBTC send failure, transaction failure, loading

Steps:

  1. Ask the customer to confirm: Is this affecting all users or just one? Is it affecting all testnet wallets of that coin type or just one wallet?
  2. Collect the wallet ID, transaction ID (if any), and the user's email address.
  3. Check https://status.bitgo.com/ for any known testnet outages or scheduled maintenance.
  4. Check internal monitoring (Grafana, Slack channels) for related testnet service issues.
  5. If a platform-side issue is identified, escalate to Engineering and inform the customer that the team is investigating.
  6. Follow up once Engineering provides a resolution or the issue clears.
  7. If no response is received from the customer after follow-up, close the ticket with an offer to reopen if needed.

Notes: Many testnet transaction issues are transient and related to testnet infrastructure stability. Always check status.bitgo.com and internal channels first before deep investigation.

Related