Scoutinternal

Locked Token Balances, Unlock Schedules, and Withdrawal Issues (SUI, ZETA, EIGEN, DEEP, SEI)

Locked Token Balances, Unlock Schedules, and Withdrawal Issues (SUI, ZETA, EIGEN, DEEP, SEI)

Problem

Customers holding tokens subject to vesting or lockup schedules (most commonly SUI, ZETA, DEEP, EIGEN, and SEI) encounter situations where their wallet balance appears fully available in the UI but withdrawals are blocked, where unlocked tokens do not reflect in the spendable balance after an unlock event, or where they need guidance on the withdrawal process for recently unlocked tokens. These issues arise in BitGo custody and wealth management wallets where a lockedAmount wallet flag restricts spendable balance until the token foundation authorizes an unlock. Related requests include foundations submitting updated lock amounts via spreadsheets, investors asking about unlock schedules, and bulk withdrawal approvals tied to foundation distributions.

Diagnostics

  • Identify the wallet and coin: Obtain the wallet ID and coin type (SUI, ZETA, DEEP, EIGEN, SEI, etc.) from the customer. Confirm whether the wallet is on BitGo custody (app.bitgo.com) or BitGo Wealth Management (e.g., zetachain.bitgowealthmanagement.com).
  • Check the lockedAmount flag via BGA: Run bga w <wallet_id> and look for the walletFlags section. The lockedAmount flag stores the locked token amount in the smallest unit (e.g., for SUI, 1 SUI = 1,000,000,000 units). Confirm whether a lock is set and what its current value is.
  • Compare balance fields: Check balanceString, confirmedBalanceString, spendableBalanceString, and lockedBalanceString. The spendable balance is calculated as: Spendable = Confirmed Balance + Staked Balance − Locked Amount. If the locked amount exceeds the confirmed balance, spendable will be zero or negative.
  • Check the UI vs. API discrepancy: Spoof the user and verify what the UI shows for "Available to Withdraw." A known bug caused the UI to display the full balance as withdrawable even when the lockedAmount flag was correctly set on the backend. The actual withdrawal would still be limited to the spendable amount.
  • Determine if an unlock event has occurred: Ask whether the token foundation (e.g., Sui Foundation / Mysten Labs, ZetaChain Foundation, Eigen Foundation) has communicated an unlock date. Check if a spreadsheet with updated lock amounts has been submitted by the foundation contact.
  • Check staking status: If the customer unstaked tokens, verify the unbonding/cooldown period (e.g., 21 days for ZETA, variable for EIGEN). Tokens remain locked during cooldown. Staking locked/vested tokens does not make them unlocked upon unstaking — they remain locked.
  • Wealth Management accounts: If the customer references zetachain.bitgowealthmanagement.com or similar, they must contact the dedicated wealth management support email, not standard BitGo support.
  • Lock API (for admin/TKM integrations): If the lock was set via the admin lock API (POST /api/v2/admin/wallet/<walletId>/lock), confirm the payload included the correct currency field (e.g., "currency":"bera:dolo") and that the GET wallet balance call returns expected values. A NULL balance response may indicate a token-specific indexing issue.

Resolution

Scenario: sui-tokens-amounts-locked#foundation-unlock-update

Trigger: A token foundation (e.g., Sui Foundation, ZetaChain, Eigen) submits a spreadsheet with updated lock amounts tied to a scheduled unlock event.

Signals: locked amounts, update SUI locked amounts, spreadsheet, unlock schedule, foundation, Nandish, Jade, DEEP lock, vesting

Steps:

  1. Receive the spreadsheet from the foundation contact (typically sent to support@bitgo.com and/or nandish@bitgo.com with CC to the CSM team).
  2. Validate the spreadsheet: check that lock amounts are rounded to 2 decimal places (not repeating decimals like 641666.666666667). If values appear to be rounded or truncated, confirm with the foundation contact before proceeding.
  3. For each wallet listed, use the BGA tool to update the lock:
    bga wallet flags add lockedAmount <amount_in_smallest_unit>
    For SUI, multiply the token amount by 1,000,000,000 (9 zeros). For example, 1,000,000 SUI = 1000000000000000.
  4. If a wallet already has an existing lock for a different token on the same chain (e.g., DEEP on SUI), adjust the lock amount according to the new values in the sheet. Note this in your reply.
  5. Confirm completion to the foundation contact and the CSM team.

