Scoutinternal

Whitelist Policy Unlock, Address Whitelisting, and Withdrawal Issues

Whitelist Policy Unlock, Address Whitelisting, and Withdrawal Issues

Problem

Customers frequently contact support when they are unable to add, modify, or remove whitelisted addresses on their BitGo wallets or enterprises. The most common scenarios include: (1) wallet policies are locked and the customer receives a "Cannot update locked rule" error when trying to change the whitelist, (2) customers (especially FTX creditors on Go Accounts) are confused about how to whitelist an address or why their spendable balance shows zero after trading, (3) customers need guidance on the address verification process for custodial wallets, and (4) customers encounter errors when sending to non-whitelisted addresses ("violates advanced whitelist"). These issues span multiple coins and wallet types (self-managed hot, custody/trust, and Go Accounts).

Diagnostics

  • Identify the wallet type: Determine whether the wallet is a self-managed hot wallet, self-managed cold wallet, custody (trust) wallet, or a Go Account. The unlock and verification workflows differ significantly between these types.
  • Check the policy lock state: Use bga w <walletId> and bga policy get <policyId> to inspect the wallet policy. Look at the Mutable up to date field — if it is blank or a past date, the policy is locked. A locked policy will produce Cannot update locked rule <ruleId> on policy <policyId> errors.
  • Confirm the customer's role on the wallet: Use bga w <walletId> to see the Users list. Verify the requester is an admin on the wallet. Only admins can modify policies and approve whitelist changes. If the customer is a viewer or spender, they cannot make whitelist changes.
  • Check if the error is "violates advanced whitelist": This means the customer is trying to send to an address not on the whitelist, and the policy action is getApproval. If the sender is the only admin, they cannot self-approve, effectively blocking the transaction.
  • Check if this is a Go Account / FTX creditor: Go Accounts have a distinct whitelist flow. Spendable balance of 0 typically indicates settlement has not completed (funds are not immediately available after trading). Confirm settlement status.
  • Check for address format issues: For memo-based chains (XLM, XRP), verify the customer is entering the address and memo/tag separately, not appending the memo to the address string. For ETH-based addresses, note that addresses are case-insensitive (checksummed vs. lowercase) — BitGo may convert to lowercase.
  • Check for "Unverified" label or "Pending Small Deposit Test" on whitelisted addresses: For custodial/trust wallets, the "Unverified" label and the "Pending Small Deposit Test" status are informational and indicate the address has not yet been verified through a first withdrawal. These have no blocking effect on self-managed wallets. The "Pending Small Deposit Test" applies to external addresses being whitelisted on custody wallets; it is a BitGo-enforced verification control, not purely a regulatory (e.g., EU/BaFin) requirement, though it aligns with regulated custody compliance standards.
  • Determine the customer's plan tier: PayGo/Starter plan users are NOT eligible for policy unlocks in production. Only Business account users and above can request policy unlocks via video verification.

Resolution

Scenario: whitelist-unlock-whitelisted-whitelisting#locked-policy-unlock

Trigger: Customer receives "Cannot update locked rule" error when trying to add, modify, or remove a whitelisted address, indicating the wallet or enterprise policy is locked.

Signals: Cannot update locked rule, locked rule, policy locked, unlock policy, unlock whitelist, add whitelisted address, Calendly, video verification, video call, policy unlock

Steps:

  1. Ask the customer for the Wallet ID(s) or Enterprise ID and the Policy ID (if known) that need to be unlocked.
  2. Verify the customer is an admin on the wallet or enterprise using bga w <walletId>.
  3. Confirm the customer's plan tier. If they are on a PayGo/Starter plan in production, policy unlocks are not available. For testnet wallets, unlocks can be performed after verifying the user's permission to the wallet without a video call.
  4. For Business tier and above (production): send the customer the Calendly video verification link: https://calendly.com/bitgo-client-delivery/videoid. Instruct them to have a government-issued photo ID ready and to reference their ticket number when scheduling.
  5. On the video call, verify the customer's identity against their government-issued photo ID. Record the video verification.
  6. After successful verification, unlock the policy using: bga policy setmutablev2 --hours <duration> (typically 24 or 48 hours). The customer must make all whitelist changes within this window.
  7. Confirm the unlock with the customer and remind them that after the unlock window expires, the policy will automatically re-lock.
  8. If the customer misses the unlock window and the policy re-locks before changes are made, the unlock process must be repeated.

