Guides
SupportStatusSign UpLogin

Troubleshooting Virtual Account Withdrawals

Suggest Edits

Tatum's Virtual Accounts (VAs) offer a streamlined approach to managing off-chain transactions.

However, it is imperative to adhere to the prescribed methods for withdrawals to ensure consistency between the VA ledger and on-chain balances.

This guide consolidates essential troubleshooting steps and best practices to address common issues encountered during VA withdrawals.

Key Principles

  • Exclusive Use of VA Endpoints:
    All withdrawals must be registered and executed through VA-specific endpoints. Utilizing standard blockchain transaction endpoints or methods to sign a transaction from a linked deposit address within a VA bypasses the VA ledger, leading to ledger discrepancies. If this happens, the withdrawal must be manually registered.

  • On-Chain Balance Supremacy:
    The blockchain's on-chain balance is the definitive record. The VA ledger serves as an abstraction; therefore, any inconsistencies must defer to the on-chain balance.

Common Issues and Resolutions

1. Withdrawal Failures Due to Insufficient Funds

Symptom: Encountering errors such as:

{
  "statusCode": 403,
  "errorCode": "btc.tx.preparation",
  "message": "Transaction preparation failure.",
  "cause": "Not enough coins on addresses to perform this transaction"
}

Potential Causes

  • Discrepancy Between VA and On-Chain Balances
    Withdrawals made outside the VA endpoints (e.g., /v3/bitcoin/transaction) do not update the VA ledger, causing mismatches. This breaks the VA ledger.
  • Unspent Transaction Outputs (UTXOs) Insufficient for Requested Amount
    On UTXO-based blockchains like Bitcoin and Litecoin, transactions must be constructed using available UTXOs. If there aren’t enough UTXOs available, the transaction will fail.
  • Manual Withdrawals Not Registered in the VA Ledger
    If a manual withdrawal was made directly via an on-chain transaction, bypassing the VA ledger, the VA ledger must be updated accordingly. Find the guide on how to Register a Manual Withdrawal HERE

Resolution Steps

  1. Verify Balances
    • Use the /v3/ledger/account/{id} endpoint to verify the currency, balance and more.
      • accountBalance: All assets on the account, both available and blocked
      • availableBalance: The account balance minus the blocked assets; use the available balance to determine how much a customer can send or withdraw from their Virtual Account
    • Use the /v3/offchain/account/{id}/address endpoint to identify the associated blockchain deposit address(es).
      • Verify the on-chain balance of this address using a blockchain explorer.
  2. Retrieve Transactions & Withdrawals within the VA ledger
    • Follow the steps mentioned in the following article and verify that all transactions were properly recorded in your VA ledger and the VA you have issues with.
  3. Verify Blocked Amounts
  4. Check for any Withdrawals stuck inProgress
  5. Manually Register Withdrawals in VA Ledger
    • If funds were withdrawn outside the VA system, manually register these withdrawals in the VA ledger to synchronize balances.
    • Follow the Creating a Manual Withdrawal guide.
  6. Alternatively, Create a Fake Withdrawal and Delete the VA
    • If reconciling the VA ledger is not possible, you may create a fake withdrawal and then delete the Virtual Account. Follow the VA Deletion Guide.
    • You may transfer the on-chain funds to another address of your choice.
  7. Utilize Correct Withdrawal Endpoints

2. Withdrawal Registered in Ledger but Failed On-Chain

Symptom

A withdrawal appears in the VA ledger but did not successfully execute on the blockchain.

Potential Causes

  • Transaction Dropped or Failed
    The blockchain transaction associated with the withdrawal did not confirm due to low fees, network congestion, or incorrect signatures.
  • Network-Specific Issues
    Some blockchains require specific conditions for withdrawals, such as minimum gas fees.

Resolution Steps

  1. Cancel the Withdrawal in the VA Ledger
  2. Delete the Withdrawal Record

3. TRON-Specific Withdrawal Errors

Symptom

Encountering offchain.tron.tx.failed errors during TRON withdrawals.

Potential Causes

  • Unactivated TRON Address
    The destination address has not been activated on the TRON network. TRON addresses require a minimum balance of 0.1 TRX to be activated.
  • Incorrect Signature or Private Key
    If using KMS, the withdrawal may fail due to mismatched signature IDs or private keys.

Resolution Steps

  1. Activate the Address
  2. Verify Private Key Alignment
  3. Confirm that the private key used matches the deposit address from which the withdrawal is initiated.

Best Practices

  • Consistent Use of VA Endpoints
    Always process deposits and withdrawals through VA-specific endpoints to maintain ledger integrity.
  • Regular Balance Audits
    Periodically compare VA ledger balances with on-chain balances to identify and rectify discrepancies promptly.
  • Stay Updated
    Make sure Tatum KMS and other tools are in their latest versions to benefit from improvements and fixes.
  • Off-chain Transfers from a Virtual Account to Blockchain require the proper use of a combination of mnemonic, xpub, index, and PrivateKey via a match dictated by the REQUEST BODY SCHEMA
  • Ensure the blockchain fees are sufficient for the transaction to be accepted on-chain. Tatum provides fee estimate for a few chains: VA Specific for BTC, LTC and DOGE as well as for other chains

Important

The intended use case for Virtual Accounts (VA) is as a Self-Custodial Exchange, meaning all withdrawals are expected to be tracked in the VA ledger.

  • Tatum does not hold custody of mnemonics or private keys. As a result, it is technically possible to sign transactions using VA ledger deposit addresses outside the VA ledger and Tatum endpoints. For more details, refer to this article.
  • The blockchain’s on-chain balance takes precedence over the VA ledger. If unregistered transactions occur, the VA ledger will become misaligned, leading to liquidity inconsistencies between the on-chain balance and the off-chain VA ledger.
  • Virtual Accounts are designed to hold a limited number of deposit addresses (1-5). While adding many more deposit addresses may appear functional, this setup often leads to unrecoverable synchronisation issues across users over time.
  • Any on-chain assets already present in a blockchain address to bind to a Virtual Account will be ignored. More information HERE.
  • Deposits are only "recognized" as long as the "currency" of the VA matches the on-chain asset deposited
  • If a mistake occurs when creating or storing a withdrawal in the VA ledger, it can be deleted and retried. Check this article for addtional details.
  • Withdrawals from a VA deposit address can be automated using VA Blockchain Operations endpoints, ensuring they are properly logged in the VA ledger.

🚧

Attention

  • You are expected to hold 1:1 asset liquidity between the VA off-chain ledger and your end-users on-chain assets.
  • To avoid potential disruptions and ensure consistent performance, we recommend adhering to the intended usage of 1-5 deposit addresses per Virtual Account.
  • Be mindful of Tatum Derivation Path.

❗️

Warning

  • All withdrawals must be registered and executed through VA-specific endpoints.
  • Using standard blockchain transaction methods to sign and broadcast a transaction from a VA-linked deposit address bypasses the VA ledger, leadings to balance discrepancies. If this happens, the withdrawal must be manually registered.

Updated 8 days ago