Assign an external Address as a Deposit Address

Virtual Accounts support adding existing blockchain addresses as Deposit Addresses.

• You can add an address by using the following v3 REST API endpoint.
• The most common use is for EVM-based (like Ethereum) Gas Pump.

Example request:

curl --request POST \
  --url 'https://api.tatum.io/v3/offchain/account/{id}/address/{address}' \
  --header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
  address: '0x6d7abd9f164db455e5aabfb5a53307e8d5657555',
  currency: 'MATIC' // The currency will match the same as the Account
}

Good to Know

• Assigning a blockchain address to a Virtual Account created with an XPUB is impossible.
• Any on-chain assets already present in the blockchain address to bind to the Virtual Account will be ignored—more information HERE.

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.