Notes: - Wallet policies lock automatically 48 hours after the first policy is set up or after the last policy change.

  • For self-managed hot wallets, the video verification is required only for policy unlocks, not for individual withdrawals.
  • For custody wallets, policies do not require a video call to add new whitelisted addresses because verification occurs at withdrawal time (first withdrawal to a new address triggers video verification).
  • The maximum unlock duration agents have used in tickets is 48 hours, though the --hours parameter can be set per request.

"Our wallet policies will be locked 48 hours after your setup of your first policy. In production environment, we do not offer policy unlocks for our PayGo/Starter plan users. For our Business account users, we can unlock the policy after verifying the request in a video call with the user." "Self-managed hot wallets: Since you don't need a video verification call for withdrawals, we have the policies gated instead for security purposes when users try to add new whitelisted addresses after the policies are locked. Any time you update the wallet policies, after 48 hours, those policies lock and can only be updated after a video verification call is complete requesting us to unlock them so you can make the appropriate changes." "Custody wallets: Since you need a KYC call for all first time withdrawals to newly whitelisted addresses, we don't request for a video verification on initial entry because you will be verifying the address on that withdrawal call. No need for a call to unlock policies to add new whitelisted addresses for these wallets."

Scenario: whitelist-unlock-whitelisted-whitelisting#violates-advanced-whitelist-single-admin

Trigger: Customer receives "violates advanced whitelist" error when trying to send, and they are the only admin on the wallet with a whitelist policy configured for getApproval.

Signals: violates advanced whitelist, getApproval, single admin, cannot approve own transaction, approval denied, advancedWhitelist

Steps:

  1. Verify the wallet's policy using bga w <walletId> and bga policy get <policyId>. Confirm the policy includes advancedWhitelist:getApproval.
  2. Check the Users list to confirm the customer is the only admin on the wallet.
  3. Explain to the customer: the wallet is configured to require admin approval for any withdrawal to an address not on the whitelist. An admin who submits a transaction cannot provide their own approval for that same action. Since there is no second admin, withdrawals to non-whitelisted addresses are effectively blocked.
  4. Advise the customer of two workarounds:
    • Add another admin to the wallet who can provide approvals as needed.
    • Remove all whitelisted addresses from the policy (requires a policy unlock first if the policy is locked). When no addresses are whitelisted, the non-whitelisted approval flow is not triggered.
  5. If the customer needs the policy unlocked to make these changes, follow the locked-policy-unlock scenario above.

Notes: This scenario only applies to self-managed hot wallets. The key issue is that any wallet with at least one whitelisted address will enforce the approval workflow for sends to non-whitelisted destinations.

"You are currently the only admin on this wallet. This wallet is configured to Get Admin Approval for any withdrawal to an address not on the whitelist. An admin submitting a change on the wallet, including a withdrawal, cannot provide their own admin approval for that action. Since approval for sending to a non-whitelisted address cannot be gained, your withdrawal is flat out being denied by policy." "As you mentioned, as long as there is any whitelisted address on the wallet, the non-whitelisted approval process is in play. A workaround for this wallet would be to either add another admin that would provide approvals as needed or to remove all whitelisted addresses."

Scenario: whitelist-unlock-whitelisted-whitelisting#go-account-whitelist-and-zero-spendable

Trigger: Customer (typically an FTX creditor with a Go Account) has whitelisted an address but cannot withdraw because spendable balance shows zero, or they are confused about the whitelist process.

Signals: spendable balance 0, zero balance, FTX, Go Account, settlement, can't withdraw, whitelist tab, how to whitelist, ftxcreditors@bitgo.com, Enter an amount that doesn't exceed the maximum spendable balance

