Tatum
Search…
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
  • Ethereum
  • 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.

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.

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.

When precalculating the addresses, you assign the owner (also referred to as "master address").
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.

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 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.

POST https://{your-region}.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 code snippet shows how to precalculate 1,000 gas pump addresses on Ethereum with an EU API key:
cURL
JavaScript
1
curl -i -X POST \
2
https://api-eu1.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
const resp = await fetch(
2
`https://api-eu1.tatum.io/v3/gas-pump`,
3
{
4
method: 'POST',
5
headers: {
6
'Content-Type': 'application/json',
7
'x-api-key': 'YOUR_API_KEY_HERE'
8
},
9
body: JSON.stringify({
10
chain: 'ETH',
11
owner: '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD',
12
from: 0,
13
to: 999
14
})
15
}
16
);
17
​
18
const data = await resp.json();
19
console.log(data);
  • 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:
[
"0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea",
"0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
...
]
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.

Activating a gas pump address allows this address to send funds to other 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

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.

POST https://{your-region}.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 code snippet shows how to activate 100 gas pump addresses on Ethereum with an EU API key and using KMS:
cURL
JavaScript
1
curl -i -X POST \
2
https://api-eu1.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
"signatureId": "26d3883e-4e17-48b3-a0ee-09a3e484ac83"
11
}'
1
const resp = await fetch(
2
`https://api-eu1.tatum.io/v3/gas-pump/activate`,
3
{
4
method: 'POST',
5
headers: {
6
'Content-Type': 'application/json',
7
'x-api-key': 'YOUR_API_KEY_HERE'
8
},
9
body: JSON.stringify({
10
chain: 'ETH',
11
owner: '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD',
12
from: 0,
13
to: 99,
14
signatureId: '26d3883e-4e17-48b3-a0ee-09a3e484ac83'
15
})
16
}
17
);
18
​
19
const data = await resp.json();
20
console.log(data);
  • 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.
  • signatureId is the KMS identifier of the private key of the blockchain address from which you want to pay the activation fee.
The API returns the ID of the activation transaction:
{
"txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}
Once you have the transaction ID, 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.

GET https://{your-region}.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 code snippet shows how to get the results of the address activation transaction on Ethereum with an EU API key:
cURL
JavaScript
1
curl -i -X GET \
2
'https://api-eu1.tatum.io/v3/gas-pump/address/ETH/c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9' \
3
-H 'x-api-key: YOUR_API_KEY_HERE'
1
const chain = 'ETH';
2
const txId = 'c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9';
3
const resp = await fetch(
4
`https://api-eu1.tatum.io/v3/gas-pump/address/${chain}/${txId}`,
5
{
6
method: 'GET',
7
headers: {
8
'x-api-key': 'YOUR_API_KEY_HERE'
9
}
10
}
11
);
12
​
13
const data = await resp.text();
14
console.log(data);
  • 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
{
"valid": [
"0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea"
],
"invalid": [
{
"address": "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
"reason": "Wallet already exists"
}
]
}
If the transaction is still being processed, the API returns an error message. In this case, repeat the call later.

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.

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.

POST https://{your-region}.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 code snippet shows how to send an NFT on Ethereum with an EU API key:
cURL
JavaScript
1
curl -i -X POST \
2
https://api-eu1.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
const resp = await fetch(
2
`https://api-eu1.tatum.io/v3/blockchain/sc/custodial/transfer`,
3
{
4
method: 'POST',
5
headers: {
6
'Content-Type': 'application/json',
7
'x-api-key': 'YOUR_API_KEY_HERE'
8
},
9
body: JSON.stringify({
10
chain: 'ETH',
11
custodialAddress: '0x687422eEA2cB73B5d3e242bA5456b782919AFc85',
12
recipient: '0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126',
13
contractType: 1,
14
tokenAddress: '0xe9cd3d2e6079c14e336ef96126a8cb76aed9c55c',
15
tokenId: '84309234',
16
fromPrivateKey: '0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2'
17
})
18
}
19
);
20
​
21
const data = await resp.json();
22
console.log(data);
  • 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 ID of the transfer transaction:
{
"txId": "c33123d47a4f89d47b314d6748eb0e9bc9c83f8818db43d9ba4accfe454aa44f"
}

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.

GET https://{your-region}.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 code snippet shows how to check whether the gas pump address with the index of 12 is activated on Ethereum with an EU API key:
cURL
JavaScript
1
curl -i -X GET \
2
'https://api-eu1.tatum.io/v3/gas-pump/activated/ETH/0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD/12' \
3
-H 'x-api-key: YOUR_API_KEY_HERE'
1
const chain = 'ETH';
2
const owner = '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD';
3
const index = '12';
4
const resp = await fetch(
5
`https://api-eu1.tatum.io/v3/gas-pump/activated/${chain}/${owner}/${index}`,
6
{
7
method: 'GET',
8
headers: {
9
'x-api-key': 'YOUR_API_KEY_HERE'
10
}
11
}
12
);
13
​
14
const data = await resp.text();
15
console.log(data);
  • 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:
{
"activated": true
}
Copy link
On this page
How to set up Gas Pump in your application
Precalculate gas pump addresses
Owner (master address)
Address index
API for precalculating gas pump addresses
Activate the gas pump addresses
When to activate gas pump addresses
Max number of the addresses to activate
API for activating gas pump addresses
Get the results of the address activation transaction
API for get the results of the address activation transaction
Send an asset from a gas pump address
Checking whether the gas pump is activated
API for sending an asset from a gas pump addresses
Check whether a gas pump address is activated
API for checking whether a gas pump address is activated