Notes: Lock updates are a recurring process; Sui Foundation sends updated spreadsheets ahead of each unlock date (e.g., monthly). Always wait for the foundation's spreadsheet before modifying locks. BitGo does not determine the unlock schedule — the foundation does.

"bga wallet flags add lockedAmount 1000000000000000 — lockedAmount flag added for wallet [WALLET_ID]" "Can your team double-check the sheet for 1/16? I am seeing some strange values I want to confirm are intentional. Example, for Cell 3B, I am showing the value of 641,666.67 in the cell. Clicking on this further reveals the number is being rounded up and the true value is 641666.666666667." "Hi Jade, We have updated the lock amount as per your request for February 3rd, 2025."

Scenario: sui-tokens-amounts-locked#tokens-not-spendable-after-unlock

Trigger: Customer reports that tokens should be unlocked per the vesting schedule but the spendable balance is still restricted or shows zero.

Signals: unable to withdraw, tokens not available, spendable balance zero, unlock not reflected, locked amount, lockedAmount flag, ZETA, EIGEN, SUI, DEEP, SEI

Steps:

  1. Run bga w <wallet_id> to verify the current lockedAmount flag value.
  2. Calculate expected spendable: Spendable = Confirmed Balance + Staked Balance − Locked Amount. If the locked amount has not been updated to reflect the latest unlock, the spendable balance will remain low.
  3. Check whether the foundation has submitted an updated lock spreadsheet for this unlock date. If not, advise the customer: "For information regarding the date and time of your token unlock, please reach out directly to the [Foundation Name] team, as they manage the unlock schedule."
  4. If the spreadsheet was submitted and the lock amount was supposed to be updated but wasn't, update it immediately using:
    bga wallet flags add lockedAmount <new_amount_in_smallest_unit>
  5. If the issue is that staking rewards or claimed rewards are being counted against the lock (e.g., EIGEN staking rewards should be liquid), escalate to engineering via Slack with the wallet ID and a clear description. Reference the known pattern where the lock flag exceeds the total confirmed balance, making spendable zero.
  6. Confirm with the customer once resolved and ask them to retry.

Notes: For ZETA, there is a 21-day unbonding/cooldown period after unstaking. Tokens will not appear as confirmed balance until cooldown completes. Staking locked/vested tokens does NOT unlock them upon unstaking — they remain locked. For EIGEN, staking rewards that are manually claimed should be liquid and withdrawable, but a bug has been observed where the lock flag blocks these as well. This requires engineering intervention.

"Hi, Thanks for your patience. This should be resolved now. Could you please try again and let us know how it goes?" "The wallet has a lock flag of approximately 167,364 EIGEN, while the total balance is only 306 EIGEN, which is much less than the locked amount. As a result, withdrawals are not possible currently." "You can stake vested, locked awards so perhaps they didn't [know] they can only withdraw the unlocked portion (i.e. unstaking locked awards still keeps them locked)."

Scenario: sui-tokens-amounts-locked#ui-shows-full-balance-but-locked

Trigger: Customer (or internal CSM) reports that the web UI displays the full balance as "Available to Withdraw" despite a lock being correctly set on the backend.

Signals: UI incorrect, available to withdraw shows full amount, web UI bug, locked amount 0 in UI, spendableBalanceString correct, display error

Steps:

  1. Verify that the lockedAmount wallet flag is correctly set via bga w <wallet_id>.
  2. Confirm that the spendableBalanceString returned by the API reflects the correct restricted amount.
  3. Reassure the CSM/investor that the actual withdrawal is limited to the spendable amount even if the UI displays a higher figure — the backend enforces the lock.
  4. Report the UI discrepancy to the engineering team via JIRA/Slack. Reference the known bug pattern.
  5. Once engineering confirms a fix is deployed, notify the CSM and ask the customer to verify the UI now displays the correct available balance.

Notes: This was a known UI bug observed with SUI wallets. The backend correctly enforced the lock — only the spendableBalanceString amount could actually be withdrawn. Engineering resolved this via a UI fix.

