Scoutinternal

Wallet Creation, Visibility, and Access Issues on BitGo

Wallet Creation, Visibility, and Access Issues on BitGo

Problem

Customers encounter a range of issues related to creating, viewing, and accessing wallets on the BitGo platform. Common symptoms include: wallets (especially legacy V1 BTC wallets) disappearing from the dashboard after UI migrations; inability to create wallets for specific coins (e.g., ETH, SEI, ZETA, Lightning) due to account plan limitations or missing coin licenses; errors during wallet creation workflows (keycard activation, key generation); wallets not visible because the user lacks permissions on the wallet or enterprise; and general confusion about how to create or restore wallets via the UI or API.

Diagnostics

  • Identify the user's account and enterprise: Use the admin tool (bga) to look up the user's email, confirm their account status, enterprise membership, and plan type (PayGo vs. Business Enterprise).
  • Check wallet existence: Search by wallet ID or BTC address using bga to confirm the wallet still exists, its balance, coin type (v1btc vs. v2), and which enterprise it belongs to.
  • Check user permissions on the wallet: Verify the user is listed in the wallet's Users list with an appropriate role (admin, spender, viewer). Also confirm the user is a member of the enterprise the wallet belongs to.
  • Check enterprise coin licenses: Verify which coins are enabled for the enterprise. Some coins (ETH, SEI, ZETA, Lightning/lnbtc) require a Business Enterprise plan or a specific signed agreement/license to be enabled.
  • Check account plan type: Determine if the user is on a PayGo account (limited coin support: BTC, BCH, BTG, LTC, ZEC, XLM, DASH) or a Business Enterprise account (broader coin support including ETH, ERC-20 tokens, and newer chains).
  • Check for V1 BTC wallet migration issues: If the wallet is a V1 BTC (type safehd) wallet, check whether the wallet has been synced/added to the user's enterprise in the new UI. Reference JIRA BG-69685 for known V1 BTC migration issues.
  • Check for enterprise setting changes: If the enterprise previously had "Users can view all wallets" enabled and it was removed, individual wallet permissions may need to be re-granted.
  • Check the wallet creation method: If using the API, confirm the SDK version, the coin ticker used in the endpoint, and whether the subType and other required fields are correctly passed.
  • Check Lightning-specific prerequisites: For Lightning wallet creation, confirm the enterprise has the custodyLightningWallet license enabled and that the latest version of BitGo Express is being used. The Lightning node (operated by Voltage) must also be provisioned.

Resolution

Scenario: wallet-create-wallets-bitgo#v1-btc-missing-new-ui

Trigger: Customer reports their BTC wallet is missing or not visible after the BitGo UI migration/update, and the wallet is a legacy V1 BTC wallet.

Signals: missing wallet, V1 BTC, v1btc, safehd, wallet disappeared, new UI, UI migration, cannot see BTC wallet, BCH BSV BTG visible but not BTC

Steps:

  1. Use the admin tool to confirm the wallet exists, its type (v1btc/safehd), balance, and enterprise association.
  2. Confirm the user is listed on the wallet and the enterprise.
  3. If the wallet is not appearing in the new UI, use bga ent addwallet <wallet_id> to sync the wallet to the user's enterprise.
  4. Ask the customer to log in again and verify the wallet is visible. Advise them to check all enterprises by clicking the dropdown on the top-left corner under the BitGo icon.
  5. If the issue persists, escalate to engineering referencing JIRA BG-69685 for V1 BTC wallet UI display issues.
  6. Reassure the customer that funds are safe and the wallet can still be accessed via the API while the UI issue is being resolved.

Notes: BitGo migrated from an old UI to a new UI which affected the display of V1 BTC wallets. BitGo no longer performs wallet upgrades from V1 to V2 on behalf of customers. Customers needing V2 functionality should create a new BTC wallet and transfer funds from their old V1 wallet to the new one.

