Pay Gas Fees with Tatum Gas Pump

Learn how to set up a Gas Pump solution in your custodial application.

As the owner of a custodial application (for example, a crypto exchange), every time you want to send assets from one of your user’s address, you have to calculate the gas fees, then send that amount to their address (a transaction that also incurs gas fees), and finally send the assets from their address. Two transactions incur gas fees and can result in minuscule differences of crypto "dust" remaining on user addresses. If you have thousands or millions of addresses, this method creates an enormous amount of work and fees for you as a custodial provider.

Gas Pump helps you manage gas fees in your custodial application in a more efficient way: gas fees for any transaction made by your customers 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 -i -X POST \
  https://api.tatum.io/v3/gas-pump \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "chain": "ETH",
    "owner": "0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD",
    "from": 0,
    "to": 999
  }'

import { Currency, TatumApi} from "@tatumio/api-client"
const api = TatumApi('YOUR_API_KEY_HERE')

export async function ethBlockchainExample(){
    const blockchainAddresses = await api.blockchain.gasPump.precalculateGasPumpAddresses({
        chain: Currency.ETH,
        owner: '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD',
        from: 0,
        to: 999,
    });
}

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:

[
  "0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea",
  "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
  "0xc5e336ef9612614e9cd3d2ea8cb76aed95c6079c",
  ...
]

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

[
  "0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea", // index is 3
  "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126", // index is 4
  "0xc5e336ef9612614e9cd3d2ea8cb76aed95c6079c"  // index is 5
]

You are now ready to assign the precalculated addresses to the customers in your custodial application.

Assign the precalculated addresses to customers

In your custodial application, assign the precalculated addresses to your customers. It is up to you how you implement the logic for assigning the addresses: you may want to assign an address to a customer once they create an account in the application, or they may need to perform additional steps to get an address assigned.

At this point, the precalculated addresses 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, 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 -i -X POST \
  https://api.tatum.io/v3/gas-pump/activate \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "chain": "ETH",
    "owner": "0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD",
    "from": 0,
    "to": 99,
    "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
}'

import { Currency, TatumApi } from "@tatumio/api-client"
const api = TatumApi('YOUR_API_KEY_HERE')

export async function ethBlockchainExample(){
    const blockchainHash = await api.blockchain.gasPump.activateGasPumpAddresses({
        from: 0,
        to: 99,
        chain: Currency.ETH,
        owner: '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD',
        fromPrivateKey: '0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2'
    });
    const addresses = await api.blockchain.gasPump.activatedNotActivatedGasPumpAddresses(Currency.ETH, blockchainHash.txId)
}
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:

{
  "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}

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 -i -X GET \
  'https://api.tatum.io/v3/gas-pump/address/ETH/c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

import { TatumApi } from "@tatumio/api-client"
const api = TatumApi('YOUR_API_KEY_HERE')
export async function ethBlockchainExample(){
    const trn = await api.blockchain.gasPump.activatedNotActivatedGasPumpAddresses(Currency.ETH, 'c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9')
    console.log(trn)
}
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

{
  "valid": [
    {
      "address": "0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea",
      "index": "0"
    }
  ],
  "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.

Implement a mechanism for sending an asset from a gas pump address

In your custodial application, implement a mechanism that allows your customers to send (transfer) an asset from their 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.

A gas pump address that transfers an asset must be the owner of this asset.

Only activated gas pump addresses can send assets to another addresses. Therefore, every time a customer initiates transfer of an asset from their gas pump address, your custodial application must perform the following steps:

Check whether the customer's address is activated. To implement this step, use the API for checking whether a gas pump address is activated.
Take one of the following actions depending on the check result:
- If the address is activated, proceed with transferring the asset. To implement this step, use the API for sending an asset from a gas pump address. NOTE: 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.
- If the address is not activated, set up a process for handling this situation: you may choose to activate the address right away and proceed with transferring the asset, or you may choose to reject the transfer request and ask the customer to complete additional actions.

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 -i -X GET \
  'https://api.tatum.io/v3/gas-pump/activated/ETH/0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD/12' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

import { TatumApi } from "@tatumio/api-client"
const api = TatumApi('YOUR_API_KEY_HERE')
export async function ethBlockchainExample(){
    const state = await api.blockchain.gasPump.gasPumpAddressesActivatedOrNot('ETH', '0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD', 12)
    console.log(state)
}
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:

{
  "activated": true
}

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 -i -X POST \
  https://api.tatum.io/v3/blockchain/sc/custodial/transfer \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "chain": "ETH",
    "custodialAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
    "recipient": "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
    "contractType": 1,
    "tokenAddress": "0xe9cd3d2e6079c14e336ef96126a8cb76aed9c55c",
    "tokenId": "84309234",
    "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
  }'

import { Currency, prepareTransferFromCustodialWallet } from '@tatumio/tatum';

const body = {
  chain: Currency.ETH,
  custodialAddress: "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
  recipient: "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126",
  contractType: 1,
  tokenAddress: "0xe9cd3d2e6079c14e336ef96126a8cb76aed9c55c",
  tokenId: "84309234",
  fromPrivateKey: "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
 }
const transfer = prepareTransferFromCustodialWallet(false, body);

chain is the blockchain that you work with.
custodialAddress is the gas pump address that sends the NFT. IMPORTANT! The gas pump address must be the owner of the NFT that it is sending.
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:

{
  "txId": "c33123d47a4f89d47b314d6748eb0e9bc9c83f8818db43d9ba4accfe454aa44f"
}

PreviousUse KMS to Store Private Keys and Sign Transactions on Solana NextBlockchain

Last updated 1 year ago