Links

Pay Gas Fees with Tatum Gas Pump

Learn how to set up a Gas Pump solution in your custodial application.
Gas Pump helps you manage gas fees in a custodial application: gas fees for any transaction made by your customers (users of your custodial application) are automatically deducted from a dedicated address (referred to as "master address") instead of the customer's address. This eliminates the need to send crypto to each customer's address to pay for gas fees.
Gas Pump supports the following blockchains:
  • BNB Smart Chain
  • Celo
  • Ethereum
  • Harmony
  • Klaytn
  • Polygon
  • TRON
You can review the smart contracts behind the Gas Pump implementation on our GitHub page:
The smart contracts are audited and certified by Certik: view the security assessment and check out Tatum on the Certic website.

How to set up Gas Pump in your application

To set up Gas Pump, complete the following steps:
If you set up a Gas Pump solution before September 27, 2022, check this article to see how the Gas Pump workflow changed.

Precalculate gas pump addresses

Gas pump addresses are the addresses that you are going to assign to the customers in your custodial application.
Precalculating a gas pump address means generating an address that follows the blockchain's requirements for the address format. At this point, no changes are made to the blockchain itself; therefore, no gas fee is applied.

Owner (master address)

When precalculating the addresses, you assign the owner (also referred to as "master address").
The owner, or the master address, is the blockchain address that will own the precalculated gas pump addresses. The owner will also be paying gas fees for operations made on the gas pump addresses. You have to make sure that the owner always has enough funds to cover these gas fees.

Address index

Each gas pump address should be associated with its own index. You can start with any number, but we recommend that you start from 0.
In one API call, you can precalculate:
  • Up to 4,000 addresses for Harmony
  • Up to 500 addresses for TRON
  • Up to 5,000 addresses for the other supported blockchains
If you need more addresses than one API call can precalculate, make several API calls. For example, if you need 10,000 addresses on Ethereum, make an API call with an index range from 0 through 4,999 and then make another API call with an index range from 5,000 through 9,999.

API for precalculating gas pump addresses

POST https://api.tatum.io/v3/gas-pump
You can find the complete information about this API, its parameters, and code samples in various languages in the API Reference.
The following sample request shows how to precalculate 1,000 gas pump addresses on Ethereum:
cURL
JavaScript
1
curl -i -X POST \
2
https://api.tatum.io/v3/gas-pump \
3
-H 'Content-Type: application/json' \
4
-H 'x-api-key: YOUR_API_KEY_HERE' \
5
-d '{
6
"chain": "ETH",
7
"owner": "0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD",
8
"from": 0,
9
"to": 999
10
}'
1
import { Currency, TatumApi} from "@tatumio/api-client"
2
const api = TatumApi('YOUR_API_KEY_HERE')
3
4
export async function ethBlockchainExample(){
5
const blockchainAddresses = await api.blockchain.gasPump.precalculateGasPumpAddresses({
6
chain: Currency.ETH,
7
owner: '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD',
8
from: 0,
9
to: 999,
10
});
11
}
12
13
ethBlockchainExample()
  • chain is the blockchain that you work with.
  • owner is the master address.
  • from and to set a range of index values for the addresses to precalculate.
The API returns an array of precalculated addresses:
1
[
2
"0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea",
3
"0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
4
"0xc5e336ef9612614e9cd3d2ea8cb76aed95c6079c",
5
...
6
]
The order in which the precalculated addresses are listed in the array is the order of the values in the index range, and the index values are assigned to the addresses accordingly. For example, you precalculated three gas pump addresses with a range of index values from 3 to 5. The first address in the returned array is assigned the index value "3", the second one - "4", and the third one - "5".
1
[
2
"0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea", // index is 3
3
"0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126", // index is 4
4
"0xc5e336ef9612614e9cd3d2ea8cb76aed95c6079c" // index is 5
5
]
The precalculated addresses can be immediately assigned to customers and can receive funds. However, they cannot be used to send funds to other addresses. This is because the addresses are not activated. To make the addresses be able to send funds, you activate them.

Activate the gas pump addresses

Activating a gas pump address allows this address to send funds to other addresses.

When to activate gas pump addresses

