How to connect a custom ERC-20 token to the ledger

Tatum Private Ledger 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 the private ledger. When you create your own virtual currency, you can create accounts and send ledger and blockchain transactions.

A virtual currency is an entity in the ledger's 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 the ledger 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 the ledger 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 the private ledger. You need to enter the symbol of the existing ERC-20, supply, which will be credited to the ledger account inside Tatum, 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
Response
Request
curl --location --request POST 'https://api-eu1.tatum.io/v3/offchain/ethereum/erc20' \
--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 ledger 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.

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
Response
Request
curl --location --request POST 'https://api-eu1.tatum.io/v3/offchain/ethereum/erc20/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 ledger account of your virtual currency and utilize all the instant feeless ledger 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 the ledger, 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 ledger virtual 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
Response
Request
curl --location --request POST 'https://api-eu1.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 ledger 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
Response
Request
curl --location --request GET 'https://api-eu1.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
Response
Request
curl --location --request POST 'https://api-eu1.tatum.io/v3/offchain/ethereum/erc20/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 ledger account of your virtual currency and utilize all the instant feeless ledger transactions.