Scoutinternal

Testnet Environment: Access, Configuration, and Coin Support Issues

Testnet Environment: Access, Configuration, and Coin Support Issues

Problem

Customers integrating with BitGo's testnet environment encounter a range of issues including inability to log in, missing coin/token support (e.g., HTETH, TKAIA, GTETH), wallets stuck in pending chain initialization, and enterprises missing required licenses to create testnet wallets. These issues affect customers using the BitGo test environment at app.bitgo-test.com for integration development and testing across multiple chains including Ethereum testnets (Holesky, Hoodi), Kaia testnet, and Bitcoin testnet.

Diagnostics

  • Verify the testnet URL: Confirm the customer is using https://app.bitgo-test.com (not the mainnet URL https://app.bitgo.com). Testnet and mainnet are separate environments with separate accounts.
  • Check enterprise type: Determine whether the customer created a "starter enterprise" versus a full enterprise account. Starter enterprises may lack the ability to create wallets. Confirm they signed up via https://developers.bitgo.com/sign-up.
  • Check enterprise coin licenses: Spoof the customer's enterprise and verify which coin licenses are enabled. Compare against a known-working enterprise if possible. Missing licenses will prevent specific testnet coin wallets (e.g., HTETH) from appearing as options.
  • Check wallet initialization status: For EVM-based testnet coins (TKAIA, HTETH, TETH, etc.), verify whether the wallet is still "pending ChainInitialization." A wallet in this state requires the first deposit to go to the base address, not a forwarding or receive address.
  • Verify deposit address: Confirm the customer sent testnet funds to the correct wallet base address. Deposits to non-base addresses before initialization will not be credited.
  • Check coin testnet support depth: Not all coins have full testnet support. Verify whether the testnet variant (e.g., TKAIA) appears in BitGo's contract constants page. If not listed, escalate to engineering.
  • Check for account lockout / throttling: If the customer reports inability to log in, check whether their account is throttled or locked on testnet. Verify credentials exist in the testnet environment (separate from mainnet).
  • Review status page: Check https://status.bitgo.com/ for any ongoing testnet outages or scheduled maintenance (503 errors have been reported historically).

Resolution

Scenario: testnet-mainnet-eth-net#missing-enterprise-licenses

Trigger: Customer cannot see or create wallets for a specific testnet coin (e.g., HTETH) while other enterprises can.

Signals: HTETH, testnet wallet creation, coin not available, missing coin option, enterprise licenses, Holesky

Steps:

  1. Ask the customer which specific testnet coin they are trying to create a wallet for (e.g., HTETH for Holesky ETH).
  2. Spoof the customer's enterprise in the admin tool and attempt to create the same wallet type.
  3. Compare the coin licenses on the affected enterprise against a known-working enterprise that can create the wallet.
  4. If licenses are missing, add the required coin licenses to the customer's enterprise.
  5. Verify by spoofing again that the wallet type can now be created.
  6. Inform the customer the issue is resolved and ask them to confirm.

Notes: This commonly occurs when a new testnet enterprise is provisioned without the full set of coin licenses. The customer will see the coin missing from the wallet creation dropdown.