"This could be just the web UI showing an incorrect amount but only up to 3438937036620 SUI can be actually withdraw. We have referred this to our Engineering Team for further review." "We have fixed this issue and the UI should show the correct balance now."

Scenario: sui-tokens-amounts-locked#unlock-schedule-visibility

Trigger: Customer asks whether they can view their token unlock schedule within the BitGo portal.

Signals: unlock schedule, vesting dates, view unlock, portal, UI, when do tokens unlock

Steps:

  1. Inform the customer: "Due to security and compliance issues, we do not show the unlock schedule on UI."
  2. Direct the customer to contact the token foundation (e.g., Mysten Labs / Sui Foundation, ZetaChain Foundation, Eigen Foundation) for their specific unlock schedule.
  3. For ZetaChain Wealth Management users, the Token Grants page may show vesting dates via the calendar icon in the actions column.

Notes: BitGo acts as the technology provider and does not determine or publish unlock schedules. The foundation controls all timing.

"Due to security and compliance issues, we do not show the unlock schedule on UI." "For information regarding the date and time of your token unlock, please reach out directly to the Mysten Labs team, as they manage the unlock schedule."

Scenario: sui-tokens-amounts-locked#custody-withdrawal-process

Trigger: Customer with recently unlocked tokens needs guidance on how to withdraw from a custodial wallet.

Signals: how to withdraw, whitelist address, video verification, Pending Video ID, custodial wallet withdrawal, SUI withdrawal

Steps:

  1. Confirm that the tokens are actually unlocked and the spendable balance reflects the expected amount.
  2. Instruct the customer: "As this is a custodial wallet, you will first need to whitelist the address you want to send to, after which you can then send to the whitelisted address."
  3. Explain that sending to an address for the first time will require a video verification call. After initiating the withdrawal, the transfer will appear in "Pending Video ID" state, and the customer will see the option to schedule a call.
  4. Provide the Calendly scheduling link for video verification: https://calendly.com/bitgo-client-delivery/kyc
  5. After the video call is completed and approved, BitGo trust operations will process the withdrawal.
  6. For SUI-based tokens, ensure the wallet has sufficient SUI to cover gas fees. If the wallet shows a 0.00 SUI spendable balance, first check whether there is an on-chain balance at the base address that is not being displayed correctly. If an on-chain balance exists but is not showing in the UI, resolve the balance display issue before proceeding (see the balance display troubleshooting steps). Once any display issue is resolved, if the SUI balance is genuinely below the required minimum (0.1 SUI), advise the customer to deposit additional SUI to the wallet's base address.

Notes: For token withdrawals on SUI (including SUI:DEEP and SUI:SUINS), the wallet must hold native SUI for gas. If the wallet shows 0.00 SUI spendable balance, do not immediately advise a deposit — first verify whether an on-chain balance exists at the base address that is simply not being reflected in the UI. Only after confirming the on-chain balance is genuinely insufficient should the customer be asked to deposit additional SUI. Unstaking SUI requires at least 2 SUI in the wallet.

"As this is a custodial wallet, you will first need to whitelist the address you want to send to, after which you can then send to the whitelisted SUI address. Sending to an address the first time will require a video verification call with us. You will see the option to schedule this call after you initiate the withdrawal and see the transfer in Pending Video ID state." "To process the withdrawal, your wallet must have enough SUI to cover the required gas fees. Please deposit SUI into your wallet's base address."

Scenario: sui-tokens-amounts-locked#bulk-withdrawal-csv

Trigger: Customer or foundation representative needs to perform bulk token withdrawals to multiple addresses using a CSV file.

Signals: bulk upload, CSV, bulk withdrawal, multiple addresses, bulk send, SUI Foundation, DEEP, SUINS, bulk transfer

Steps:

  1. Direct the customer to the Withdrawal page in the BitGo UI. The bulk withdrawal option is located at the bottom of the page.
  2. Instruct them to download the CSV template from the bulk withdrawal screen.
  3. The CSV columns are: From (Wallet ID), To (Recipient Address), Amount, Coin, Comment.
  4. For coin type, use: sui for SUI tokens, sui:deep for DEEP tokens, sui:suins for SuiNS tokens.
  5. Each row represents one transaction (1 recipient per transaction — no "send to many" in a single tx).
  6. One CSV file can contain multiple token types.
  7. For Sui Foundation and similar large entities, bulk transfers require a video verification call. The caller should email support@bitgo.com and trustoperations@bitgo.com with the CSV file attached ahead of the call, including the entity name, token type, row count, and total amount.
  8. Schedule the video call via: https://calendly.com/bitgo-client-delivery/kyc and reference the ticket number.

