GP - Setting Up Gas Pump from A to Z

The Basics

Master GP Address:

• You select a blockchain address to work as your "Master GP Address". You must own the PrivateKey.
• "Master GP Address" is the blockchain address that will own the precalculated "Slave GP Contract Addresses"
• "Master GP Address" pays all the gas fees for operations made by "Slave GP Contract Addresses".

Slave GP Contract Address:

• Smart Contract based address
• If just precalculated, the address can only be used to deposit assets.
• Transferring out requires activating the address.

❗️

Gas Pump is a Smart Contract Chain dependant. An activated "Slave GP Contract Address" in for example the ETH chain won't work to transfer out assets from another chain.

Address index:

• Each "Slave GP Contract Addresses" is associated with its own index.
• You can start with any number, but we recommend that you start from zero (0).
  • If 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".
• We strongly encourage users to track these addresses as well as their index.
  JSON

  [
    "0x3cb76aed9c5e336ef961265c6079c14e9cd3d125", // index == 3
    "0x2c6079c14e9cd3d2ea8cb76aed9c5e336ef96586", // index == 4
    "0xf5e336ef9612614e9cd3d2ea8cb76aed95c6087c"  // index == 5
  ]
  

Precalculating limits:

• Up to 4,000 addresses for Harmony, in one call
• Up to 500 addresses for TRON, in one call
• Up to 5,000 addresses for the other supported blockchains, in one call

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.

Steps

📘

The following steps and examples are based on Ethereum Sepolia (testnet).

Step_1: Precalculate Gas Pump (GP) addresses

• v3 REST API endpoint
• GP addresses are "Slave GP Contract Addresses" that you can assign to End-users 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 fees apply.

Example request:

• The API returns an array of precalculated addresses.
• 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.

//POST https://api.tatum.io/v3/gas-pump
curl --location 'https://api.tatum.io/v3/gas-pump' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
    "chain": "ETH",
    "owner": "0xc1eb70a67e8fd5ff1863c22d4f2856cc7953a7d2", //Your "Master GP  Address"
    "from": 0,
    "to": 3
}'
//Response:
[
    "0x73b10492E49B7Ce4cc8dD7F80F38147Ad8DA5Bdf", // index == 0
    "0xbF7b8Ce8f5379E27E679918Aa2fef37f42981804", // index == 1
    "0xfcB4d6A7D0c25477662b52c4E9FC58D67Ed9f2a1", // index == 2
    "0xfac0FcB92279DcA2C4EA5A9AFc21d5D7975B5554"  // index == 3
]

Step_2: Assign the precalculated addresses to customers

• For Virtual Accounts, find the article Adding an external Address as Deposit Address
• In your custodial application, you may assign the precalculated "Slave GP Contract Addresses" to your End-users.
• 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 able to send funds, you need to activate them.

Step_3: Activating a "Slave GP Contract Address"

• v3 REST API endpoint
• Activating a "Slave GP Contract Addresses" has a cost in gas fees. Therefore, you may want to activate only those addresses that are going to be used for sending funds to other addresses.
• Considerations:
  • If you know that a gas pump address will not be used for sending funds, you can leave this address not activated. The end user using this address will still be able to deposit funds.
  • If you know that all the precalculated addresses will be sending funds immediately, you can activate all the addresses right after they have been precalculated.
  • You can set up the activation in such a way that a "Slave GP Contract Addresses" gets activated only when a specific event is triggered. For example:
    • When it receives an asset for the first time
    • When a End-user tries to send assets from his "Slave GP Contract Addresses" for the first time
• Paying the activation gas fees:
  You can pay the gas fees for each activation transaction yourself, or Tatum can cover it for you.
  • 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 KMS).
  • Tatum pays the gas fees for you: use Request Body Scema ActivateGasPumpTatum with parameter "feesCovered" == true"
    • Mainnet: you must have a paid plan. Tatum pays the fees from our own blockchain address. Then, the fee amount paid by Tatum is converted to credits, and these credits are charged to your paid plan. The transaction fees and the corresponding numbers of credits deducted from your allowance vary depending on what blockchain you activate the addresses.
    • Testnet: no credits are deducted from the monthly credit allowance.

