SupportStatusDashboard

Creating End User Accounts: UTXO (like Bitcoin)

How to create Virtual Accounts - UTXO (BTC)

Suggest Edits

You can create Virtual Accounts (VA) for UTXO-based chains (like Bitcoin) in your VA ledger.

This guide walks over the steps to generate a "Master Exchange BTC Wallet" for your first Bitcoin-based Virtual Account.

Steps

Step_1: Generate a Bitcoin Wallet

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" //Required to generate PrivateKeys
}

❗️

Never share your mnemonic(s) and/or private key(s) with anyone. It is your responsibility to keep this information safe.

Step_2: Create a Virtual Account, BTC-based, on the VA ledger

  • v3 REST API endpoint
  • You can generate BTC Virtual Accounts connected to the XPUB of the mnemonic we got in the previous step.
  • You can generate as many accounts as needed, but they must all be connected to the same XPUB.
  • Example request:
curl --location --request POST 'https://api.tatum.io/v3/ledger/account' \
--header 'x-api-key: {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "currency": "BTC",
    "xpub": "tpubDFRtR6DexBRjtJAfGYMaLnNWRwz7h5pNXu8rX4wcYuH6xeXncMcTqPnUVqk8d86DmUHJeWJBxhK6vhFHMQr4eZhHkQvKxXYtgYKPPMjKwer",
    "customer":{
        "accountingCurrency": "EUR",
        "externalId": "EX_CUST_1" // ID of customer in your Exchange Database
    }
}'
// Response
{
    "currency": "BTC",
    "active": true,
    "balance": {
        "accountBalance": "0",
        "availableBalance": "0"
    },
    "frozen": false,
    "xpub": "tpubDFRtR6DexBRjtJAfGYMaLnNWRwz7h5pNXu8rX4wcYuH6xeXncMcTqPnUVqk8d86DmUHJeWJBxhK6vhFHMQr4eZhHkQvKxXYtgYKPPMjKwer",
    "customerId": "63889d0395bfe9fd220ffdf0", // TatumDB_Customer_ID
    "accountingCurrency": "EUR",
    "id": "63889d0295bfe9fd220ffdef" // Virtual_Account_ID 
}

Step_3: Create a Deposit Address for a Virtual Account

  • v3 REST API endpoint
  • You may create a deposit address for each VA - This allows your end users to deposit from outside your Exchange or Application.
  • Deposit addresses MUST be generated from the XPUB of the mnemonic generated in the first step.
  • Example request:
//Generate BTC Deposit Address for BTC Virtual_Account_ID: 63889d0295bfe9fd220ffdef
curl --location --request POST 'https://api.tatum.io/v3/offchain/account/63889d0295bfe9fd220ffdef/address' \
--header 'x-api-key: {YOUR_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"
}

Good to Know

  • Virtual Accounts should be assigned to "customers" at creation. The "customer" inside the VA ledger is an entity containing information about your application's user, such as the customer's country of residence, accounting currency, and other. The parameter "externalId" is the identifier of your users in your database.
  • When generating an XPUB, it is recommended not to use the address from "index" = "0". This address is reserved to act as ChangeAddress for UTXO-based transactions.
  • Virtual Accounts can only handle one (1) single currency per account.
  • All Virtual Accounts within the ledger should use the same Mnemonic and XPUB. If your Virtual Accounts use different mnemonics and XPUBs, you will face breaking issues when withdrawing assets all the while trying to reconcile Bookkeeping.
    • UTXO blockchains are capable of performing multiple transactions at once.
    • If Virtual Accounts are generated from different XPUBs, tracking which assets are sent from which wallet is impossible.
    • If you generate Virtual Accounts from different XPUBs, you won't be able to perform instant transactions between them. Only virtual accounts generated from the same XPUB will be able to perform transactions with one another.

🚧

For Mainnet and/or a Production Environment, it is recommended to use KMS.

Updated about 1 month ago