VA - Creating End User Accounts: Gas Pump (EVM)

You can create Virtual Accounts (VA) for EVM-based chains (like Ehereum) based on a Gas Pump (GP) "Slave GP Contract Address". Additional details on GP are available at the following link.

Steps

1. Precalculate (generate) a "Slave GP Contract Address"

2. Create a Virtual Account, Token-based, on the VA ledger

  • v3 REST API endpoint
  • Find the list of supported tokens, by default at the following link.
  • You can generate a USDC Virtual Account connected intended to use with GP.
  • You can generate as many accounts as needed with different "Slave GP Contract Address".
  • Example request:
    curl -i -X POST \
      https://api.tatum.io/v3/ledger/account \
      -H 'Content-Type: application/json' \
      -H 'x-api-key: {YOUR_API_KEY}' \
      -d '{
        "currency": "USDC"
        "customer":{
           "accountingCurrency": "EUR",
            "externalId": "EX_CUST_1" // ID of customer in your Exchange Database
        }
      }'
    // Response
    {
        "currency": "USDC",
        "active": true,
        "balance": {
            "accountBalance": "0",
            "availableBalance": "0"
        },
        "frozen": false,
        "customerId": "63889d0395bfe9fd220ffdf0", // TatumDB_Customer_ID
        "accountingCurrency": "EUR",
        "id": "5fb7bdf6e96d9ab593e191a6" // Virtual_Account_ID
    }
    

3. Assign a "Slave GP Contract Address" as a Deposit Address for a Virtual Account

  • Find the steps to Assign the address at the following link.

  • You may assign the "Slave GP Contract Address" as a deposit address for the VA - This allows your end users to deposit from outside your Exchange or Application.

  • Example Request:
    The response confirms the GP address has been assigned to the virtual account. Any incoming blockchain transaction to this address, matching the currency, will be automatically detected and the VA balance will be updated.

    //Slave GP Contract Address: "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126" --> index == ## from GP Master Address - Track this index!
    //POST https://api.tatum.io/v3/offchain/v3/offchain/account/{id}/address/{address}
    curl -i -X POST \
      'https://api.tatum.io/v3/offchain/account/5fb7bdf6e96d9ab593e191a6/address/0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126' \
      -H 'x-api-key: {YOUR_API_KEY}'
    //Response:
    
    {
      "address": "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126", //This address assigned while assigned to this VA can only handle USDC_ETH from the ETH chain, exclusively
      "currency": "USDC"
    }
    

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 others. The parameter "externalId" is the identifier of your users in your database.
  • Virtual Accounts can only handle one (1) single currency per account.
  • It is strongly encouraged that a Virtual Account only holds one (1) single deposit address at a time.
  • Any existing assets already present on an address you assign won't be considered to update the VA balance.

🚧

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