Because activating a gas pump address costs some amount of gas on a blockchain, you want to activate only those addresses that will be used for sending funds to other addresses.
Depending on your business needs and requirements, decide when to activate a gas pump address:
  • If you know that a gas pump address will not be used for sending funds, you can leave this address not activated. The customer who uses this address will still be able to receive funds.
  • If you know for sure that all the precalculated addresses will be sending funds, you can activate all the addresses right after they have been precalculated.
  • You can set up the activation in such a way so that a gas pump address gets activated only when a specific event is triggered. For example, you can activate a gas pump address:
    • When it receives an asset for the first time
    • When the customer tries to send an asset from this address for the first time

Max number of the addresses to activate

You can activate up to 270 addresses in one API call.
If you need to activate more than 270 addresses, make several API calls. For example, if you need to activate 500 addresses, make an API call with 270 addresses (set up the range of their index values accordingly) and then make another API call with the remaining 230 addresses.

Paying the gas fee for activating gas pump addresses

You can pay the gas fees for each activation transaction yourself, or Tatum can cover it for you.
  • When paying the gas fees yourself, you must sign the transaction with either the private key of the blockchain address from which you want to pay the fees or the signature ID of that private key (if you use Key Management System). To pay the fees yourself, use any schema of the API request body except for ActivateGasPumpTatum. For example, if you are activating gas pump addresses on Ethereum and you use KMS, use the ActivateGasPumpKMS schema.
  • If you want Tatum to cover the fees, use the ActivateGasPumpTatum API request body.
    • On the mainnet, you have to have a paid pricing plan. Tatum pays the fees from its own blockchain address. Then, the fee amount paid by Tatum is converted to the number of credits, and these credits are deducted from the monthly credit allowance of your paid pricing plan. The transaction fees and the corresponding numbers of credits deducted from your allowance vary depending on what blockchain you activate the addresses.
    • On the testnet, no credits are deducted from the monthly credit allowance. You can activate gas pump addresses regardless of your pricing plan.

API for activating gas pump addresses

POST https://api.tatum.io/v3/gas-pump/activate
You can find the complete information about this API, its parameters, and code samples in various languages in the API Reference.
The following sample request shows how to activate 100 gas pump addresses on Ethereum:
cURL
JavaScript
1
curl -i -X POST \
2
https://api.tatum.io/v3/gas-pump/activate \
3
-H 'Content-Type: application/json' \
4
-H 'x-api-key: YOUR_API_KEY_HERE' \
5
-d '{
6
"chain": "ETH",
7
"owner": "0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD",
8
"from": 0,
9
"to": 99,
10
"fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
11
}'
1
import { Currency, TatumApi } from "@tatumio/api-client"
2
const api = TatumApi('YOUR_API_KEY_HERE')
3
4
export async function ethBlockchainExample(){
5
const blockchainHash = await api.blockchain.gasPump.activateGasPumpAddresses({
6
from: 0,
7
to: 99,
8
chain: Currency.ETH,
9
owner: '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD',
10
fromPrivateKey: '0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2'
11
});
12
const addresses = await api.blockchain.gasPump.activatedNotActivatedGasPumpAddresses(Currency.ETH, blockchainHash.txId)
13
}
14
ethBlockchainExample()
  • chain is the blockchain that you work with.
  • owner is the master address.
  • from and to set a range of index values for the addresses to activate.
  • fromPrivateKey is the private key of the blockchain address from which you want to pay the activation fee.
The API returns the hash (ID) of the activation transaction:
1
{
2
"txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
3
}
Once you have the transaction ID, get the results of the address activation transaction.

Get the results of the address activation transaction

Get the results of the address activation transaction to verify that the gas pump addresses have actually been activated.

API for get the results of the address activation transaction

GET https://api.tatum.io/v3/gas-pump/address/{chain}/{txId}
You can find the complete information about this API, its parameters, and code samples in various languages in the API Reference.
The following sample request shows how to get the results of the address activation transaction on Ethereum:
cURL
JavaScript
1
curl -i -X GET \
2
'https://api.tatum.io/v3/gas-pump/address/ETH/c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9' \
3
-H 'x-api-key: YOUR_API_KEY_HERE'
1
import { TatumApi } from "@tatumio/api-client"
2
const api = TatumApi('YOUR_API_KEY_HERE')
3
export async function ethBlockchainExample(){
4
const trn = await api.blockchain.gasPump.activatedNotActivatedGasPumpAddresses(Currency.ETH, 'c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9')
5
console.log(trn)
6
}
7
ethBlockchainExample()
  • chain is the blockchain that you work with.
  • txId is the ID of the address activation transaction.
