Scoutinternal

Transaction Approval and Approver Issues on BitGo Wallets

Transaction Approval and Approver Issues on BitGo Wallets

Problem

Customers encounter a range of issues related to transaction approvals and approver configuration on BitGo wallets. Common symptoms include: inability to approve pending transactions (password errors, UI errors, missing approver notifications), confusion about how the "Required # of Approvals" setting interacts with admin roles and final approvers, approvals getting stuck in a "processing" state, the "remove" button for final approvers being greyed out due to locked policies, pending approvals not loading in the UI, and transactions bypassing expected approval requirements. These issues span all wallet types (custodial, self-managed hot, and self-managed cold) and affect multiple chains.

Diagnostics

  • Identify the wallet type: Check in the BitGo Admin tool whether the wallet is custodial or self-managed (non-custodial). Support capabilities differ: BitGo can add/remove admins on custodial wallets but cannot add admins to non-custodial wallets.
  • Check wallet policy configuration: In the Admin tool, review the wallet's policy section. Look at the allTx:getApproval rule, the "Required # of Approvals" value, and whether "Require Admin Approval On All Outgoing Transactions" is enabled.
  • Count wallet admins vs. required approvals: Confirm the number of admin users on the wallet against the required number of approvals. If required approvals ≥ number of admins, the initiating admin cannot also be an approver, which can deadlock the approval flow.
  • Verify the user's role on the wallet: Check whether the user attempting to approve has admin permissions on the specific wallet (and on any Go Account if applicable). A user with only spender or viewer permissions cannot provide admin approval.
  • Check for enterprise-level policies: Review whether an enterprise-level policy (accessible via the 9-dot menu) or a Final Approver policy is in effect. Enterprise policies can layer additional approval requirements on top of wallet-level settings.
  • Determine if the wallet policy is locked: If the customer reports the "remove" button or policy settings are greyed out, the wallet policy is locked and requires a video verification call to unlock for up to 48 hours.
  • Check for pending approval state: Look at the pending approval's current state. If it shows "processing," it may be stuck due to a race condition (simultaneous approvals). Escalate to engineering if needed.
  • Verify user onboarding status: Confirm the approver has completed their BitGo account onboarding (first login). Users who have not yet logged in will not appear as valid approvers on pending approvals created before their onboarding.
  • Check for UI errors: If the customer reports "Error: Cannot read properties of undefined (reading 'forEach')" or similar JavaScript errors on the Pending Approvals page, this is a known platform-side bug. Check the BitGo status page and internal Slack channels for ongoing incidents.
  • Password type: Determine whether the user is entering their login password or the wallet password. Only the wallet creator uses the wallet password; all other users with permissions use their login password. When using the API, the Access Token creator's password applies.

Resolution

Scenario: approval-approver-final-approve#self-approval-not-allowed

Trigger: Customer expects a transaction they initiated to count as one of the required admin approvals, or they are the only admin and cannot approve their own transaction.

Signals: self-approve, submitter cannot approve, initiator approval, required approvals, only admin, not enough admins

Steps:

  1. Explain to the customer: The user submitting a transaction cannot also provide admin approval for the transaction they submit. This is a platform-level restriction.
  2. If the wallet requires N admin approvals, there must be at least N+1 admins on the wallet (or N admins plus a spender who initiates the transaction).
  3. To add an additional admin: for custodial wallets, an existing admin can invite a new user. For non-custodial (self-managed) wallets, the existing admin must add the user directly via the wallet's Users section in the UI.
  4. If the customer wants an API key's transactions to count toward the approval flow, clarify that the API key inherits the permissions of its creator. The creator's submission still cannot self-approve.

Notes: This is the most common misunderstanding. It applies equally to wallet-level and enterprise-level approval policies.

