Guides
SupportStatusSign UpLogin

Creating End User Accounts: EVM (like Ethereum)

How to create Virtual Accounts - EVM (Ethereum)

Suggest Edits

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

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

Steps

Step_1: Generate an Ethereum Wallet

curl --location --request GET 'https://api.tatum.io/v3/ethereum/wallet' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response
{
    "xpub": "xpub6EMcUVjBn8qrftjMxinPS34ebPPHATDPkYvmxhex9H8rmwE4dTaiW94c3rZzBbk55WFoSspYCyQRSkMmGzDjDdyJNUpqtwq1ZGCDC7dgtjC",
    "mnemonic": "heart piece harvest noodle maximum sunny panic urban remove cabin unfold clog feature bid veteran carry isolate common armor voyage shiver frown brown size" //Required to generate PrivateKeys
}

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 a Virtual Account, ETH-based, on the VA ledger

  • v3 REST API endpoint
  • You can generate ETH 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.
  • You can use ERC-20 Tokens as currency. Find the list of Supported Tokens in the following article.
  • 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": "ETH",
    "xpub": "xpub6EMcUVjBn8qrftjMxinPS34ebPPHATDPkYvmxhex9H8rmwE4dTaiW94c3rZzBbk55WFoSspYCyQRSkMmGzDjDdyJNUpqtwq1ZGCDC7dgtjC",
    "customer":{
        "accountingCurrency": "EUR",
        "externalId": "EX_CUST_1" // ID of customer in your Exchange Database
    }
}'
// Response
{
    "currency": "ETH",
    "active": true,
    "balance": {
        "accountBalance": "0",
        "availableBalance": "0"
    },
    "frozen": false,
    "xpub": "xpub6EMcUVjBn8qrftjMxinPS34ebPPHATDPkYvmxhex9H8rmwE4dTaiW94c3rZzBbk55WFoSspYCyQRSkMmGzDjDdyJNUpqtwq1ZGCDC7dgtjC",
    "customerId": "63889d0395bfe9fd220ffdf0", // TatumDB_Customer_ID
    "accountingCurrency": "EUR",
    "id": "63889d3c92c973e68550afd7" // 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 ETH Deposit Address for ETH Virtual_Account_ID: 63889d3c92c973e68550afd7
curl --location --request POST 'https://api.tatum.io/v3/offchain/account/63889d3c92c973e68550afd7/address' \
--header 'x-api-key: {YOUR_API_KEY}'
// Response
{
    "xpub": "xpub6EMcUVjBn8qrftjMxinPS34ebPPHATDPkYvmxhex9H8rmwE4dTaiW94c3rZzBbk55WFoSspYCyQRSkMmGzDjDdyJNUpqtwq1ZGCDC7dgtjC",
    "derivationKey": 1, // By default, just like for UTXO based chains, we start with index == 1 and skip index==0 as reserved.
    "address": "0xe29744c6de04d062e5785b2f35dc11e57610ab34",
    "currency": "ETH"
}

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.
  • 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.
  • 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 6 months ago