"We have been migrating from old UI to new BitGo user interface which has affected the old v1btc wallets." (ticket #72415)

"v1btc wallets are supported in the UI, we are currently check why you are not able to see them. We will provide an update shortly" (ticket #207939)

"I can see your V1 BTC wallet. We are making some changes with the UI so at the moment we hare having issues viewing V1 BTC wallets. It is something we are actively working on." (ticket #86781)

Scenario: wallet-create-wallets-bitgo#user-not-on-enterprise-or-wallet

Trigger: Customer reports a wallet is missing from the dashboard, but admin lookup shows the wallet exists and the user either lacks wallet-level permissions or is not a member of the enterprise the wallet belongs to.

Signals: wallet not found, missing wallet, no permissions, not part of enterprise, cannot see wallet, enterprise membership

Steps:

  1. Use the admin tool to identify which enterprise the wallet belongs to and list the wallet's users.
  2. Confirm whether the reporting user is a member of that enterprise and has permissions on the specific wallet.
  3. If the user is not on the enterprise, advise them to have the enterprise owner add them to the enterprise.
  4. If the user is on the enterprise but not on the wallet, advise a wallet admin to invite them to the wallet with the appropriate role.
  5. If the enterprise previously had "Users can view all wallets" enabled and this was removed, the removal may not have fully synced. The wallet admin must explicitly grant wallet-level permissions to affected users.

Notes: An API access token created by a user inherits equal to or fewer permissions than that user's login. If the user creating the token lacks wallet access, API calls using that token will return "wallet not found" errors.

"While we are showing you and Hannah both have permissions on this wallet, neither of you are part of the Enterprise this wallet is a part of. They will need to add you to the Volabit Enterprise for you to be able to access wallets there." (ticket #202374)

"If this Enterprise had 'Users can view all wallets' enabled, removal of that setting may not have fully synced across all users on your Enterprise." (ticket #209665)

"Users of your API key have equal to or less permissions on our platform as your login. Having a wallet admin add you both to these wallets should allow these wallets to be found." (ticket #195431)

Scenario: wallet-create-wallets-bitgo#coin-not-available-paygo

Trigger: Customer cannot find a specific coin (e.g., ETH, SEI, ZETA) in the wallet creation dropdown, and admin lookup shows they are on a PayGo account.

Signals: ETH not available, Ethereum wallet, SEI token, ZETA, create wallet, coin not listed, PayGo, unsupported coin

Steps:

  1. Confirm the customer's account plan type using the admin tool (PayGo vs. Business Enterprise).
  2. If the customer is on a PayGo account, inform them that only Bitcoin, Bitcoin Cash, Bitcoin Gold, Litecoin, Zcash, Stellar, and Dash are supported for PayGo accounts.
  3. For coins like ETH, SEI, ZETA, or other tokens available only on Business Enterprise plans, direct the customer to contact the BitGo sales team at: https://www.bitgo.com/connect-with-us/
  4. If the customer is on a Business Enterprise plan but the coin is still not listed, check whether the specific coin license has been enabled on their enterprise. Coordinate with the customer success manager or internal team to enable the coin.
  5. Confirm the customer is logged into the correct enterprise, as some customers have multiple enterprises (e.g., Inc. vs. Trust entities). Advise them to check the enterprise ID under their profile > settings.

Notes: Some coins require a signed Coin Specific Addendum (CSA) before they can be enabled. The customer success manager or sales team handles the contract signing process.

"Our ETH wallet are available on our Business Enterprise account holder. For PayGo account only Bitcoin, Bitcoin Cash, Bitcoin Gold, Litecoin, Zcash, Stellar, and Dash are supported." (ticket #237108)

"We have enabled the SEI token for you. You should be able to see the SEI token option in wallet creation now." (ticket #188048)

"You need to login using your [email] and need to complete the account setup... Make sure you are under the enterprise Criterion Corp. with the ID [enterprise_id]. You can check the enterprise ID by clicking on your profile icon and going to settings tab." (ticket #236939)

Scenario: wallet-create-wallets-bitgo#lightning-wallet-creation

Trigger: Customer attempts to create a Lightning wallet via the API and receives errors such as "Coin or token type tlntbc not supported" or subType not being recognized.

Signals: lightning wallet, lnbtc, tlntbc, lightningCustody, UnsupportedCoinError, subType, custodyLightningWallet license, Voltage node

Steps:

  1. Confirm the customer's enterprise has the custodyLightningWallet license enabled. If not, coordinate with the sales team (e.g., Ryan Sisti or the assigned CSM) to get the Lightning Wallet agreement signed and the license enabled.
  2. Verify the customer is using the latest version of BitGo Express. Provide the update links:
  3. Confirm the correct coin ticker is being used in the API call: lnbtc for mainnet, tlntbc for testnet. The older ticker tlnbtc is incorrect.
  4. Ensure the API call includes "subType": "lightningCustody" in the request body.
  5. After the wallet is created via the API, a Lightning node must be provisioned by the node operator (Voltage). If the wallet is created but no address can be generated, escalate to engineering to check whether the Voltage node has been stood up.
  6. Reference the developer docs: https://developers.bitgo.com/docs/wallets-lightning-custody

Notes: Lightning wallet creation is API-only. The enterprise must have the appropriate license enabled before the API call will succeed. Even after successful wallet creation, there may be a delay while the Lightning node is provisioned.

"enterprise involved is missing self-custody lightning license..." (ticket #269423)

"You will not be able to proceed with a success here until the agreement has been signed and the license enabled." (ticket #269423)

"The existing wallet you have setup is good. At this point, this is just waiting for the node team to finish the last steps on the wallet. Our engineering team has reached out to Voltage who operates the node." (ticket #319261)

Scenario: wallet-create-wallets-bitgo#keycard-activation-code

Trigger: Customer is unable to complete wallet creation because they cannot find or input the activation code from the keycard PDF.

Signals: keycard, activation code, wallet creation stuck, keycard PDF, 6-digit code, cannot find code

Steps:

  1. Explain that when a wallet is created via the UI, a Keycard PDF is downloaded to the customer's computer.
  2. The Keycard contains a 6-digit Activation Code that must be input into the UI to finalize the wallet creation.
  3. Direct the customer to locate the downloaded Keycard PDF and find the Activation Code field on it.
  4. Advise the customer to use a desktop or laptop computer with the latest version of Google Chrome when creating wallets.
  5. Recommend disabling any browser plugins that may interfere with the site's performance.
  6. If the customer chose "offline key creation" (supplying their own public key), advise that this is restricted to contracted Institutional customers. For standard wallet creation, they should choose the option to let BitGo create the key.

Notes: The BitGo mobile app is only for transaction approvals and does not support wallet creation. Wallets must be created via the web UI at https://app.bitgo.com/auth/log-in or via the API.

"When creating the wallet, please choose the option to let Bitgo create the key for you. Offline key creation is restricted to contracted Institutional Customers." (ticket #332311)

"Please see the example screenshot I have provided of one of my test wallet's keycard. There you will see an example of the Activation Code to input." (ticket #250551)

"Our official app is only for approvals and does not allow the creation of wallets." (ticket #245138)

Scenario: wallet-create-wallets-bitgo#wallet-password-recovery-keycard

Trigger: Customer wants to restore access to a wallet using their BitGo keycard, or has forgotten their wallet password.

Signals: restore wallet, keycard, wallet recovery, forgot password, Box D, wallet password

Steps:

  1. Instruct the customer to log into their account at https://app.bitgo.com/auth/log-in.
  2. Navigate to the wallet they want to recover.
  3. Go to "Settings", click on "Password" in the left column.
  4. Click the "Recover your wallet" link at the bottom of the center column.
  5. The customer will need to supply all of the text info in "Box D" of their Keycard to complete the recovery process.
  6. If the customer needs 2FA reset or account unfreezing, request identity verification: the first 8 and last 8 characters of their BitGo Public Key found on "Box C" of the keycard, or 3 transaction hashes, or the date of their BitGo email verification.

Notes: For account-level access issues (frozen account, lost 2FA), support must verify the customer's identity before resetting 2FA or unfreezing the account. The keycard's "Box C" (BitGo Public Key) is used for this verification — specifically "the first 8 / last 8 characters".

"To start the wallet recovery process, log into your account and go to the wallet you're trying to spend from. Then go to 'Settings', click on 'Password' in the left column, and then finally click on the 'Recover your wallet' link at the bottom of the center column. Now you'll start the wallet recovery process, and you'll need to supply all of the text info in the Box D of your Keycard" (ticket #276224)

"Alternatively, you may provide us the first and the last 8 characters of your BitGo Public Key found on your wallet keycard (Box C)" (ticket #318088)

Scenario: wallet-create-wallets-bitgo#api-wallet-not-found-token-permissions

Trigger: Customer receives a "wallet not found" or "WalletNotFound" error when calling the BitGo API, and the access token was created by a user who lacks permissions on the target wallet.

Signals: wallet not found, WalletNotFound, API error, access token, API key, permission denied, 404

Steps:

  1. Identify which user created the access token being used in the API call.
  2. Verify whether that user has permissions on the target wallet using the admin tool.
  3. If the user does not have access, advise the customer to either: a. Have a wallet admin add the token-creating user to the wallet with appropriate permissions, OR b. Create a new access token using a user account that already has the required wallet permissions.
  4. Remind the customer that an access token's permissions are equal to or less than the creating user's permissions. A token with spend permission cannot be used by a viewer or a user not added to the wallet.

Notes: This commonly occurs when a user is removed from a wallet or enterprise, but their old API token is still in use. It also occurs when a new user is set up for API integrations but has not yet been granted wallet-level access.

"We were able to locate the error in our logs, we see the user doing the call is '[EMAIL]' which does not have access to the wallet id below thus it triggers the error because the user lacks the access to this wallet below" (ticket #243099)

"For the access token to work, you need to give the access token the needed permission as well as ensuring the person doing the call has the needed permission." (ticket #243099)

Scenario: wallet-create-wallets-bitgo#wallet-lifecycle-archive-freeze

Trigger: Customer asks about deactivating, archiving, deleting, or cleaning up unused wallets created via automation.

Signals: delete wallet, archive wallet, deactivate, unused wallets, wallet lifecycle, freeze wallet, cleanup

Steps:

  1. Inform the customer that there is no means to delete a wallet from the BitGo platform.
  2. Wallets with a 0 balance can be archived by an admin on that wallet via the UI: navigate to the wallet > Settings tab > Archive button.
  3. There is currently no API endpoint for archiving wallets. If a wallet has any balance and needs to be archived, the customer must email support@bitgo.com.
  4. Wallets can be frozen using the API endpoint: https://developers.bitgo.com/reference/v2walletfreeze — however, freezing does not remove the wallet from the UI, and initialized on-chain addresses can still receive funds.
  5. There is no mechanism to prevent an archived wallet from receiving funds if its on-chain addresses have already been created.
  6. For high-volume onboarding flows, recommend the customer implement logical tagging/labeling at the application layer for unused wallets, and periodically archive 0-balance wallets via the UI.

Notes: Wallet deletion is intentionally not supported for audit, compliance, and security reasons. The freeze endpoint is documented at https://developers.bitgo.com/reference/v2walletfreeze.

"Within the Settings tab in the UI for each wallet, there is an Archive button that allows an admin on that wallet to Archive a wallet with 0 balance. There is currently no means to perform this with the API. If a wallet does have any level of balance, an email needs to be sent to our support team so that we can archive the wallet. There is no mechanism to prevent an archived wallet from still receiving funds." (ticket #267979)

"There is no means to delete a wallet from our platform. We do offer the ability to freeze a wallet, but this will not remove the wallet from the UI view and if the wallet has been initialized so the receive addresses are live onchain, there is nothing to prevent that address from receiving funds." (ticket #267979)

Scenario: wallet-create-wallets-bitgo#role-permissions-wallet-creation

Trigger: Customer is a wallet admin or enterprise member but cannot create new wallets within an enterprise, or receives permission errors when attempting to create wallets.

Signals: cannot create wallet, permission error, wallet admin, role, custom role, enterprise admin

Steps:

  1. Verify the user's role within the enterprise using the admin tool.
  2. If the user was recently added as a Wallet Admin via Default Roles but still cannot create wallets, recommend the Org Admin create a Custom Role for the user with the specific permissions needed (including wallet creation).
  3. Once the custom role is created and assigned, the user can be safely removed from the Default Roles (e.g., Wallet Admin, Wallet Spender) as the custom role will grant the required permissions.
  4. Confirm there is no option to create a wallet within an existing wallet — each wallet is an independent entity under the enterprise.

Notes: There is no "sub-wallet" or "child wallet" concept. Each wallet is created independently under the enterprise. The "create new address" option within a wallet generates receive addresses, not new wallets.

"Please note there is no option to create a wallet within a wallet at BitGo. You can use the option to create a separate independent wallet, if you require additional wallet for BTC under this Enterprise account." (ticket #266797)

"Our recommendation here is to have the Org Admin create you your own Custom Role. Instead of adding you as a member on the Default Roles, they should grant you the needed permissions to the needed wallets through that Custom Role which should resolve this issue for you." (ticket #266797)

Scenario: wallet-create-wallets-bitgo#btc-unspent-consolidation

Trigger: Customer receives an "insufficient funds" error when sending BTC despite having an adequate balance, due to too many small unspents in the wallet.

Signals: insufficient funds, unspents, consolidation, consolidate unspents, BTC, transaction limit, 200 unspents

Steps:

  1. Explain that a BTC transaction can only consume a maximum of 200 unspents. If the sum of the 200 highest-value unspents is not sufficient to cover the transaction amount plus fees, an "insufficient funds" error will occur.
  2. Direct the customer to consolidate unspents using the API endpoint: https://developers.bitgo.com/api/express.wallet.consolidateunspents
  3. Alternatively, the customer can send small BTC transactions to consolidate unspents organically.
  4. Note that consolidation is not done automatically due to the multi-signature nature of BitGo wallets — BitGo does not have access to customer private keys.

Notes: The default limit is 200 unspents for consolidation per transaction.

"The default limit is 200 unspents for consolidation. A transaction can only consume a maximum of 200 unspents to build the transaction, and if the sum of your 200 highest-value unspents is not sufficient to cover the transaction amount (plus fees), you will receive an 'insufficient funds' error." (ticket #40806)

Scenario: wallet-create-wallets-bitgo#self-managed-hot-wallet-key-creation

Trigger: Customer asks how to create wallet keys externally or use their own backup key for a self-managed hot wallet.

Signals: external signing, backup key, self-managed hot wallet, key creation, air-gapped, BitGo Express, OVC

Steps:

  1. Advise the customer to install BitGo Express.
  2. Use the Create Keys endpoint to generate keys for use with self-managed hot wallets: https://developers.bitgo.com/api/express.keychain.local
  3. Keys created this way are stored on the local machine where BitGo Express is installed.
  4. Once the key is created, the customer can create a wallet using that key. Full wallet functionality (send/receive) is available via both the UI and API.
  5. Clarify that the Offline Vault Console (OVC) is NOT needed for self-managed hot wallets — OVC is only for customers licensed for self-managed cold wallets.
  6. Direct the customer to the developer documentation at: https://developers.bitgo.com/

Notes: If a customer creates a wallet by supplying their own keys, they can still make full use of the wallet via the UI or BitGo Express. OVC is restricted to cold wallet configurations.

"You will want to install Bitgo Express. From there, you will want to use the Create Keys endpoint we provided which will create a key for use with Self-Managed Hot wallets. Once they key is created, you can then create a wallet which makes use of that key. OVC is not needed." (ticket #263512)

"If you create a wallet by supplying keys you have created, your team can make full use of the wallet using the UI or via Bitgo Express." (ticket #263512)

Scenario: wallet-create-wallets-bitgo#dashboard-loading-issue

Trigger: Customer reports the BitGo dashboard is not loading or wallet views fail to render, often after a platform update or outage.

Signals: dashboard not loading, wallet view not loading, cannot access wallet, UI error, browser issue

Steps:

  1. Ask the customer to try accessing the platform from a desktop or laptop using the latest version of Google Chrome.
  2. Recommend clearing browser cache and cookies, or trying incognito mode.
  3. Advise disabling any browser plugins that may interfere with the site.
  4. Check https://status.bitgo.com/ for any ongoing outages or scheduled maintenance.
  5. If the issue persists and appears to be platform-side, escalate to engineering for investigation.

Notes: The login URL is https://app.bitgo.com/auth/log-in (production) or https://app.bitgo-test.com/ (testnet).

"Please try to perform the task again using desktop or a laptop device. We also suggest to use the latest google Chrome as the main browser when accessing https://app.bitgo.com/login You may also try to disable any browser plugins that may have interfered with the site performance." (ticket #72415)

Related