"Unfortunately, this is not possible. The User submitting a transaction cannot also provide admin approval for the transaction they submit." (ticket #117647)

"The user cannot provide admin approval for the transactions they submit." (ticket #174731)

Scenario: approval-approver-final-approve#require-approval-toggle-not-enabled

Trigger: Customer has set "Required # of Approvals" to a value but transactions are still going through without any admin approval.

Signals: transactions bypass approval, no approval required, broadcasting without approval, admin approval not triggered

Steps:

  1. Navigate to the wallet's Settings tab in the UI.
  2. Check whether "Require Admin Approval On All Outgoing Transactions" is enabled (toggled on). The "Required # of Approvals" field only dictates how many admins must approve if an approval is triggered — it does not by itself force approvals on every transaction.
  3. If the toggle is not enabled, instruct the customer's admin to enable it. A policy unlock may be required (see the locked-policy scenario).
  4. Also verify whether the wallet has an allTx:getApproval policy rule. If not, the approval requirement is only triggered by other conditions (e.g., velocity limits, whitelist violations).

Notes: This distinction between the toggle and the number field is a frequent source of confusion. The toggle is the master switch; the number field sets the quorum.

"Did you find that the toggle for requires admin approval worked like we spoke about on our call today?" (ticket #232241)

"The difference between these two wallets is, 'Require Admin Approval On All Outgoing Transactions' is enabled on the wallet requiring 2 Admins, while the example wallet does not have this enabled." (ticket #174731)

Scenario: approval-approver-final-approve#policy-locked-cannot-modify

Trigger: Customer reports the "remove" button for a final approver is greyed out, or they cannot change policy settings (Required # of Approvals, final approvers, whitelist).

Signals: greyed out, remove button disabled, cannot change policy, policy locked, update failed

Steps:

  1. Confirm the wallet policy is locked. This is the expected behavior for custodial and locked self-managed wallets.
  2. A video verification call is required to unlock the policy for up to 48 hours.
  3. Provide the customer with the scheduling link: https://calendly.com/bitgo-client-delivery/videoid
  4. Instruct the customer to reference their ticket number when scheduling and to have a government-issued photo ID ready.
  5. If the customer has not been previously video-verified, a previously verified owner of the enterprise must join the call.
  6. Once unlocked, the customer's admin can navigate to Wallet Settings to make the desired changes (remove final approver, change number of approvals, etc.) within the 48-hour window.

Notes: Removing a user from the final approver list in a policy does not happen automatically when the user is removed from the enterprise. Each policy must be updated individually. Policies are re-locked automatically after 48 hours.

"The button is greyed out because the wallet policy is locked and will require a video call to be able to unlock the policy for up to 48 hours to apply changes." (ticket #208874)

"We have unlock the wallet policy for next 24 hours. You would now be able to update the number of approvals required to approve the whitelist." (ticket #321902)

Scenario: approval-approver-final-approve#wrong-password-on-approval

Trigger: Customer receives a "password incorrect" or passphrase error when attempting to approve a transaction in the UI.

Signals: password incorrect, passphrase error, wrong password, error on approval, unable to approve

Steps:

  1. Determine whether the user is the wallet creator or another admin/spender on the wallet.
  2. Only the wallet creator should use the established wallet password. All other users with permissions on the wallet must use their login password when approving in the UI.
  3. When using the API, the user of the Access Token inputs whatever password the Token's creator would use.
  4. Ask the customer to clear browser cache, refresh their session, and try again. Recommend using Chrome in incognito mode to rule out caching issues.
  5. If the issue persists, check whether the user recently reset their login password — this could cause a mismatch if an old session is cached.
  6. If the user has confirmed the correct password and still receives the error, request the wallet ID for further investigation.

Notes: Password manager auto-fill can sometimes inject incorrect credentials. Suggest the customer manually type the password.

"Reviewing this wallet, I show [EMAIL] is the creator. They should be the only one using the established wallet password. All other users with permissions on this wallet will use their login password when using the wallet within the UI." (ticket #174731)

Scenario: approval-approver-final-approve#pending-approval-stuck-processing

Trigger: A pending approval appears stuck and never reaches the final approver, or the approval state shows "processing" indefinitely.

Signals: stuck approval, processing state, final approver not reached, approval not completing, simultaneous approval

Steps:

  1. This is caused by a race condition: two users approve nearly simultaneously. User A's approval triggers the backend to set the state to "processing." User B's near-simultaneous approval attempt receives an error ("request was already resolved"), and the backend fails to advance the state from "processing" to the next step.
  2. Escalate to the Engineering team with the pending approval ID and wallet ID.
  3. Engineering can cancel the stuck transaction in the database, which will change its state to "rejected."
  4. The customer will need to re-initiate the transaction after the stuck approval is cleared.
  5. Advise the customer to coordinate approvals so that approvers do not attempt to approve at nearly the same instant.

Notes: This is a known backend issue. If the customer reports this repeatedly, file a JIRA ticket referencing the race condition in the pending approval state machine.

"User B also attempts to approve the Pending Approval, almost at the same time as User A but just a tiny bit later. User B gets back an error saying that the request was already resolved... somehow this step of setting the correct Pending Approval state no longer happens and the Pending Approval remains stuck in processing." (ticket #183359)

Scenario: approval-approver-final-approve#pending-approvals-ui-error

Trigger: The Pending Approvals tab fails to load, displaying "Error: Cannot read properties of undefined (reading 'forEach')" or similar JavaScript errors.

Signals: forEach error, pending approvals not loading, UI crash, cannot read properties of undefined, activity page crash

Steps:

  1. Check internal Slack channels and the BitGo status page (https://status.bitgo.com/) for known platform-wide incidents.
  2. This error has been a known platform-side bug (internal reference: cr-901) affecting multiple enterprises simultaneously.
  3. If confirmed as a platform issue, inform the customer that the engineering team is aware and working on a resolution.
  4. Once engineering resolves the issue, confirm with the customer that the Pending Approvals tab is loading again.
  5. If the issue is isolated to one user, ask them to clear all browser cache, update Chrome to the latest version, and retry. Also suggest trying in Chrome incognito mode.

Notes: If the issue is caused by a very large number of old pending approvals on the enterprise/wallet, this can also cause the page to crash. In that case, engineering may need to bulk-reject old pending approvals on the backend.

"Error: Cannot read properties of undefined (reading 'forEach')" (ticket #217469)

"All of these approvals have already been rejected and the page will crash if you scroll down." (ticket #228622)

Scenario: approval-approver-final-approve#approver-not-visible-new-user

Trigger: A user configured as an approver in the policy does not appear in the approval flow and does not receive notification for a pending approval.

Signals: approver not showing, no notification, user not listed, missing approver, new user not visible

Steps:

  1. Verify that the user has completed their BitGo onboarding by logging in for the first time at https://app.bitgo.com/web.
  2. If the user completed onboarding after the pending approval was created, they will not be recognized as a valid approver for that specific approval.
  3. The initiator should rescind the existing transaction and re-initiate it. The newly onboarded user will then appear as a valid approver.
  4. Confirm the user is listed in the wallet's policy as an approver and has the correct role (admin).

Notes: This is expected behavior, not a bug. The system evaluates eligible approvers at the time the pending approval is created or last updated.

"The user completed their onboarding process after the pending approval was created and last updated. Consequently, they were not recognized as a valid approver at that time, which is why they did not receive a notification to approve." (ticket #231784)

"I would have Matt login to https://app.bitgo.com/web, rescind the the transaction and re-initiate. You will then see Hillel as an approver." (ticket #231784)

Scenario: approval-approver-final-approve#removing-user-from-self-managed-wallet

Trigger: Customer wants to remove an admin from a self-managed (non-custodial) wallet but cannot complete the removal because the target user is unavailable or no second approver exists.

Signals: remove user, self-managed wallet, admin removal, no secondary approver, user no longer with company

Steps:

  1. BitGo Support cannot remove admins from self-managed wallets directly.
  2. The removal must be initiated from the wallet's Users section in the UI by another admin. The admin being removed (or someone with access to their BitGo account) must then accept the removal request.
  3. If the user is no longer with the organization and their account is inaccessible: a. Work with the organization's IT team to gain access to the departed user's email. b. Trigger a password reset via the "Forgot Password" prompt on the BitGo login screen. c. Schedule a video call to reset the departed user's 2FA. The person on the call must be a previously verified enterprise owner. Use: https://calendly.com/bitgo-client-delivery/videoid d. After regaining account access, log in as the departed user and accept the pending removal request.
  4. Once removed from the wallet, repeat at the enterprise level if needed.
  5. Wallets with past transfer activity cannot be deleted but can be archived in Wallet Settings.

Notes: This is a multi-step process that requires coordination with the customer's IT team. For custodial wallets, Support can assist with user removal directly after video verification.

"We are unable to remove Spenders or Admins from self-managed wallets. If you select to remove Yiannis from the wallet within the Users section of the wallet, either Yiannis or a member of your team with access to Yiannis's Bitgo account can then accept the removal." (ticket #216424)

Scenario: approval-approver-final-approve#configuring-approval-policies

Trigger: Customer asks how to set up approval requirements, add approvers, configure dual authorization, or create enterprise-wide approval policies.

Signals: how to set up approvals, add approver, dual authorization, require approval, configure policy, spender initiator

Steps:

  1. Wallet-level approvals: Navigate to the wallet's Settings tab. Set the "Required # of Approvals" to the desired number and enable "Require Admin Approval On All Outgoing Transactions" if approvals should be enforced on every withdrawal.
  2. Spender-initiated workflow: Give the transaction initiator spender permissions on the wallet. Add the desired approvers as wallet admin users. Spender-initiated transactions will automatically require admin approval.
  3. Enterprise-level policies: An enterprise owner can access the enforcement policies section via the 9-dot menu at the top of the screen. This allows configuring velocity limits, approval requirements, and final approver rules that apply across all wallets.
  4. Final Approver policies: These are configured at the enterprise policy level and enforce that specific designated users must approve transactions on all wallets under the enterprise.
  5. Multiple approval groups: It is not possible to configure group-based approval logic (e.g., "one from Group A AND one from Group B") in a single policy. Two separate policies are needed: one for wallet admin approvals and one for final approver approvals.
  6. If a single user belongs to multiple approval actions, that user's single approval can satisfy multiple requirements simultaneously.
  7. Policy changes themselves require approval from another admin.

Notes: The $250,000 USD video approval threshold for custodial wallets cannot be adjusted. Transactions to newly whitelisted addresses for the first time also trigger video approval on custodial wallets. These thresholds are fixed by the Trust team.

"You will want the initiator to have Spender permissions on any wallet they will create a withdrawal on. From there, you can add an Owner as a Wallet Admin to each of those wallets. This will default to require the Spender to get the Admin's approval for withdrawals." (ticket #237298)

"It is not possible to have this function from a single Policy. You will need to configure two policies, one that looks to request Admin Approval from 2 Wallet Admins and one that looks to request Final Approver Approval from 2 Users on the wallet." (ticket #315987)

Scenario: approval-approver-final-approve#bulk-reject-old-pending-approvals

Trigger: Customer has a large backlog of old pending approvals that cannot be efficiently rejected through the UI, or the activity page crashes when loading them.

Signals: bulk reject, old approvals, page crash, slow page, delete pending approvals, bulk approval

Steps:

  1. There is no bulk approval or rejection tool available in the BitGo UI.
  2. Confirm with the customer that they authorize rejection of the specified pending approvals (get explicit permission and wallet IDs).
  3. Escalate to the Engineering team to perform the bulk rejection on the backend.
  4. Engineering may need time to process the request. Keep the customer informed of progress.
  5. Once completed, confirm with the customer that the pending approvals have been cleared.

Notes: Large numbers of pending approvals can degrade UI performance. The https://app.bitgo.com/1/0/activity/all page is particularly affected. This is a known limitation.

"This request to reject the 93 pending approvals should now be completed." (ticket #228622)

Scenario: approval-approver-final-approve#phantom-approvers-ui-bug

Trigger: Users appear as approvers on transactions despite not being configured as final approvers, or incorrect approvers are displayed in the approval UI.

Signals: phantom approver, wrong approver, incorrect approver, random approver added, UI showing wrong user

Steps:

  1. Confirm the wallet's final approver configuration in the admin tool and verify which users are actually listed.
  2. This was a known UI bug that was fixed by the Engineering team (internal reference: POL-253).
  3. If the customer reports this issue, check whether the fix has been deployed by verifying with Engineering.
  4. If the bug has recurred, escalate to Engineering with the wallet ID and screenshots showing the incorrect approvers.

Notes: This was a display-only issue — the incorrect approvers shown in the UI did not actually have approval power. The underlying approval logic was correct.

"Just to update here that our team has fixed this issue and you should no longer see incorrect approvers in the UI as flagged in this ticket." (ticket #207145)

Scenario: approval-approver-final-approve#missing-permissions-for-go-account

Trigger: User receives an error when trying to approve a batch or settlement on a Go Account despite having the correct enterprise role.

Signals: Go Account, batch approval error, settlement error, OTC settlement, missing permissions, cannot approve batch

Steps:

  1. Check the user's permissions on the specific Go Account. Having an enterprise-level role does not automatically grant permissions on the Go Account.
  2. An admin on the Go Account (check admin list) must invite the user to the Go Account with the appropriate permissions (e.g., spender).
  3. For OTC settlement approvals, confirm that the settlement has completed processing. Funds may not be immediately available for withdrawal after trading.
  4. If the error persists after permissions are confirmed, escalate via internal Slack channels.

Notes: Enterprise-level roles and Go Account roles are separate. Users must be explicitly added to each Go Account they need access to.

"You will need to have an admin on the Go Account invite you to the Go Account as a Spender in order for your permissions to mimic Chade. Ryan, Thomas, or Andrew can provide this invite." (ticket #265950)

Scenario: approval-approver-final-approve#user-management-key-share-approval

Trigger: Customer receives an unexpected "Activity Approval" prompt related to sharing keys with users, not a transaction approval.

Signals: activity approval, share keys, key sharing, user management system, unexpected approval prompt

Steps:

  1. Explain that this is related to the User Management System recently added to the platform, which manages how users are added to wallets and at which roles.
  2. This prompt asks the admin to share keys to various wallets with users so they may spend or manage certain actions on the wallet.
  3. Choosing "share keys" will show a subsequent prompt listing which keys to which wallets will be shared.
  4. This is expected behavior and not an error.

Notes: This approval type is separate from transaction approvals and policy change approvals.

"This is related to the new User Management System recently added to our platform which is an improved method of managing how users are added to wallets and at which roles. This is a prompt to share keys to various wallets with users so they may spend or manage certain actions on the wallet." (ticket #243216)

Scenario: approval-approver-final-approve#ui-error-transient

Trigger: Customer encounters an intermittent error when clicking approve, but the issue resolves on retry, cache clear, or re-login.

Signals: intermittent error, retry works, cache issue, transient error, fifth time charm

Steps:

  1. Ask the customer to clear all browser cache and update Chrome to the latest version.
  2. Try the approval action again in a fresh session or Chrome incognito mode.
  3. If the error was transient and does not recur, no further action is needed.
  4. If it recurs consistently, request a HAR file capture (Chrome DevTools → Network tab → reproduce error → download HAR) and escalate to Engineering.

Notes: Many one-off UI errors are resolved by cache clearing and session refresh. Always try this step first before escalating.

Related