Tatum
Search…
How to withdraw assets from virtual accounts with gas pump wallets
This guide describes how to withdraw assets from virtual accounts connected to gas pump wallets. We will cover the whole flow of the user journey - gas pump wallet generation, virtual account creation, and withdrawal from the gas pump wallet to the blockchain address with correct virtual account balance updates.
Wallet generation
The first step is to create a gas pump wallet for every user. Each wallet supports the native currency of the blockchain it's deployed on, as well as ERC-20, ERC-721, and ERC-1155 tokens by default.
In the following request, we will simply choose how many wallets we want to deploy:
JavaScript
cURL
1
import {Currency, generateCustodialWalletBatch } from '@tatumio/tatum';
2
/**
3
* Generate new custodial smart contract address on the blockchain.
4
* @param testnet - false for mainnet, true for testnet
5
* @param body - body of request - https://apidoc.tatum.io/tag/Gas-pump/#operation/GenerateCustodialWallet
6
* @returns transaction ID of wallet creation
7
*/
8
const body = {
9
chain: Currency.MATIC,
10
fromPrivateKey: "0x37b091fc4ce46a56da643f021254612551dbe0944679a6e09cb5724d3085c9ab",
11
batchCount: 200,
12
owner: "0x80d8bac9a6901698b3749fe336bbd1385c1f98f2"
13
}
14
const wallet = generateCustodialWalletBatch (false, body);
Copied!
1
curl --location --request POST 'https://api-eu1.tatum.io/v3/blockchain/sc/custodial/batch' \
2
--header 'Content-Type: application/json' \
3
--header 'x-api-key: YOUR_API_KEY' \
4
--data-raw '{
5
"owner": "0x80d8bac9a6901698b3749fe336bbd1385c1f98f2",
6
"batchCount": 200,
7
"chain": "MATIC",
8
"fromPrivateKey": "0x37b091fc4ce46a56da643f021254612551dbe0944679a6e09cb5724d3085c9ab"
9
}'
Copied!
The response is the transaction hash. From this hash, we can find the address of each contract we have deployed - our gas pump wallet addresses.
Response
1
{
2
"txId": "0x2979a3d30f812b0d9ebcc66d01b620d3779380c38e8770a82fa4ea4f2dfa8f69"
3
}
Copied!
Virtual account creation
Now, for every user, we need to create a virtual account. Since we have decided to support MATIC and USDC for every user, we need to create 2 virtual accounts - MATIC and USDC. These accounts do not have xpubs because we will manually assign addresses to them later.
JavaScript
cURL
1
import { Account, Currency, CreateAccount, createAccount } from "@tatumio/tatum";
2
import { config } from "dotenv";
3
​
4
config();
5
​
6
const createNewAccount = async () => {
7
const createAccountData: CreateAccount = {
8
currency: Currency.MATIC
9
};
10
const accoun: Account = await createAccount(createAccountData);
11
console.log(accoun);
12
};
13
​
14
const createNewAccount = async () => {
15
const createAccountData: CreateAccount = {
16
currency: Currency.USDC_MATIC
17
};
18
const accoun: Account = await createAccount(createAccountData);
19
console.log(accoun);
20
};
21
​
22
createNewAccount();
Copied!
1
curl --location --request POST 'https://api-eu1.tatum.io/v3/ledger/account' \
2
--header 'x-api-key: YOUR_API_KEY' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"currency": "MATIC"
6
}'
7
​
8
curl --location --request POST 'https://api-eu1.tatum.io/v3/ledger/account' \
9
--header 'x-api-key: YOUR_API_KEY' \
10
--header 'Content-Type: application/json' \
11
--data-raw '{
12
"currency": "USDC_MATIC"
13
}'
Copied!
The response will contain details about the two accounts we have just created.
Response
1
{
2
"currency": "MATIC",
3
"active": true,
4
"balance": {
5
"accountBalance": "0",
6
"availableBalance": "0"
7
},
8
"frozen": false,
9
"accountingCurrency": "EUR",
10
"id": "5fb7bdf6e96d9ab593e191a5"
11
}
12
​
13
{
14
"currency": "USDC_MATIC",
15
"active": true,
16
"balance": {
17
"accountBalance": "0",
18
"availableBalance": "0"
19
},
20
"frozen": false,
21
"accountingCurrency": "EUR",
22
"id": "5fb7bdf6e96d9ab593e191a6"
23
}
Copied!
Once an account has been created, we need to assign a gas pump address to it. This process enables automatic incoming transaction synchronization for the specified address and currency.
JavaScript
cURL
1
import {assignDepositAddress} from '@tatumio/tatum';
2
/**
3
* Assign address for account
4
* @param id - account ID
5
* @param address - blockchain address to assign
6
*/
7
const assign = assignDepositAddress ("5fb7bdf6e96d9ab593e191a5","0x8Fca331d13E518059191Dde43765ea77C6C98336");
Copied!
1
curl --location --request POST 'https://api-eu1.tatum.io/v3/offchain/account/5fb7bdf6e96d9ab593e191a5/address/0x8Fca331d13E518059191Dde43765ea77C6C98336' \
2
--header 'x-api-key: YOUR_API_KEY'
Copied!
The response confirms the address has been assigned to the virtual account. Any incoming blockchain transaction to this address will be automatically detected and the virtual account balance will be updated.
Response
1
{
2
"address": "0x8Fca331d13E518059191Dde43765ea77C6C98336",
3
"currency": "MATIC"
4
}
Copied!
Withdraw assets from the account
The following 3 steps are necessary to withdraw assets from a virtual account and send them to the blockchain:
- 1.Create a withdrawal request to the virtual account - it will debit the withdrawn balance from the virtual account
- 2.Perform a transfer of the assets from the gas pump address - this will result in the blockchain transaction.
- 3.Mark the withdrawal from the 1st step as completed.
Let's withdraw 1 USDC from an account to the blockchain.
Perform a withdrawal
To make the virtual account balance in sync, you need to perform a withdrawal operation from that account.
JavaScript
cURL
1
import { offchainStoreWithdrawal } from '@tatumio/tatum';
2
/**
3
* Generate new custodial smart contract address on the blockchain.
4
* @param data - body of request - https://apidoc.tatum.io/tag/Withdrawal/#operation/storeWithdrawal
5
* @returns transaction reference, withdrawal id, withdrawal detail
6
*/
7
const body = {
8
senderAccountId: "5fb7bdf6e96d9ab593e191a6",
9
address: "0x42952e30fB119e0683607Ef6D5A7E8A97dBB7314",
10
amount: "1"
11
}
12
const wallet = offchainStoreWithdrawal (body);
Copied!
1
curl --location --request POST 'https://api-eu1.tatum.io/v3/offchain/withdrawal' \
2
--header 'x-api-key: YOUR_API_KEY' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"senderAccountId":"5fb7bdf6e96d9ab593e191a6",
6
"address":"0x42952e30fB119e0683607Ef6D5A7E8A97dBB7314",
7
"amount":"1"
8
}'
Copied!
The result is the virtual account transaction reference and the ID of the withdrawal. The account balance has been debited with 1 USDC and the transaction is visible in the list of the transactions for the virtual account. We still haven't done anything on the blockchain.
Response
1
{
2
"reference": "5e6be8e9e6aa436299950c41",
3
"id": "5e68c66581f2ee32bc354087"
4
}
Copied!
Perform a blockchain transaction
Now it's time to move the assets to another address. Since we're using gas pump wallets, you don't have to send any MATIC there to pay for gas. You only need to specify which assets should be sent, how much of them, and where to send them, and the funds required to pay for the transaction will automatically be deducted from the owner address you specified when creating the gas pump wallets.
JavaScript
cURL
1
import { Currency, prepareTransferFromCustodialWallet } from '@tatumio/tatum';
2
/**
3
* Prepare signed transaction from the custodial SC wallet.
4
* @param testnet - false for mainnet, true for testnet
5
* @param data - body of request - https://apidoc.tatum.io/tag/Gas-pump/#operation/TransferCustodialWallet
6
* @param provider optional provider to enter. if not present, Tatum Web3 will be used.
7
* @returns {txId: string} Transaction ID of the operation, or signatureID in case of Tatum KMS
8
*/
9
const body = {
10
chain: Currency.MATIC,
11
custodialAddress: "0x8Fca331d13E518059191Dde43765ea77C6C98336",
12
tokenAddress: "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
13
contractType: 0,
14
recipient: "0x42952e30fB119e0683607Ef6D5A7E8A97dBB7314",
15
amount: "1",
16
tokenId: "100000",
17
fromPrivateKey: "0x37b091fc4ce46a56da643f021254612551dbe0944679a6e09cb5724d3085c9ab"
18
}
19
const transfer = prepareTransferFromCustodialWallet(false, body);
Copied!
1
curl --location --request POST 'https://api-eu1.tatum.io/v3/blockchain/sc/custodial/transfer' \
2
--header 'Content-Type: application/json' \
3
--header 'x-api-key: YOUR_API_KEY' \
4
--data-raw '{
5
"chain": "MATIC",
6
"contractType": 0,
7
"amount": "1",
8
"tokenAddress": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
9
"custodialAddress": "0x8Fca331d13E518059191Dde43765ea77C6C98336",
10
"recipient": "0x42952e30fB119e0683607Ef6D5A7E8A97dBB7314",
11
"fromPrivateKey": "0x37b091fc4ce46a56da643f021254612551dbe0944679a6e09cb5724d3085c9ab"
12
}'
Copied!
The response is the transaction hash. As you can see, we have to enter the address of the token we want to transfer (tokenAddress 0x2791bca1f2de4661ed88a30c99a7a9449aa84174). The contractType attribute is very important, as it tells the wallet which kind of a token it is transferring - 0 for ERC-20 assets. For more on using gas pump wallets, please refer to our full guide.
Response
1
{
2
"txId": "0xa1bdc0008b6cce138cec38336a3cbbf1117cc56bcfe0004e14d6789a9d099b72"
3
}
Copied!
Complete or cancel the withdrawal
Once the transaction is successful, you need to mark the withdrawal as completed. If the transaction fails and you want to refund the assets to the virtual account, you need to cancel the original withdrawal request.
That's it. 5 simple steps to connect your gas pump wallets to virtual accounts and keep them synced.