Creating End User Accounts: XRP and XLM

You can create Virtual Accounts (VA) for XRP and XLM chains in your VA ledger.

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

Steps

Step_1: Generate an XRP wallet

• v3 REST API endpoint
• Be mindful of Tatum Derivation Path.
• The response returns the parameter "address" that will work as the XPUB for your VA ledger. The parameter "secret" works as the "PrivateKey" to sign transactions.
• Example request:

curl --request GET \
  --url https://api.tatum.io/v3/xrp/account \
  --header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
  address: 'rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d', //Works as an XPUB
  secret: 'ssKPqjZ9VPg79rEsrHjydRLMM8xgG' //Required to sign transactions
}

import { Account, Currency, CreateAccount, createAccount } from "@tatumio/tatum";
import { config } from "dotenv";

config();

const createNewAccount = async () => {
  const createAccountData: CreateAccount = {
    currency: Currency.BTC,
    xpub: wallet.address
  };
  const accoun: Account = await createAccount(createAccountData);
  console.log(accoun);
};

createNewAccount();

❗️

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

Step_2: Create an XRP Virtual Account on the VA ledger

• v3 REST API endpoint
• You can generate XRP Virtual Accounts connected to the "address" (working as XPUB) and the "secret" 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 --request POST \
  --url https://api.tatum.io/v3/ledger/account \
  --header 'content-type: application/json' \
  --header 'x-api-key: {YOUR_API_KEY}' \
  --data '{
      "currency":"XRP",
      "xpub":"rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d",
      "customer":{
          "accountingCurrency":"USD",
          "customerCountry":"US",
          "externalId":"123654",
          "providerCountry":"US"
      },
      "compliant":false,
      "accountCode":"AC_1011_B",
      "accountingCurrency":"USD",
      "accountNumber":"123456"
}'
//Response:
{
  currency: 'XRP',
  active: true,
  balance: { 
    accountBalance: '0',
    availableBalance: '0'
  },
  frozen: false,
  xpub: 'rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d',
  accountingCurrency: 'USD',
  id: '61afba85997b887f543fa7f0' //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.
• With XRP and XLM, the "deposit address" is the same as the XPUB. User's deposits are identified via the parameter "destinationTag".
• Example request:

curl --request POST \
  --url 'https://api.tatum.io/v3/offchain/account/{Virtual_Account_ID}/address?index=1' \
  --header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
  xpub: 'rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d',
  derivationKey: 1,
  address: 'rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d',
  currency: 'XRP',
  destinationTag: 1
}

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.
• Virtual Accounts can only handle one (1) single currency per account.
• On XRP and XLM, you must freeze a specific amount of assets for each deposit address you create. If you are creating many deposit addresses this costs an absurd amount of money. For this reason, every Virtual Account uses the same deposit address, which is the same address as the wallet's XPUB.
• Virtual Accounts using XRP and XLM require users depositing to your Exchange or application to use the correct "destinationTag" (XRP) and "message" (XLM)
  • This is mandatory for VA Ledger to correctly identify the correct Account to credit the assets.
  • Deposits made without the destinationTag or message won't be credited.
• If you try to create an XRP or XLM virtual account with a different XPUB, or try to create a deposit address for a Virtual Account with a different XPUB, you will encounter the following error:
  JSON

  {
    errorCode: 'account.xpub.bnb',
    message: 'For BNB, XLM and XRP, only 1 xpub is allowed for API Key. For your ledger account, use already defined xpub and memo field for address differentiation. Please contact support at [email protected] if you need more.'
  }
  

  This is not a bug, it is the expected behavior and is telling you that you must use the same XPUB to create different Virtual Accounts and deposit addresses on the XRP blockchain.

🚧

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