The gas pump is Tatum's feature that helps you manage gas fees in a custodial application. When you use the gas pump, gas fees for any transaction made by your customers (users of your custodial application) are automatically deducted from the 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.
For more information about the gas pump, see our user documentation.
Each API related to the gas pump supports its own set of the blockchains. The list of the supported blockchains is provided in the API description further in this section.
2 credits per API call
Precalculate (generate) gas pump addresses that you can assign to the customers of your custodial application.
This API does not make any changes on the blockchain itself, just generates addresses that follow the blockchain's requirements for the address format; therefore, no gas fee is applied.
This API is supported for the following blockchains:
Address index
Each address should be associated with its own index. Use the from
and to
request body parameters to set a range of index values for the addresses to precalculate. You can start with any number, but we recommend that you start from 0.
In one API call, you can precalculate:
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.
The order in which the precalculated addresses are returned in the API response 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 arrray 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 ]
The owner of the gas pump addresses
The owner (also referred to as "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.
Activated and not activated addresses
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, activate them.
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "chain": "ETH",
- "owner": "0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD",
- "from": 0,
- "to": 1000
}
[- "0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea"
]
2 credits per API call
Activate the precalulated gas pump addresses. Activating a gas pump address allows this address to send funds to other addresses.
You can activate up to 270 addresses in one 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 in the from
and to
request body parameters) and then make another API call with the remaining 230 addresses.
When to activate a gas pump address
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. 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.
Depending on your business needs and requirements, you can choose when to activate the gas pump addresses. 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.
Alternatively, 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:
After you make an API call to activate gas pump addresses, use the API for getting the results of the address activation transaction.
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.
ActivateGasPumpTatum
. For example, if you are activating gas pump addresses on Ethereum and you use KMS, use the ActivateGasPumpKMS
schema.
ActivateGasPumpTatum
schema of the request body.
This API is supported for the following blockchains:
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "chain": "ETH",
- "owner": "0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD",
- "from": 0,
- "to": 200,
- "feesCovered": true
}
{- "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}
1 credit per API call
Get the results of the activation transaction after activating gas pump addresses.
If the activation transaction got recorded into a block, the API returns two arrays:
valid
, with the activated gas pump addressesinvalid
, with the gas pump addresses that for some reason did not get activated together with the reason whyIf the transaction is still being processed, the API returns an error message. In this case, repeat the call later.
This API is supported for the following blockchains:
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "valid": [
- {
- "index": 1,
- "address": "0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea"
}
], - "invalid": [
- {
- "address": "0x2b5a0bE5940B63dE1eDdCCCa7bd977357e2488eD",
- "reason": "Wallet already exists"
}
]
}
1 credit per API call
Check whether the gas pump address with a specified index is activated and can send funds to other addresses.
You can use this API when a customer initiates a fund transfer and you need to check whether their gas pump address is allowed to send funds.
This API is supported for the following blockchains:
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "activated": true
}
2 credits per API call
Transfer (send) an asset from a gas pump address to the other address.
This operation is usually performed by users in your custodial application: a user who has a gas pump address assigned wants to transfer an asset to some address on the blockchain.
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:
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.
This API is supported for the following blockchains:
Signing a transaction
When transferring an asset, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.
Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.
For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.
chain required | string The blockchain to work with |
custodialAddress required | string = 42 characters The gas pump address that transfers the asset; this is the address that you precalculated and activated earlier and that is assigned to a customer in your custodial application; this is not the "master address" |
recipient required | string = 42 characters The blockchain address that receives the asset |
contractType required | number The type of the asset to transfer. Set |
tokenAddress | string = 42 characters (Only if the asset is a fungible token, NFT, or Multi Token) The address of the token to transfer. Do not use if the asset is a native blockchain currency. |
amount | string^[+]?((\d+(\.\d*)?)|(\.\d+))$ (Only if the asset is a fungible token, Multi Token, or native blockchain currency) The amount of the asset to transfer. Do not use if the asset is an NFT. |
tokenId | string <= 256 characters (Only if the asset is a Multi Token or NFT) The ID of the token to transfer. Do not use if the asset is a fungible token or native blockchain currency. |
fromPrivateKey required | string = 66 characters The private key of the blockchain address that owns the gas pump address ("master address") |
nonce | number The nonce to be set to the transfer transaction; if not present, the last known nonce will be used |
object (CustomFee) The custom defined fee; if not present, will be calculated automatically | |
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "chain": "ETH",
- "custodialAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
- "recipient": "0xe242bA5456b782919AFc85687422eEA2cB73B5d3",
- "contractType": 0,
- "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
}
{- "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}
2 credits per API call
Transfer (send) multiple assets from a gas pump address to one or more addresses.
This operation is usually performed by users in your custodial application: a user who has a gas pump address assigned wants to transfer multiple assets to one or more addresses on the blockchain.
The gas fee for sending the assets 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 assets:
If you want to send only one asset, you can also use the API for transferring an asset from a gas pump account.
This API is supported for the following blockchains:
Signing a transaction
When transferring assets, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.
Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.
For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.
chain required | string The blockchain to work with |
custodialAddress required | string = 42 characters The gas pump address that transfers the assets; this is the address that you precalculated and activated earlier and that is assigned to a customer in your custodial application; this is not the "master address" |
recipient required | Array of strings The blockchain address that receives the assets |
contractType required | Array of numbers The type of the assets to transfer. Set |
tokenAddress required | Array of strings
|
amount required | Array of strings
|
tokenId required | Array of strings
|
fromPrivateKey required | string = 66 characters The private key of the blockchain address that owns the gas pump address ("master address") |
nonce | number The nonce to be set to the transfer transaction; if not present, the last known nonce will be used |
object (CustomFee) The custom defined fee; if not present, will be calculated automatically | |
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "chain": "ETH",
- "custodialAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
- "recipient": [
- "0xe242bA5456b782919AFc85687422eEA2cB73B5d3"
], - "contractType": [
- 0
], - "tokenAddress": [
- "0x782919AFc85eEA2cB736874225456bB5d3e242bA"
], - "amount": [
- "100000"
], - "tokenId": [
- "100000"
], - "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
}
{- "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}
2 credits per API call
Allow another blockchain address (the spender
parameter in the request body) to transfer the asset from a gas pump address on behalf of the master address.
Use this API when the customer using the gas pump address sells assets on a marketplace or auction. After the customer creates a listing of the asset, they have to allow the marketplace/auction smart contract to transfer the asset to the buyer after the asset has been bought.
The asset can be one of the following types:
This API is supported for the following blockchains:
Signing a transaction
When approving the transfer of an asset, you are charged a fee for the transaction, and you must sign the transaction with the private key of the blockchain address from which the fee will be deducted.
Providing the private key in the API is not a secure way of signing transactions, because the private key can be stolen or exposed. Your private keys should never leave your security perimeter. You should use the private keys only for testing a solution you are building on the testnet of a blockchain.
For signing transactions on the mainnet, we strongly recommend that you use the Tatum Key Management System (KMS) and provide the signature ID instead of the private key in the API. Alternatively, you can use the Tatum JavaScript client.
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "chain": "ETH",
- "custodialAddress": "0x687422eEA2cB73B5d3e242bA5456b782919AFc85",
- "spender": "0xe242bA5456b782919AFc85687422eEA2cB73B5d3",
- "contractType": 0,
- "tokenAddress": "0x782919AFc85eEA2cB736874225456bB5d3e242bA",
- "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2"
}
{- "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}
This API is deprecated.
To start with the gas pump, use the API for precalculating the gas pump addresses.
2 credits per API call
Generate new gas pump smart contract address on the blockchain. This address enables custodial providers to receive native assets, ERC20 / ERC721 / ERC1155 tokens on behalf of their customers on dedicated blockchain address, but in the same time it can initiate transfer of those assets away. Gas required for the transfer from that address is going to be deducted from the providers address - the one, which was used to generate the address on the blockchain.
This operation deploys a smart contract on the blockchain.
For paid plans, it is possible to pay for the gas costs - you don't have to provide private key or signatureId. Blockchain fees will be covered by your credits.
This API is supported for the following blockchains:
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "chain": "MATIC",
- "feesCovered": true,
- "batchCount": 270,
- "owner": "0x8cb76aed9c5e336ef961265c6079c14e9cd3d2ea"
}
{- "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}
This API is deprecated.
To start with the gas pump, use the API for precalculating the gas pump addresses.
If you built your gas pump solution using this API and the API for generating a gas pump wallet address, you can still use this API for creating more custodial addresses for your solution. However, we recommend that you switch to the API for precalculating the gas pump addresses.
2 credits per API call
Generate new gas pump smart contract address on the blockchain. It's possible to enable tokens, which should be detected and supported on that address. This address enables custodial providers to receive native assets, ERC20 / ERC721 / ERC1155 tokens on behalf of their customers on dedicated blockchain address, but in the same time it can initiate transfer of those assets away.
Gas required for the transfer from that address is going to be deducted from the providers address - the one, which was used to generate the address on the blockchain.
There are multiple options, how this address can be setup - it cannot be changed in the future:
All of these options could be enabled with a batch mode as well - in 1 transaction, it is possible to transfer multiple different assets from that address, e.g. ETH + USDC + ERC721 token. Without batch mode, 3 separate transaction must have been performed.
This operation deploys a smart contract on the blockchain. More assets you will support, more intial gas will be used for address creation. Batch mode adds more gas for every type.
This API is supported for the following blockchains:
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to perform the required operation due to a logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
{- "chain": "ETH",
- "fromPrivateKey": "0x05e150c73f1920ec14caa1e0b6aa09940899678051a78542840c2668ce5080c2",
- "enableFungibleTokens": false,
- "enableNonFungibleTokens": false,
- "enableSemiFungibleTokens": false,
- "enableBatchTransactions": false
}
{- "txId": "c83f8818db43d9ba4accfe454aa44fc33123d47a4f89d47b314d6748eb0e9bc9"
}
This API is deprecated.
To start with the gas pump, use the API for precalculating the gas pump addresses.
If you built your gas pump solution using the API for generating a gas pump wallet address and API for generating a custodial wallet address, you can still use this API for getting the custodial wallet address from the transaction. However, we recommend that you switch to the API for precalculating the gas pump addresses.
1 credit per API call
Get gas pump smart contract addresses from deploy transaction.
This API is supported for the following blockchains:
OK
Bad Request. Validation failed for the given object in the HTTP Body or Request parameters.
Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
Forbidden. The request is authenticated, but it is not possible to required perform operation due to logical error or invalid permissions.
Internal server error. There was an error on the server while processing the request.
[- "0xc21C81ef03f98898Fb155E00C364e8a7b9D158b8"
]