Scoutinternal

Address Generation, Validation, and Management on BitGo

Address Generation, Validation, and Management on BitGo

Problem

Customers encounter a range of issues related to blockchain addresses and account (physical/mailing) addresses on the BitGo platform. For blockchain addresses, problems include failures when creating new wallet addresses (e.g., ETH forwarder version errors), address validation errors for various coins (LTC, BTC, XDC, tbtc4), inability to edit address labels (TRX), and requests to flush tokens from specific addresses. For account addresses, customers need to update their personal or enterprise physical/mailing address on file but cannot find a self-service option in the UI. These issues span multiple coins (ETH, LTC, BTC, TRX, XDC, Polygon) and affect both API/SDK and UI workflows.

Diagnostics

  • Blockchain address creation errors: Ask for the exact error message, the coin ticker, the Wallet ID, and whether the customer is using the API, SDK, or UI. Check which version of BitGo Express or the BitGo JS SDK they are running.
  • Address validation errors: Ask for the coin, the address being validated, and the full error response (including requestId). Determine which endpoint they are calling (e.g., /api/v2/:coin/verifyaddress) and which SDK version is in use.
  • Address label editing issues: Confirm the coin (e.g., TRX) and whether the address has been initialized on-chain. Attempt to reproduce in the UI.
  • Token flushing requests: Obtain the Wallet ID, the specific address(es), the token contract address, and any relevant transaction hashes. Check confirmed vs. spendable balance for discrepancies.
  • Physical/mailing address changes: Confirm the customer's identity, enterprise, and whether they are an FTX creditor (who may need to update on the FTX portal first). Determine what documentation they can provide (utility bill, lease, government-issued ID).
  • Identity/liveness verification failures: Check if the customer failed the automated liveness test and needs to be directed to a video call.

Resolution

Scenario: eth-address-addresses-generation#eth-forwarder-version

Trigger: Customer receives an error containing "Cannot create address with forwarder version 1 for this wallet. Choose a higher forwarder version" when creating an ETH wallet address.

Signals: ETH, create address, forwarder version 1, forwarderVersion, Cannot create address, higher forwarder version

