Generating a Deposit Address: Introduction

Once an End User Virtual Account is created, it is not yet synchronized with the blockchain. There is no blockchain address connected to it acting as a Deposit Address, but just the XPUB from your Master Exchange Wallet.

Steps

Step_1: Generate a Wallet

• This step should have been done while Setting up your Exchange or Application.
  • Example: BTC - v3 REST API endpoint
  • Retrieve the XPUB and store the Mnemonic.

Example request:

curl --location --request GET 'https://api.tatum.io/v3/bitcoin/wallet' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response
{
    "mnemonic": "method main swing charge hero theory eyebrow myself movie series silent camp proof tortoise electric rabbit good clip process always expect chase adult fee",
    "xpub": "tpubDFRtR6DexBRjtJAfGYMaLnNWRwz7h5pNXu8rX4wcYuH6xeXncMcTqPnUVqk8d86DmUHJeWJBxhK6vhFHMQr4eZhHkQvKxXYtgYKPPMjKwer"
}

Step_2: Create a Virtual Account (XPUB-based)

• UTXO chains (like Bitcoin)
• EVM chains (like Ethereum)

Step_3: Generate a deposit address for a Virtual Account (XPUB-based)

• v3 REST API endpoint

Example request:

• The XPUB will be taken from the Virtual_Account_ID.
• The Deposit Address will be generated by adding +1 to the "index", as seen in the response as "derivationKey"

//POST: https://api.tatum.io/v3/offchain/account/{id}/address
curl --location --request POST 'https://api.tatum.io/v3/offchain/account/{Virtual_Account_ID}/address' \
--header 'x-api-key: {testnet_API_KEY}'
// Response
{
    "xpub": "tpubDFRtR6DexBRjtJAfGYMaLnNWRwz7h5pNXu8rX4wcYuH6xeXncMcTqPnUVqk8d86DmUHJeWJBxhK6vhFHMQr4eZhHkQvKxXYtgYKPPMjKwer",
    "derivationKey": 1, //By default, it starts with index == 1, Index == 0 is reserved to act as a ChangeAddress when transferring out.
    "address": "tb1q2m35yvwlvrt4glqmlakepdd2jdanpe6nmc7wek", //This is the address your end user can use to deposit assets from outisde your Exchange or Application
    "currency": "BTC"
}

Step_4: The result is a blockchain address that has been connected to the VA

• Any incoming blockchain transaction to this address, which matches with the "currency" of the VA will be automatically synchronized to the ledger.

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 the VA Blockchain Operationsendpoints, 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.