Steps:

  1. Confirm the customer is on a Go Account (check enterprise type).
  2. If the spendable balance shows 0 but the wallet balance is non-zero, explain that funds are not immediately available for withdrawal after trading due to settlement processing time. Ask the customer to try again after settlement completes (typically within 24–48 hours).
  3. If the customer is asking how to whitelist an address, provide the following instructions:
    • Navigate to the Go Account Wallet.
    • Click on the whitelist tab.
    • Click on whitelist and add the address.
  4. If the customer has whitelisted an address and it shows as "Unverified," explain that the address will remain unverified until a withdrawal is initiated to that address. Upon initiating the withdrawal, if additional verification is required, the customer will be prompted to complete a selfie/liveness verification or schedule a video call.
  5. If the customer is trying to add a bank account and encountering issues (e.g., needing correspondent bank info), clarify that crypto withdrawal to a whitelisted crypto address is the primary path for Go Accounts. Bank withdrawal options depend on the entity and account configuration.

Notes: - The "Enter an amount that doesn't exceed the maximum spendable balance" message with a 0 spendable typically resolves after settlement completes.

  • Go Accounts are excluded from the enterprise-level "All Wallets" policies per the policy engine design.
  • For FTX creditor distributions, funds are credited on a specific date communicated via email and cannot be withdrawn before that date.

"Please follow the steps below to whitelist an address:- —> Navigate to your Go Account Wallet —> Click on whitelist tab —> Click on whitelist and add the address" "The address will remain unverified until a withdrawal is initiated to that specific address. Once the withdrawal is submitted, if additional verification is required, you will be prompted to schedule a video call with us to complete the address and transaction verification." "Please note that funds are not immediately available for withdrawal after trading due to settlement processing time. This ensures that all transactions are properly recorded and processed. As a result, your spendable balance may show as 0 until the funds are fully settled."

Scenario: whitelist-unlock-whitelisted-whitelisting#memo-address-format-error

Trigger: Customer cannot whitelist an address on a memo-based chain (XLM, XRP, etc.) because they are appending the memo/tag directly to the address string instead of entering them separately.

Signals: XLM, XRP, Stellar, memo, memo id, tag, destination tag, unable to whitelist, invalid address, ?dt=

Steps:

  1. Ask the customer to provide the address and memo/tag in plain text.
  2. Instruct the customer to add the address alone in the address field, without the memo or tag appended (e.g., do not include ?dt= in the address).
  3. The memo ID or destination tag should be entered in the separate memo id field provided in the whitelist form.
  4. After adding correctly, the whitelisted entry will display the address with the memo shown separately.

Notes: This is a common formatting mistake on XLM and XRP. The address field should contain only the base address; the memo/tag goes in its own field.

"You need to add the address alone without the tag: GA5XIGA5C7QTPTWXQHY6MCJRMTRZDOSHR6EFIBNDQTCQHG262N4GGKTM then under memo id 1697558486476042067."

Scenario: whitelist-unlock-whitelisted-whitelisting#unverified-label-on-whitelist

Trigger: Customer sees an "Unverified" label or "Pending Small Deposit Test" status next to whitelisted addresses in the UI and is concerned about whether transactions are safe to send or whether the test is mandatory.

Signals: Unverified, unverified label, whitelist verification, informational, trust wallet, self managed wallet, Pending Small Deposit Test, small deposit, EU requirement, regulatory, same enterprise, intra-enterprise

Steps:

  1. Explain that the "Unverified" label and the "Pending Small Deposit Test" status are displayed for informational purposes on custody (trust) wallets.
  2. The "Pending Small Deposit Test" is BitGo's address verification step for custody wallets applied to external addresses being whitelisted. It is a BitGo-enforced compliance control, not purely an EU or BaFin regulatory requirement, though it aligns with regulated custody standards. If the test is not completed, the address remains in an "Unverified" state and withdrawals to it may be blocked until verification is completed.
  3. Whitelist verification (including the small deposit test) is functionally relevant only for custody (trust) wallets. For self-managed wallets, the "Unverified" label has no effect on the ability to send transactions.
  4. For custody wallets, the address is verified during the first withdrawal to that address via a video verification call or selfie liveness check.
  5. Reassure the customer that they can proceed with transactions to whitelisted addresses on self-managed wallets regardless of the "Unverified" label.
  6. If the customer asks whether the small deposit test can be skipped or bypassed (e.g., because the address belongs to a wallet within the same enterprise), check internally with the Trust/Custody or Client Delivery team — no self-service exception is available, and any exception must be confirmed against compliance requirements before communicating to the customer.