Steps:

  1. Ask the customer for the Wallet ID the address is being created on.
  2. Instruct the customer to pass a value of 2 for the parameter forwarderVersion when creating addresses via the API endpoint: https://developers.bitgo.com/api/v2.wallet.newaddress
  3. If the customer then receives the error forwarderVersion has to be an integer between 0 and 1, this indicates their BitGo Express or SDK version is outdated.
  4. Instruct the customer to update to the latest version of BitGo Express (https://hub.docker.com/r/bitgo/express/tags) or the BitGo JS SDK (https://www.npmjs.com/package/bitgo).
  5. After updating, retry address creation with forwarderVersion set to 2.

Notes: This issue applies to ETH and ERC-20 token wallets. The forwarder version 1 limitation is wallet-specific; not all wallets require version 2.

"Your team will need to pass a value of '2' for the parameter 'forwarderVersion' when creating addresses for this wallet using the API: https://developers.bitgo.com/api/v2.wallet.newaddress" (ticket #222148)

"Please insure your team is using the latest version of Bitgo ExpressSDK https://hub.docker.com/r/bitgo/express/tags https://www.npmjs.com/package/bitgo" (ticket #222148)

Scenario: eth-address-addresses-generation#ltc-invalid-address-format

Trigger: Customer receives an InvalidAddress error when validating or withdrawing to an LTC address, with the error message indicating the address could not be parsed.

Signals: LTC, invalid address, could not parse address, Supports bech32, Supports cashAddr, InvalidAddress, P2SH

Steps:

  1. Ask the customer for the LTC address that is failing validation.
  2. Determine the address format. BitGo supports P2SH format for LTC. Certain address formats (e.g., newer bech32 variants) may not be supported.
  3. Advise the customer to convert the address to P2SH format, which BitGo supports. Provide a link to an address converter tool if appropriate.
  4. Retry the withdrawal or validation with the converted P2SH address.

Notes: The error 'invalid address: Error: could not parse address. Supports bech32: true. Supports cashAddr: false' specifically indicates the address format is not recognized by the SDK. Converting to P2SH resolves this.

"Try to use this link to convert address to P2SH which we support." (ticket #206794)

Scenario: eth-address-addresses-generation#xdc-address-prefix

Trigger: Customer reports that the /api/v2/xdc/verifyaddress endpoint returns false for addresses with the xdc prefix but true for the same addresses with a 0x prefix.

Signals: XDC, xdc prefix, 0x prefix, verifyaddress, address format, false, interchangeable

Steps:

  1. Confirm the customer is using the /api/v2/xdc/verifyaddress endpoint.
  2. Explain that currently on the BitGo platform, XDC addresses with the xdc prefix and the 0x prefix are not treated identically. The platform sends funds from xdc.. addresses to 0x... addresses, and this route is the only currently supported method. Sending from 0x... to xdc... is not yet supported.
  3. Escalate to engineering if the customer requires full bidirectional prefix support; this is a known limitation under active development.
  4. Follow up with the customer once engineering provides an update or resolution timeline.

Notes: This is a known platform limitation. Engineering is working on full XDC prefix support. The timeline is not fixed as of the latest ticket evidence.

"Currently for our platform, we send funds from 'xdc..' address to our '0x...'. This route is currently the only supported method. '0x...' to 'xdc...' is not yet supported." (ticket #242972)

Scenario: eth-address-addresses-generation#verify-address-sdk-version

Trigger: Customer receives InvalidAddressDerivationPropertyError when calling verifyAddress via the BitGo JS SDK, but the same address validates successfully via the REST API.

Signals: InvalidAddressDerivationPropertyError, verifyAddress, tbtc4, SDK version, BitGoJS

Steps:

  1. Ask the customer which version of the BitGo JS SDK they are running.
  2. Attempt to reproduce the error by calling the REST API endpoint /api/v2/:coin/verifyaddress with the same coin and address. If the REST API returns valid, the issue is SDK-version-specific.
  3. Instruct the customer to update to the latest version of the BitGo JS SDK (https://www.npmjs.com/package/bitgo).
  4. Retry the verifyAddress call after updating.

Notes: This has been observed with tbtc4 coin on test environments. The REST API may work correctly even when an older SDK version throws InvalidAddressDerivationPropertyError.

"Can you please update to the latest version and try again? We weren't able to reproduce this error calling this endpoint /api/v2/:coin/verifyaddress with coin: tbtc4" (ticket #242750)

Scenario: eth-address-addresses-generation#trx-address-label-edit

Trigger: Customer is unable to edit the label of a newly created TRX address via the UI or API.

Signals: TRX, label, edit, address label, cannot edit, initialized

Steps:

  1. Confirm the coin is TRX and reproduce the issue in the UI if possible.
  2. Explain to the customer that for wallets requiring individual address initialization (such as TRX), the address must be initialized on-chain before the label becomes editable.
  3. If the address has already been initialized but the label is still not editable, this is a known bug. Escalate to the engineering team.
  4. Engineering deployed a fix: after initialization, address labels should now be editable. Confirm the customer is on the latest platform version and retry.

Notes: The bug was that TRX address labels remained locked even after initialization. A fix was released to production. Addresses still must be initialized before label editing is possible — this is by design for chains that require address initialization.

"For wallets that need each individual address to be initialized, the address must first be initialized before the label is mutable. This portion is working as intended. For TRX, our team found the label remains locked even after initialization which is unintended." (ticket #267289)

"This has now been resolved with Address Labels being able to have edits performed. Of note, Addresses will need to be first initialized before the label is editable." (ticket #267289)

Scenario: eth-address-addresses-generation#btc-change-address

Trigger: Customer asks how BTC change is handled when no change address is specified, or whether a custom change address must be within the same wallet.

Signals: BTC, change address, change, next address, same wallet, custom change address

Steps:

  1. If no change address is specified in the transaction, BTC change is automatically returned to the next allocated address in the wallet. This behavior is the same for both API and UI transactions.
  2. If the customer specifies a custom change address, that address must be within the same wallet.
  3. The UI currently allows setting a custom change address per transaction but does not support setting a default change address at the wallet level. The SDK has a parameter for change address per transaction as well.
  4. If the customer requests a default change address feature (as a wallet-level config), log this as a feature request and ask for a business impact statement so engineering can prioritize accordingly.

Notes: There is currently no wallet-level configuration for a fixed default change address. This has been requested as a feature.

"Q1) You don't need to manually specify a change address — your explanation of the process is accurate. 'I assume that it goes to the next allocated address in the wallet' and works same in API Q2) Yes the address needs to be within the same wallet" (ticket #247393)

"The UI currently allows setting a custom change address per transaction but not as a default, SDK has a parameter so no default necessary. We currently do not allow setting a fixed change address as a wallet config." (ticket #247393)

Scenario: eth-address-addresses-generation#token-flush-request

Trigger: Customer reports a discrepancy between confirmed and spendable balance on an ETH wallet and requests that specific addresses be flushed to consolidate tokens.

Signals: flush, confirmed balance, spendable balance, VIRTUAL, forwardToken, redeployAddress, ETH, token, contract address

Steps:

  1. Obtain the Wallet ID, the address(es) to flush, the token contract address, and any relevant transaction hashes from the customer.
  2. Verify the on-chain confirmation status of the referenced transaction(s) using a block explorer (e.g., Etherscan).
  3. Using the BitGo admin tool (bga), attempt to redeploy the address if needed: bga admin redeployAddress --addresses <address>. If the address is already deployed, it will be skipped.
  4. Flush the token using: bga admin forwardToken --wallet <wallet_id> --tokenAddress <token_contract_address> --addresses <address>.
  5. Confirm the flush transaction on-chain and notify the customer with the transaction hash.
  6. If the amount to flush is less than the gas fees required, skip that address and inform the customer.
  7. Verify that confirmed and spendable balances now align after flushing.

Notes: ETH base-chain balances generally do not need flushing; flushing is typically for ERC-20 tokens on forwarding addresses. Ensure the customer provides the token contract address for each address to be flushed. If addresses are not attached to a BitGo wallet, they cannot be flushed — ask the customer to double-check.

"bga admin forwardToken --wallet [WALLET_ID] --tokenAddress [ETH_ADDRESS] --addresses [ETH_ADDRESS] Attempting to flush tokenAddress [ETH_ADDRESS] for addresses: 1 1 addresses flushed for address [ETH_ADDRESS]" (ticket #360638)

Scenario: eth-address-addresses-generation#polygon-indexer-outage

Trigger: Customer reports address validation failures on Polygon via BitGo Express, receiving a 404 "wallet address not found" error.

Signals: polygon, validate address, BitGo Express, wallet address not found, NotFound, 404, indexer

Steps:

  1. Ask the customer for the full error response including the requestId.
  2. Check the BitGo status page (https://status.bitgo.com/) for any ongoing Polygon indexer incidents.
  3. If an indexer outage is confirmed, inform the customer that this is a transient platform issue and that it should resolve once the indexer recovers.
  4. Ask the customer to retry after the incident is resolved.
  5. If no known outage is listed, escalate to engineering with the endpoint, coin, wallet ID, address, and full error response.

Notes: Polygon indexer outages can cause address lookups to fail with 404 errors even though the addresses are valid. These are transient issues.

"We had an issue with our polygon indexers earlier today that has been resolved." (ticket #265723)

Scenario: eth-address-addresses-generation#physical-address-change

Trigger: Customer wants to update their personal or enterprise physical/mailing address on their BitGo account but cannot find a self-service option in the UI.

Signals: physical address, mailing address, change address, residential address, update address, account address, utility bill, lease, government ID

Steps:

  1. Confirm the customer's identity and the enterprise/account in question.
  2. There is no self-service option in the BitGo UI to change a physical/mailing address. The customer must contact support.
  3. Request a government-issued photo ID showing the new address, or a lease agreement, utility bill, or property deed with their name and new address.
  4. If the customer is an FTX creditor, confirm whether they have already updated their address on the FTX portal first. If not, instruct them to do so before requesting the update on BitGo. Reference: https://www.bitgo.com/ftx-faq
  5. Once documentation is received, pass the request and documents to the internal team for review and update.
  6. Confirm to the customer once the address has been updated.

Notes: Acceptable documents include: utility bill, lease agreement, property deed, or government-issued photo ID showing the new address. The customer can email these to support@bitgo.com.

"You will need to submit a lease agreement or Utility Bill with your name/company name on it. Once received, we will review and update." (ticket #216893)

"Could you kindly provide your new residential address so we can update it on our platform? We will need a government-issued photo ID that displays the address you wish to update." (ticket #360209)

Scenario: eth-address-addresses-generation#identity-verification-liveness

Trigger: Customer cannot complete address/identity verification because the automated liveness test is not prompting or is failing.

Signals: verify, liveness, live verification, video call, Calendly, government ID, identity verification

Steps:

  1. If the automated liveness test is unsuccessful or not prompting, offer the customer a video call with the BitGo team for manual verification.
  2. Provide the scheduling link: https://calendly.com/bitgo-client-delivery/videoid
  3. Instruct the customer to have their government-issued photo ID ready during the meeting.

Notes: This applies to identity/address verification flows, not blockchain address creation.

"If the automated liveness test is unsuccessful, you can schedule a video call with our team for verification. Please use the following link to schedule a time to meet with us and verify the request: https://calendly.com/bitgo-client-delivery/videoid" (ticket #318481)

Scenario: eth-address-addresses-generation#non-bitgo-client-address-access

Trigger: A non-BitGo client contacts support requesting access to a blockchain address that is managed by a third party (e.g., Wirex) through BitGo infrastructure.

Signals: not a client, Wirex, ETH address, access, cannot locate, third party

Steps:

  1. Attempt to locate the user's account on the BitGo platform using the email address they contacted from.
  2. If no account is found, inform the customer that BitGo cannot assist because they are not a BitGo client and BitGo does not hold their account details.
  3. Direct the customer to contact the third-party service (e.g., Wirex) for assistance, as that service controls the wallet/address in question.

Notes: BitGo cannot provide access to wallets or addresses belonging to third-party clients. The third party must initiate any access or recovery process.

"Unfortunately, we are not able to assist as you are not a BitGo client and so we do not have your details on our platform. You might want to contact Wirex support for assistance." (ticket #236947)

Related