Withdrawing From a Gas Pump Address

Withdrawing from a "Slave GP Contract Address" follows the steps as described in the guide Creating a Manual Withdrawal

• Find how to create Gas Pump addresses in the following article.
• Find how to create Virtual Accounts with Gas Pump in the following article.

Steps

Step_1: Transfer an asset from a "Slave GP Contract Address"

• v3 REST API endpoint

Because you are using GP, you do not have to send funds to pay for the gas. The funds required to pay for the transaction will automatically be deducted from your "Master GP Address".

Example request:

• The response returns the transaction ID (hash)

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}' \
  -d '{
    "chain": "ETH",
    "custodialAddress": "0x5c6079c14e9cd3d2ea8cb76aed9c5e336ef96126", //The deposit address from the VA as "Slave GP Contract Address"
    "recipient": "0x42952e30fB119e0683607Ef6D5A7E8A97dBB7314", //Destination blockchain address, outside your Exchange or Application
    "contractType": 0, // zero for ERC-20 tokens
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", //The Token of the Virtual Account as "currency"
    "amount": "1",
    "fromPrivateKey": "####" // The PrivateKey of your "Master GP Address"
  }'
//Response:

{
  "txId": "0xa1bdc0008b6cce138cec38336a3cbbf1117cc56bcfe0004e14d6789a9d099b72"
}

Step_2: Create a Withdrawal in the VA ledger

• v3 REST API endpoint.

This will register a VA transaction from the source account in the ledger. It debits the amount from the source VA. In the request, specify:

• The ID of the VA to withdraw the assets from (the senderAccountId parameter)
• The blockchain address to send the assets to (the address parameter).
• Creating a withdrawal request to the virtual account will debit the withdrawn balance from the virtual account. This operation is done within the virtual account and is not written to the underlying blockchain.

Example request:

• The response returns the VA log transaction reference and the ID of the withdrawal.

curl -i -X POST \
  https://api.tatum.io/v3/offchain/withdrawal \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -d '{
    "senderAccountId": "5fb7bdf6e96d9ab593e191a6", // Virtual Account ID associated with the "Slave GP Contract Address" you transferred out in step_1 
    "address": "0x42952e30fB119e0683607Ef6D5A7E8A97dBB7314", //The deposit address from the VA as "Slave GP Contract Address"
    "amount": "1",
    "fee": "0.0005"
  }'
//Response:

{
  "reference": "5e6be8e9e6aa436299950c41",
  "id": "5e68c66581f2ee32bc354087"
}

Step_3: Mark the withdrawal transaction as completed "Done"

• v3 REST API endpoint.

Mark the withdrawal as successful and store the transaction hash/ID of the blockchain transaction to the withdrawal operation in the VA ledger. This step must be completed; otherwise, there will be inconsistencies within the virtual account state.

Example request:

//PUT: https://api.tatum.io/v3/offchain/withdrawal/{id}/{txId}
curl --request PUT \
     --url https://api.tatum.io/v3/offchain/withdrawal/5e68c66581f2ee32bc354087/0xa1bdc0008b6cce138cec38336a3cbbf1117cc56bcfe0004e14d6789a9d099b72 \
     --header 'accept: application/json' \
     --header 'x-api-key: {YOUR_API_KEY}'

Good to Know

• Should the blockchain transaction fail and you already executed Step_2, you may delete the withdrawal from the VA ledger via the following v3 REST API endpoint

❗️

Warning

Virtual Accounts where the withdrawal currency is a token, it is recommended to use “revert=false".

Important

The intended use case for Virtual Accounts (VA) is as a Self-Custodial Exchange, meaning all withdrawals are expected to be tracked in the VA ledger.

• Tatum does not hold custody of mnemonics or private keys. As a result, it is technically possible to sign transactions using VA ledger deposit addresses outside the VA ledger and Tatum endpoints. For more details, refer to this article.
• The blockchain’s on-chain balance takes precedence over the VA ledger. If unregistered transactions occur, the VA ledger will become misaligned, leading to liquidity inconsistencies between the on-chain balance and the off-chain VA ledger.
• Virtual Accounts are designed to hold a limited number of deposit addresses (1-5). While adding many more deposit addresses may appear functional, this setup often leads to unrecoverable synchronisation issues across users over time.
• Any on-chain assets already present in the blockchain address to bind to the Virtual Account will be ignored. More information HERE.
• Deposits are only "recognized" as long as the "currency" of the VA matches the on-chain asset deposited
• If a mistake occurs when creating or storing a withdrawal in the VA ledger, it can be deleted and retried. Check this article for addtional details.
• Withdrawals from a VA deposit address can be automated using the VA Blockchain Operationsendpoints, ensuring they are properly logged in the VA ledger.

🚧

Attention

• You are expected to hold 1:1 asset liquidity between the VA off-chain ledger and your end-users on-chain assets.
• To avoid potential disruptions and ensure consistent performance, we recommend adhering to the intended usage of 1-5 deposit addresses per Virtual Account.
• Be mindful of Tatum Derivation Path.

❗️

Warning

• All withdrawals must be registered and executed through VA-specific endpoints.
• Using standard blockchain transaction methods to sign and broadcast a transaction from a VA-linked deposit address bypasses the VA ledger, leadings to balance discrepancies. If this happens, the withdrawal must be manually registered