Notes: The "Unverified" label was confirmed by BitGo engineering as a UI display issue for self-managed wallets — "whitelist verification is only for trust wallets. It has no effect on self managed wallets." The "Pending Small Deposit Test" is the specific status label shown on custody wallet whitelist entries for external addresses awaiting first-withdrawal verification. It is not purely an EU/BaFin requirement but is consistent with regulated custody compliance controls.

"After speaking with our engineers I found out that this is a mistake, whitelist verification is only for trust wallets. It has no effect on self managed wallets. It is for informational purposes only on custodial wallets"

Scenario: whitelist-unlock-whitelisted-whitelisting#custody-video-verification-thresholds

Trigger: Customer on a custody (trust) wallet has completed one video verification for a small test withdrawal but is prompted again for a larger withdrawal amount.

Signals: video verification, custodial, trust wallet, 250k, threshold, liveness, video call again, second verification

Steps:

  1. Explain the three conditions that trigger a video verification call on custody wallets:
    • Transaction amount is ≥ $250,000 USD.
    • Total transactions in a rolling 24-hour period are ≥ $250,000 USD.
    • The customer is sending to an unverified whitelisted address (first-time send).
  2. After the address is verified via a first successful withdrawal, subsequent sends to that same address will not require address verification. However, if the amount exceeds the $250k threshold, a new video verification is required for the transaction itself.
  3. If the customer's initial liveness/selfie check was unsuccessful, they can schedule a video call with the support team as a fallback.

Notes: The $250k thresholds apply per-transaction and on a rolling 24-hour aggregate basis. Both conditions are independently evaluated.

"You need to do a video call to verify custodial withdrawals only in the below 3 conditions: transaction is >= 250k usd, transactions in a rolling 24hr period are >=250k usd, if you are sending to an unverified whitelisted address. Thus after verifying the address, if the amount sent is over 250k then another video call will be needed."

Scenario: whitelist-unlock-whitelisted-whitelisting#ui-navigation-withdrawal

Trigger: Customer is on the wrong page in the UI (e.g., Enterprise settings instead of wallet-level view) and cannot find the whitelist tab or withdrawal button.

Signals: can't find whitelist, can't click, withdrawal button, Assets tab, View As, Wallets, enterprise settings, wrong page

Steps:

  1. Instruct the customer to navigate to the Assets tab at the top of the screen.
  2. Next to the +Create Wallets button, they should see a View As button. Click it and select Wallets to switch the dashboard view to show individual wallets.
  3. Each wallet row will display a Withdrawal button. Click this to open the transaction builder.
  4. In the transaction builder, the To / Destination field should auto-populate with valid whitelisted addresses for the chosen coin.
  5. If the customer is trying to manage whitelisted addresses, they should click into the specific wallet, then navigate to the whitelist tab within that wallet's view.

Notes: The Enterprise-level settings page does not show wallet-level whitelist management. Customers frequently confuse the enterprise view with the wallet view.

"When you login to the platform, at the main dashboard, choose Assets. From there, next to the 'Create Wallets' button, you should see a 'View As' button. There you will have the option to choose 'Wallets'. This will show your wallets. Next to each Wallet is a 'Withdrawal' button. You will want to choose this to withdraw from the wallet. The 'To' or Destination field should auto-populate the valid Whitelisted addresses you can send the chosen Coin too."

Scenario: whitelist-unlock-whitelisted-whitelisting#wallet-password-error-on-withdrawal

Trigger: Customer has whitelisted an address but receives an error when attempting the withdrawal due to an incorrect wallet password.

Signals: wallet password, incorrect password, wrong password, Forgot Wallet Password, wallet passphrase

Steps:

  1. Inform the customer that their login password and wallet password may be different. Changing the login password does not change the wallet password.
  2. The wallet creator must use the wallet passphrase they set when the wallet was created. Any other user on the wallet should use their BitGo platform password.
  3. If the customer has forgotten their wallet password, they can reset it from: Wallet > Settings > Forgot Wallet Password?
  4. After completing the wallet password reset, the customer should be able to perform the withdrawal.