🚧

Activating a "Slave GP Contract Address" is a Smart Contract deployment charged via Gas Fees. The more addresses you activate, the more deployments you make and the higher the total cost, even if you activate them all at once.

Example request:

• Returns the hash (ID) of the activation transaction.

//POST https://api.tatum.io/v3/gas-pump/activate
curl --location 'https://api.tatum.io/v3/gas-pump/activate' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
    "chain": "ETH",
    "owner": "0xc1eb70a67e8fd5ff1863c22d4f2856cc7953a7d2", // Your "Master GP Address"
    "from": 0, //From which index we start to activate "Slave GP Contract Addresses"
    "to": 0,
    "fromPrivateKey": "####" // Your "Master GP Address" PrivateKey
}'
//Response:

{
    "txId": "0xc741a8e681d03d115c856a7454e9b28f9c1a808c97bed8ca52b096f3b25deea9"
}

Step_4: Get the results of the address activation transaction

• v3 REST API endpoint
• Get the results of the address activation transaction to verify that the gas pump addresses have successfully been activated.

Example request:

• If the transaction is still being processed, the response will be an error message. Repeat the call later.
• 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

// GET https://api.tatum.io/v3/gas-pump/address/{chain}/{txId}
curl --location 'https://api.tatum.io/v3/gas-pump/address/ETH/0xc741a8e681d03d115c856a7454e9b28f9c1a808c97bed8ca52b096f3b25deea9' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
    "valid": [
        {
            "address": "0x73b10492E49B7Ce4cc8dD7F80F38147Ad8DA5Bdf",
            "index": 0
        }
    ],
    "invalid": []
}

Step_5: Check if a "Slave GP Contract Address" is activated (optional)

• v3 REST API endpoint
• When in doubt, it's possible to check if a specific "Slave GP Contract Address" was activated.
• You must know the "index". If you don't, you may precalculate addresses until you find it again.

Example request:

• Returns the activated parameter. If it set to true, the "Slave GP Contract Address has been activated.

//GET https://api.tatum.io/v3/gas-pump/activated/{chain}/{owner}/{index}
curl --location 'https://api.tatum.io/v3/gas-pump/activated/ETH/0xc1eb70a67e8fd5ff1863c22d4f2856cc7953a7d2/0' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:

{
    "activated": true
}

Step_6: Transfer out from a "Slave GP Contract Address"

• v3 REST API endpoint - You can send only one asset per API call. If you want to send multiple assets, use the following v3 REST API endpoint
• In your custodial application, implement a mechanism that allows your End-users to send (transfer) assets from their deposit addresses ("Slave GP Contract Address") to outside your Exchange or Application.

Request Example:

• Returns the hash (ID) of the transfer transaction

//POST https://api.tatum.io/v3/blockchain/sc/custodial/transfer
curl --location 'https://api.tatum.io/v3/blockchain/sc/custodial/transfer' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
    "chain": "ETH",
    "custodialAddress": "0x73b10492E49B7Ce4cc8dD7F80F38147Ad8DA5Bdf", // Your "Slave GP Contract Address"
    "recipient": "0x5593549ead3b3bd6e4b049ed607ec0f422208298",
    "contractType": 0, // ERC-20 token transfer == 0
    "amount": "10",
    "tokenAddress":"0x03cee0939F57855EB95437f4a0EFA7B1AfBFA4c6", // The ContractAddress of the ERC-20 token
    "fromPrivateKey": "####" // Your "Master GP Address" PrivateKey
}'
//Response:
{
    "txId": "0x29d2796622b64f08ff18b87a277887fe475731cef0009dd3f9eb314d4ec754cd"
}

Good to Know

• Example transactions performed over Ethereum-Sepolia Testnet
• Master GP Address covers the gas fees for sending assets.
• Ensure that Master GP Address always has enough funds to cover gas fees.
• Only activated "Slave GP Contract Address can transfer out assets.