How to connect a custom ERC-20 token to a virtual account

Tatum Virtual Accounts can support any existing or new ERC-20 token which is not included out of the box. To support your own ERC-20 token and utilize all the off-chain features, you must create your own virtual currency inside a virtual account. When you create your own virtual currency, you can create accounts and send virtual account and blockchain transactions.

pageHow to create an ERC-20 token

A virtual currency is an entity in the virtual account distributed database. It is created with an initial supply of coins. This supply can be extended or reduced at any time.

Every virtual currency inside virtual accounts is pegged to a currency from the outside world. It can be a blockchain asset or fiat currency. This means that one unit of the virtual currency is equal to one unit of the pegged currency.

When you create a virtual currency MY_OWN_TOKEN with the base pair USD, 1 MY_OWN_TOKEN = 1 USD, you can set your custom base rate, e.g., 1 MY_OWN_TOKEN = 2 USD with the base rate 2.

When you want to connect a custom ERC-20 token to virtual accounts and utilize off-chain features, there are two scenarios:

• You want to connect an existing ERC-20 token to Tatum.

• You want to create your own ERC-20 token and connect it to Tatum.

Connecting an existing ERC-20 token

If you want to support an existing ERC-20 token, you only need to create a virtual currency representing the ERC-20 token inside virtual accounts. You need to enter the symbol of the existing ERC-20, supply, which will be credited to the virtual account inside Tatum, a base pair, and the blockchain address where the initial supply was transferred. Let's use the Tatum Test Token, an ERC-20 token issued for testing purposes by Tatum.

Request

curl --location --request POST 'https://api.tatum.io/v3/offchain/token/ETH' \
--header 'x-api-key: YOUR_API_KEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "symbol": "TTT",
    "supply": "100000",
    "description": "Tatum Test Token",
    "basePair": "USD",
    "decimals": 18,
    "address": "0x04978af26e756521cb4b2b7b2a09595e9d90b9cc"
}'

Response

{
    "accountId": "5fbe5cf150e53a37ec36a3c8",
    "address": "0x04978af26e756521cb4b2b7b2a09595e9d90b9cc"
}

The call's result is the virtual account's ID, with an account balance of the supply at the blockchain address. The account is frozen unless the virtual currency is connected to a specific ERC-20 on the blockchain.

pageOff-chain

To unfreeze the account and connect the virtual currency to a blockchain ERC-20 token, you need to provide the address of the ERC-20 token and the name of the virtual currency.

Request

curl --location --request POST 'https://api.tatum.io/v3/offchain/token/TTT/0xb3858430b7ed404747b9561027d2c01a72610f43' \
--header 'x-api-key: YOUR_API_KEY '

Response

{
    "accountId": "5fbe5cf150e53a37ec36a3c8",
    "address": "0x04978af26e756521cb4b2b7b2a09595e9d90b9cc"
}

The request does not have any response when successful. Internally, it will unfreeze the account created in the previous step and start the automatic synchronization of incoming transactions for connected accounts and addresses. It is also possible to create a virtual account of your virtual currency and utilize all the instant feeless virtual account transactions.

Creating and connecting a new ERC-20 token

In this step, you will create a new ERC-20 on the blockchain, create a virtual currency in virtual accounts, and connect this virtual currency to the instance of the ERC-20 token. This can be done using two API calls. In the first call, you both deploy your ERC-20 token and create the virtual account currency.

Blockchain transactions are signed using a private key via API, which is not a secure way of signing transactions. Your private keys and mnemonics should never leave your security perimeter. To correctly and securely sign a transaction, you can use Tatum CLI from the command line, a specific language library like Tatum JS, the local middleware API, or our complex key management system, Tatum KMS.

Request

curl --location --request POST 'https://api.tatum.io/v3/offchain/ethereum/erc20/deploy' \
--header 'x-api-key: YOUR_API_KEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "symbol": "TestToken",
    "supply": "100000",
    "description": "Tatum Test Token",
    "basePair": "USD",
    "address": "0x28cbeb0681bca9a07165c98cdb05051Fdf7Dc3F3",
    "privateKey": "0xd3d46d51fa3780cd952821498951e07307dfcfbbf2937d1c54123d6582032fa6"
}'

Response

{
    "txId": "0x0683895306bdb35845c90b2899db79b0f6761c12686554f044113589c6002c0e",
    "accountId": "5fbeba90075c0a37e4b50950"
}

The call's result is the virtual account's ID, with an account balance of the supply at the blockchain address. The account is frozen unless the virtual currency is connected to a specific ERC-20 on the blockchain. The second property is the transaction ID of the blockchain transaction that created the ERC-20 token. To obtain the contract address, you need to get the details of the transaction. You can see the property contractAddress, which is the address of the ERC-20 token.

Request

curl --location --request GET 'https://api.tatum.io/v3/ethereum/transaction/0x0683895306bdb35845c90b2899db79b0f6761c12686554f044113589c6002c0e' \
--header 'x-api-key: YOUR_API_KEY'

Response

{
    "blockHash": "0x7b1eeb0c628be04d835dcc7ec90e3816c8a5e64e9eb7737ac3e5da5797459a97",
    "blockNumber": 9140796,
    "contractAddress": "0x5a14C4ebc2e20eEB820C5197fc408a3CB9E27B75",
    "gas": 1527567,
    "gasPrice": "30000000000",
    "gasUsed": 1527567,
    ...
    ...
}

To unfreeze the account and connect the virtual currency to a blockchain ERC-20 token, you need to provide the address of the ERC-20 token and the name of the virtual currency.

Request

curl --location --request POST 'https://api.tatum.io/v3/offchain/token/TestToken/0x5a14C4ebc2e20eEB820C5197fc408a3CB9E27B75' \
--header 'x-api-key: YOUR_API_KEY '

Response

{
    "accountId": "5fbe5cf150e53a37ec36a3c8",
    "address": "0x04978af26e756521cb4b2b7b2a09595e9d90b9cc"
}

The request does not have any response when successful. Internally, it will unfreeze the account created in the previous step and start the automatic synchronization of incoming transactions for connected accounts and addresses. It is also possible to create a virtual account of your virtual currency and utilize all the instant feeless virtual account transactions.