Notes: This issue often surfaces alongside whitelist-related complaints because the customer assumes the whitelist is the blocker, when the actual issue is an incorrect wallet passphrase.

"Please also note that your login password can be different from your wallet password and if you had changed your login password, your wallet passwords will not change. Also, Please note the creator of the wallet will need to use the wallet passphrase they set for the wallet. Any other user will use their BitGo platform password. You can reset your wallet password from Wallet > Settings > Forgot Wallet Password?"

Scenario: whitelist-unlock-whitelisted-whitelisting#whitelisting-audit-report-request

Trigger: Customer requests a historical report of all whitelisted addresses (with timestamps) for audit or compliance purposes.

Signals: whitelisting report, audit, controls audit, timestamp, historical, whitelisted addresses log, calendar year

Steps:

  1. Acknowledge the request. There is currently no self-service way to generate a whitelisting history report in the BitGo UI.
  2. Escalate the request internally to the appropriate team (Client Delivery / Engineering) to pull the whitelisting data with timestamps from the backend.
  3. Communicate realistic timelines to the customer — engineering involvement may be required to ensure timestamps are accurate.
  4. Note that the backend approval flow shows line items for pending approval, approval received (with timestamp and user), and video verification status. The status may display as "pending" in the initial line item even for completed approvals — the subsequent line items confirm completion.
  5. Flag to Product team that customers have requested the ability to view approval history and whitelisting logs directly in the UI for future enhancement.

Notes: This is a manual process that requires internal coordination. Set expectations with the customer accordingly. There is no UI report currently available for this data. For customers who need to programmatically list current whitelisted addresses (not historical audit logs), direct them to the API endpoints described in the fetch-whitelist-via-api scenario.

"As of now, there is not a best way to generate this in the UI - but we are happy to help here."

Scenario: whitelist-unlock-whitelisted-whitelisting#fetch-whitelist-via-api

Trigger: Customer asks how to retrieve or list whitelisted addresses programmatically via the API, either for a specific wallet or across an entire enterprise.

Signals: API, fetch whitelist, list whitelist, programmatic, advancedWhitelist, expandAdvancedWhitelist, enterprise whitelist, whitelisted addresses API, walletId whitelist, enterpriseId whitelist

Steps:

  1. To fetch the whitelist entries for a specific wallet, use the Get Wallet endpoint with the expandAdvancedWhitelist query parameter:
    GET /api/v2/{coin}/wallet/{walletId}?expandAdvancedWhitelist=true
Authorization: Bearer <accessToken>
    When expandAdvancedWhitelist=true, the response includes the wallet's whitelist entries from the advancedWhitelist rules, showing all whitelisted addresses, walletIds, and enterpriseIds for that wallet.
  2. To search or list whitelists across the whole enterprise (instead of one wallet at a time), use the aggregated enterprise whitelist endpoint:
    GET /api/v2/enterprise/{enterpriseId}/whitelists
Authorization: Bearer <accessToken>
    This returns a paginated list of whitelist entries (walletId, address, label, coin, etc.) across all wallets in the enterprise.
  3. Ensure the access token used has read permissions scoped to the relevant enterprise and wallets. Insufficient permissions can result in empty or error responses.

Notes: - The expandAdvancedWhitelist=true parameter is the per-wallet approach; the /enterprise/{enterpriseId}/whitelists endpoint is the enterprise-wide aggregated approach.

  • Both endpoints require a valid Bearer access token with appropriate read permissions.
  • If the customer needs a historical audit log of whitelist changes (with timestamps), that is a separate request — see the whitelisting-audit-report-request scenario above.

Related

  • policy-structure — Covers policy parameters including scope, touchpoint, conditions, and actions relevant to whitelist policies.
  • policies-faqs — Addresses common questions about policy approvals, admin requirements, and in-progress policy changes.
  • bitgo-global-regulated-entities — Relevant when determining which entity governs the customer's wallet type and available features (custody vs. self-managed, Go Accounts).