Notes: Bulk withdrawal is supported for custody wallets (SUI only for custody; broader asset list for self-custody). Supported assets for bulk include: BCH, BTC, LTC, DASH, ZEC, DOGE, ETH, BSC, POLYGON, SOL, VET, HASH, ADA, ALGO, BASEETH, SUI, ATOM, OSMO, TIA, BLD, OG, SEI, SEIEVM, ZETA, INJECTIVE, IOTA, COREUM, THOR, BABY, CRONOS, INITIA, ASI, ARBETH, OPETH, BERA, OAS, COREDAO, XDC, WEMIX, MON, WORLD, IP, HYPEEVM, SONIC, XPL, KAVAEVM, SONEIUM, SOMI, FLR, SGB, APT, FLOW, HBAR, OFC.

"For example coin type as: sui, sui:deep and sui:suins" "From should be the Wallet ID from which you are trying to send the funds and To should be the Recipient Address, followed by amount, coin type and comment."

Scenario: sui-tokens-amounts-locked#eigen-employee-account-setup

Trigger: Employee grantee of a token project (e.g., Eigen Labs) cannot see tokens or encounters identity verification errors when setting up their custody account.

Signals: EIGEN, employee account, Eigen Labs FBO, identity verification, cannot create wallet, KYC, token unlock, grantee