"I moved forward with adding the missing licenses to the affected user's Enterprise. Spoofing them, I can see the HTETH wallets can now be created." (ticket #262209)

Scenario: testnet-mainnet-eth-net#wallet-pending-chain-initialization

Trigger: Customer deposited testnet funds but balance does not appear; wallet is still pending ChainInitialization.

Signals: TKAIA, TETH, pending ChainInitialization, deposit not showing, base address, wallet initialization, Kaia testnet

Steps:

  1. Check the wallet status in the admin tool. Confirm whether it shows "pending ChainInitialization."
  2. Identify the wallet's base address (this is the primary address shown in the wallet details, not a forwarding/receive address).
  3. Verify whether the customer's deposit transaction was sent to the base address or to a different address.
  4. If the deposit went to the wrong address, instruct the customer to send testnet funds to the wallet base address to initialize the wallet.
  5. Once the wallet is initialized, prior deposits to non-base addresses should also appear. If they do not, escalate to engineering to investigate credit of earlier transactions.
  6. If the deposit was sent to the correct base address but still not credited, escalate to engineering — there may be a backend indexing issue for that specific testnet coin.

Notes: This applies to EVM-based testnet coins such as TKAIA (Kaia testnet). Engineering may need to investigate whether full testnet support exists for newer coins. Check the contract constants page for testnet coin entries.

"We see the TKAIA wallet in question is still pending ChainInitialization and so, TKAIA must be sent to the wallet base address to initialise the wallet." (ticket #256573)

"I am not seeing TKAIA in our contract constants page reflecting testnet support." (ticket #256573)

Scenario: testnet-mainnet-eth-net#starter-enterprise-no-wallets

Trigger: Customer signed up for testnet but cannot find prefunded wallets or create new wallets; they created a "starter enterprise" instead of a full enterprise account.

Signals: starter enterprise, no wallets, testnet signup, prefunded wallets missing, cannot create wallet, developers.bitgo.com

Steps:

  1. Confirm how the customer signed up. Ask if they used https://developers.bitgo.com/sign-up.
  2. Check the enterprise type in the admin tool. If it is a "starter enterprise," it will not have full wallet creation capabilities or prefunded wallets.
  3. Advise the customer to have a teammate use a new email address to sign up at https://developers.bitgo.com/sign-up to create a proper enterprise account.
  4. Once the new enterprise is created, the original user can be invited to join it.
  5. Provide the guide for creating a testnet enterprise if needed.

Notes: Testnet accounts are completely separate from mainnet accounts. Customers need a distinct email and must sign up specifically for the testnet environment. The testnet forgot-password flow is at https://app.bitgo-test.com/web/auth/forgot-password/recover-password.

"Can you confirm that you followed this link https://developers.bitgo.com/sign-up? looks like the enterprise created is a starter enterprise and not an enterprise account thus the wallets were not created. Are you able to ask one of the teammates to use a new email to sign up to create the enterprise and then invite you?" (ticket #262245)

Scenario: testnet-mainnet-eth-net#testnet-login-issues

Trigger: Customer reports they cannot log in to the testnet environment, encountering errors or lockouts.

Signals: testnet login, cannot log in, throttling, account locked, bitgo-test.com, forgot password

Steps:

  1. Confirm the customer is using the correct testnet URL: https://app.bitgo-test.com.
  2. Verify that the customer has a separate testnet account (testnet credentials are independent from mainnet).
  3. If the customer forgot their password, direct them to the testnet password recovery flow: https://app.bitgo-test.com/web/auth/forgot-password/recover-password.
  4. If the account appears throttled or locked, check for rate limiting in the admin tool and reset if appropriate.
  5. If the customer has never created a testnet account, guide them to sign up at https://developers.bitgo.com/sign-up using a new email.
  6. Check https://status.bitgo.com/ for any active testnet outages (503 errors have been reported during outages).

Notes: Testnet environment outages (503 errors) have occurred historically and are tracked on the status page. If multiple customers report testnet login failures simultaneously, check for a platform-wide issue before troubleshooting individual accounts.

Scenario: testnet-mainnet-eth-net#testnet-coin-not-fully-supported

Trigger: A newer coin's testnet variant does not appear to function correctly, or engineering confirms limited testnet support.

Signals: coin not supported, testnet support, engineering escalation, contract constants, new coin, TKAIA, GTETH

Steps:

  1. Check the BitGo contract constants page to verify whether the testnet variant of the coin is listed.
  2. If the coin is not listed, inform the customer that testnet support may be limited or not yet available for that specific coin.
  3. Escalate to engineering via the appropriate Slack channel (e.g., #support-engineering) to confirm the depth of testnet support for the coin.
  4. If engineering confirms limited support, communicate the current status to the customer and provide an estimated timeline if available.
  5. If engineering can resolve the issue (e.g., fix indexing or balance display), monitor for confirmation and update the customer.

Notes: Not all coins that are supported on mainnet have equivalent full testnet support. Ethereum testnet variants have changed over time (GTETH for Goerli, HTETH for Holesky, and Hoodi may follow). Verify which testnet variant is currently active.

"We are checking with our engineering team to see how deep the support for this coin goes within our Testnet environment." (ticket #256573)

"We have fixed this issue and Kaia Testnet balance for the wallet should show correct numbers now." (ticket #256573)

Related