If the activation transaction got recorded into a block, the API returns two arrays:
  • valid, with the activated gas pump addresses
  • invalid, with the gas pump addresses that for some reason did not get activated together with the reason why
1
{
2
"valid": [
3
{
4
"address": "0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea",
5
"index": "0"
6
}
7
],
8
"invalid": [
9
{
10
"address": "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
11
"reason": "Wallet already exists"
12
}
13
]
14
}
If the transaction is still being processed, the API returns an error message. In this case, repeat the call later.

Send an asset from a gas pump address

Send (transfer) an asset from a gas pump address to the other address.
The gas fee for sending the asset will be covered by crypto funds on the master address. Make sure that the master address always has enough funds to cover gas fees.

Checking whether the gas pump is activated

To be able to send the asset, the gas pump address must be activated.
This check should be executed every time a customer initiates transfer of an asset from their gas pump address. You will learn how to check whether the gas pump address is activated in the next section further in this article.

API for sending an asset from a gas pump addresses

POST https://api.tatum.io/v3/blockchain/sc/custodial/transfer
You can find the complete information about this API, its parameters, and code samples in various languages in the API Reference.
With this API, you can send only one asset per API call. If you want to send multiple assets, use the API for transferring multiple assets from a gas pump account.
The following sample request shows how to send an NFT on Ethereum:
cURL
JavaScript
1
curl -i -X POST \
2
https://api.tatum.io/v3/blockchain/sc/custodial/transfer \
3
-H 'Content-Type: application/json' \
4
-H 'x-api-key: YOUR_API_KEY_HERE' \
5
-d '{
6
"chain": "ETH",
7
"custodialAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
8
"recipient": "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
9
"contractType": 1,
10
"tokenAddress": "0xe9cd3d2e6079c14e336ef96126a8cb76aed9c55c",
11
"tokenId": "84309234",
12
"fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
13
}'
1
import { Currency, prepareTransferFromCustodialWallet } from '@tatumio/tatum';
2
3
const body = {
4
chain: Currency.ETH,
5
custodialAddress: "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
6
recipient: "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
7
contractType: 1,
8
tokenAddress: "0xe9cd3d2e6079c14e336ef96126a8cb76aed9c55c",
9
tokenId: "84309234",
10
fromPrivateKey: "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
11
}
12
const transfer = prepareTransferFromCustodialWallet(false, body);
  • chain is the blockchain that you work with.
  • custodialAddress is the gas pump address that sends the NFT.
  • recipient is the blockchain address that receives the NFT.
  • contractType is the type of the asset to transfer; 1 means NFTs.
  • tokenAddress is the address of the NFT to send.
  • tokenId is the ID of the NFT to send.
  • fromPrivateKey is the private key of the "master address".
The API returns the hash (ID) of the transfer transaction:
1
{
2
"txId": "c33123d47a4f89d47b314d6748eb0e9bc9c83f8818db43d9ba4accfe454aa44f"
3
}

Check whether a gas pump address is activated

Only activated gas pump addresses can send funds to other blockchain addresses.
Every time a customer tries to send funds from their gas pump address, check whether their address is activated. If the address is not activated, you can choose to activate it right away and allow the customer to complete the transfer, or you can choose to reject the transfer request.

API for checking whether a gas pump address is activated

GET https://api.tatum.io/v3/gas-pump/activated/{chain}/{owner}/{index}
You can find the complete information about this API, its parameters, and code samples in various languages in the API Reference.
The following sample request shows how to check whether the gas pump address with the index of 12 is activated on Ethereum:
cURL
JavaScript
1
curl -i -X GET \
2
'https://api.tatum.io/v3/gas-pump/activated/ETH/0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD/12' \
3
-H 'x-api-key: YOUR_API_KEY_HERE'
1
import { TatumApi } from "@tatumio/api-client"
2
const api = TatumApi('YOUR_API_KEY_HERE')
3
export async function ethBlockchainExample(){
4
const state = await api.blockchain.gasPump.gasPumpAddressesActivatedOrNot('ETH', '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD', 12)
5
console.log(state)
6
}
7
ethBlockchainExample()
  • chain is the blockchain that you work with.
  • owner is the master address.
  • index is the index of the gas pump address to check.
The API returns the activated parameter. If it set to true, the gas pump address has been activated:
1
{
2
"activated": true
3
}