Steps:

  1. Confirm the user has an existing BitGo account. They do not need to create a new wallet — they should switch to the "Eigen Labs FBO" Enterprise (or equivalent) where a wallet with their name should already exist.
  2. If the user receives a "User must complete identity verification first" error, send them a Persona KYC inquiry link (e.g., https://inquiry.withpersona.com/verify?code=<unique_code>). This must be completed before withdrawals are allowed.
  3. If the user's account is not configured to create wallets on the FBO Enterprise, inform them: "Your user account is not configured to allow you to create wallets on that Enterprise. If you wish to create wallets, you will need to create these on your own Enterprise."
  4. If the KYC link has expired, generate and send a new one.
  5. Once KYC is approved, confirm the user can proceed with withdrawals.

Notes: The KYC/identity verification requirement does not block the unlock itself but must be completed before the user can withdraw. Ensure the user checks spam for the inquiry email. This pattern applies to any FBO enterprise distribution (EIGEN, SUI employee grants, etc.).

"Hi Sara, Getting on a call will not help as this requires an update internally at our end which we should be able to complete today. This will not affect the unlock but needs to be settled before you can withdraw." "Your user account is not configured to allow you to create wallets on that Enterprise. If you wish to create wallets, you will need to create these on your own Enterprise."

Scenario: sui-tokens-amounts-locked#wealth-management-redirect

Trigger: Customer contacts standard BitGo support but their account is on BitGo Wealth Management (e.g., ZetaChain Wealth Management at zetachain.bitgowealthmanagement.com).

Signals: wealth management, zetachain.bitgowealthmanagement.com, HeightZero, Zeta Wealth Management, wrong support channel

Steps:

  1. Verify that the customer's account is on a Wealth Management platform (e.g., the URL https://zetachain.bitgowealthmanagement.com/).
  2. Redirect the customer to the appropriate support channel. For ZetaChain Wealth Management, direct them to contact the dedicated wealth management support email provided by their foundation representative.
  3. Standard BitGo support (support@bitgo.com) does not have access to Wealth Management account details and cannot assist with those accounts.

Notes: This applies to ZetaChain incentivized testnet rewards, validator token grants, and similar programs hosted on the Wealth Management platform.

"You will need to contact [EMAIL] for assistance with that site." "Upon checking, we see you have an account with Zeta Wealth Management. Could you please email [EMAIL] for further support? The support you have reached out is for the regular BitGo user accounts."

Scenario: sui-tokens-amounts-locked#zeta-address-format

Trigger: Customer receives an address error when trying to withdraw ZETA tokens to an external exchange.

Signals: ZETA, address error, destination address incorrect, zeta prefix, withdraw ZETA, OKX, Kraken, Coinbase

Steps:

  1. Verify the destination address format. ZETA addresses require a zeta prefix, not a standard 0x Ethereum-format address.
  2. Direct the customer to the ZetaChain address converter tool: https://www.zetachain.com/docs/reference/tools/address-converter/
  3. Advise the customer to check with the receiving exchange (e.g., Coinbase, OKX, Kraken) whether they accept ZETA deposits in the zeta-prefixed format.
  4. Recommend performing a small test transaction before sending the full amount.
  5. If the customer has forgotten their wallet passphrase, they can use their Keycard to reset it via wallet settings → "recover wallet password" option (the Keycard — not recovery codes — is required for this).

Notes: Recovery codes are only for login/2FA purposes and cannot be used for wallet recovery. The Keycard contains the encrypted backup key required for wallet password recovery. BitGo cannot assist with third-party exchange deposit procedures.

"Yes, the address needs to have the prefix zeta. You can use the following tool to convert the address: https://www.zetachain.com/docs/reference/tools/address-converter/" "Every BitGo wallet comes with a keycard, and this keycard is required for the recovery process. Recovery codes cannot be used as a replacement for the keycard."

Scenario: sui-tokens-amounts-locked#lock-api-token-balance-null

Trigger: Admin lock API call returns success but the lock is not visible in the UI, or the GET wallet balance API returns a NULL/empty balance despite tokens being present.

Signals: lock API, admin API, NULL balance, empty balances, lock not showing, TKM, ADMIN access token, bera:dolo, wallet lock

Steps:

  1. Confirm the lock API call was successful by reviewing the response (e.g., {"lockValue":"13760000000000000000000000"}).
  2. Check whether the GET balance API call is being made with the correct access token. The lock API uses an ADMIN access token; the balance API may use the investor's access token. Confirm the correct token is being used.
  3. If the balance API returns { balances: [] } despite an on-chain balance existing, this may be a token indexing issue. Escalate to engineering via Slack with the wallet ID, coin type, and API responses.
  4. Verify the lock is visible via BGA: bga w <wallet_id> and check for the lockedAmount in walletFlags.
  5. If the issue was resolved internally (e.g., via Slack), confirm resolution with the requester and close the ticket.

Notes: This pattern has been observed with newer tokens (e.g., DOLO on Berachain). The lock may be correctly applied at the backend but not reflected in the UI or balance API due to token support maturity.

"API POST Call: /api/v2/admin/wallet/[WALLET_ID]/lock Payload: {"walletId":"[WALLET_ID]","value":"[WALLET_ID]","currency":"bera:dolo"} Response: (success) {"lockValue":"13760000000000000000000000"}" "One notable item, when we run a GET wallet balance API call on the wallet it's returning a NULL value even though there is a balance in the wallet. Response: { balances: [] }"

Scenario: sui-tokens-amounts-locked#consolidate-after-unlock

Trigger: Customer's SUI tokens should be unlocked but are not appearing as available; consolidating the balance resolves the issue.

Signals: SUI, consolidate, balance not available, unlocked tokens not showing, consolidate balance

Steps:

  1. Advise the customer to consolidate the balance on their address through the BitGo UI.
  2. Navigate to the wallet and use the consolidation option available in the wallet interface.
  3. If the issue resolves after consolidation, no further action is needed.
  4. If it does not resolve, check the lockedAmount flag and proceed with the appropriate scenario above.

Notes: SUI uses an object-based model. Sometimes newly unlocked tokens need to be consolidated before they appear as spendable. This is a quick first step before deeper investigation.

"Could you please try consolidating the balance on your address through the UI."

Related

  • introduction-to-staking — Covers staking mechanics for SUI (locked-in-wallet model), unbonding periods for ZETA/EIGEN, and how staking interacts with locked balances.
  • types-of-policies-client-controlled-vs-bitgo-enforced — Explains video identity verification and selfie liveness check policies that apply to custody withdrawals after tokens are unlocked.
  • non-bitgo-recoveries — Relevant if a customer has lost their wallet passphrase and needs to use their Keycard for recovery (especially ZETA withdrawal scenarios).