Gas Tank API Documentation
The Gas Tank is a versatile platform that empowers users to manage gas tank balances seamlessly across different blockchain networks. This project facilitates actions such as depositing, withdrawing, internal transferring, and consuming gas tank balances, allowing users to efficiently utilize their resources on EVM, Cosmos-like, and UTXO chains. With support for multiple blockchain environments, The Gas Tank offers users a unified solution for gas utilization across diverse networks. Check the Gas Tank API Swagger for more information.
The base URL for all Gas Tank API is: https://gas-tank.xdefi.services
Below are the available services provided by the Gas Tank API. You need to have a valid JWT token to access the services. You can get the JWT token by using the Multiple Address Login endpoint.
Authentication
Multiple Addresses Login
This endpoint facilitates the generation of JWT tokens for multiple wallet addresses in a single request. The request payload should consist of an array of objects, each containing an address and its corresponding signature. Upon successful validation of the signatures, the server will generate JWT tokens for the provided addresses.
To get signatures, you can use personal_sign
method from web3.js or ethers.js. Below is an example of how to get a signature using web3.js:
const web3 = new Web3(window.ethereum);
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
const address1 = "0x1234567890123456789012345678901234567890";
const address2 = "0x0987654321098765432109876543210987654321";
const messageToSign = await (
await fetch(`${GAS_TANK_ENDPOINT}/v2/auth/message`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify([address1, address2]),
})
).json();
const message = messageToSign.message;
const signature1 = await web3.eth.personal.sign(message, address1);
const signature2 = await web3.eth.personal.sign(message, address2);
await fetch(`${GAS_TANK_ENDPOINT}/v2/auth/login`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify([
{
address: address1, // Address of the user
signature: signature1, // Signature
},
{
address: address2,
signature: signature2,
},
...
]),
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
{
"access": "jwt.access.token",
"refresh": "jwt.refresh.token"
}
You can also add new wallets to an existing JWT token. Request will be secured by JWT header. Clients need to submit an array of objects containing the address and signature for each new wallet. The server will validate the signatures and, if successful, update the existing JWT token to include the new wallets and generate new JWT.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/v2/auth/update`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${jwtToken}`, // JWT token
},
body: JSON.stringify([
{
address: newAddress,
signature: newSignature,
},
...
]),
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
{
"access": "jwt.access.token",
"refresh": "jwt.refresh.token"
}
Refresh JWT Token
Clients can use this endpoint to obtain a new JWT token without re-authenticating, providing a refresh token.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/v2/auth/refresh`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
body: JSON.stringify({
refresh: refreshToken, // Refresh token
}),
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"access": "jwt.access.token",
"refresh": "jwt.refresh.token"
}
Messages
Construct Deposit Message
This endpoint will generate messages
parameter for Deposit balances.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/msg/increase`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
owner: "0xOwnerWalletAddress", // The wallet address of the owner
tokenAddress: "0xTokenContractAddress", // The contract address of the token
amount: "1", // Amount of the token to deposit
chain: "ethereum", // The blockchain network, e.g., 'ethereum'
}),
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"type": "string",
"message": "string"
}
Construct Withdraw Message
This endpoint will generate messages
parameter for Withdraw balances.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/msg/withdraw`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
address: "0xYourWalletAddress", // Your wallet address
tokenAddress: "0xTokenContractAddress", // The contract address of the token
amount: "1", // Amount of the token to withdraw
chain: "ethereum", // The blockchain network, e.g., 'ethereum'
recipient: "0xRecipientWalletAddress", // The recipient's wallet address
}),
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"type": "string",
"message": "string"
}
Construct Internal Transfer Message
This endpoint will generate messages
parameter for Internal Transfer balances.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/msg/internal-transfer`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
address: "0xYourWalletAddress", // Your wallet address
tokenAddress: "0xTokenContractAddress", // The contract address of the token
amount: "1", // Amount of the token to transfer
chain: "ethereum", // The blockchain network, e.g., 'ethereum'
recipient: "0xRecipientWalletAddress", // The recipient's wallet address
}),
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"type": "string",
"message": "string"
}
Construct Consume Message
This endpoint will generate messages
parameter for Consume balances.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/msg/consume`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
address: "0xYourWalletAddress", // Your wallet address
minDestinationAmount: "1", // Minimum amount of the token to consume
destinationChain: "ethereum", // The blockchain network, e.g., 'ethereum'
}),
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"type": "string",
"message": "string"
}
Chains / Token / Status
Get all Tokens
This endpoint allows users to retrieve information about all tokens available on the Gas Tank platform.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/chains/tokens`, {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"additionalProp1": {
"name": "string",
"key": "string",
"chainId": "string",
"native": {
"symbol": "string",
"decimals": 0,
"address": "string",
"actions": [
"string"
]
},
"tokens": [
{
"name": "string",
"symbol": "string",
"decimals": 0,
"address": "string",
"actions": [
"string"
]
}
]
},
"additionalProp2": {
"name": "string",
"key": "string",
"chainId": "string",
"native": {
"symbol": "string",
"decimals": 0,
"address": "string",
"actions": [
"string"
]
},
"tokens": [
{
"name": "string",
"symbol": "string",
"decimals": 0,
"address": "string",
"actions": [
"string"
]
}
]
},
...
}
Get dispatchers information
This endpoint provides information about the dispatchers on the Gas Tank platform.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/chains/dispatchers-info`, {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"additionalProp1": {
"chain": "string",
"address": "string",
"balance": "string",
"status": "string",
"threshold": "string"
},
"additionalProp2": {
"chain": "string",
"address": "string",
"balance": "string",
"status": "string",
"threshold": "string"
},
...
}
Get chains Operational status
This endpoint provides information about the status of all supported chains on the Gas Tank platform.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/chains/status`, {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"operational": true,
"chains": [
{
"chain": "string",
"operational": true,
"actions": {
"increase": true,
"withdraw": true,
"consume": true
},
"extras": {
"address": "string",
"balance": "string",
"threshold": "string",
"status": "string"
},
"comment": "string"
},
...
]
}
Balance & Transactions - Deposit, Withdraw, Send Gas
Get all balance entries for user
This endpoint returns a list of all balance entries per address by using JWT
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/balances`, {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
{
"additionalProp1": [
{
"id": "string",
"address": "string",
"tokenAddress": "string",
"balance": 0,
"chain": "string"
}
],
"additionalProp2": [
{
"id": "string",
"address": "string",
"tokenAddress": "string",
"balance": 0,
"chain": "string"
}
],
...
}
Get balances by address
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/balances/${address}`, { // Address to retrieve balances
method: "GET",
headers: {
"Content-Type": "application/json"
"Authorization": `Bearer ${jwtToken}`, // JWT token
},
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
[
{
"id": "string",
"address": "string",
"tokenAddress": "string",
"balance": 0,
"chain": "string"
},
...
]
Get total balances using JWT
This endpoint returns a list of total balances for the specified JWT.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/balances/totals`, {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
}).then((response) => {
console.log(response);
// Handle & do something with the response
});
[
{
"address": "string",
"symbol": "string",
"value": "string",
"decimals": 0
},
...
]
Deposit balance
This endpoint allows users to deposit balance to the Gas Tank platform.
To deposit the balance, you need to sign the message with the private key of the address you want to deposit the balance for. v
, r
, s
are the signature fields of the message signed by the address owner and message
is generated in Construct Deposit Message.
You can sign a string of data using ethers.js, below is an example of how to sign a message using ethers.js and deposit the balance.
import { ethers } from "ethers";
const web3 = new Web3(window.ethereum);
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
const address = "0x1234567890123456789012345678901234567890"; // Address to deposit balance
const message = message; // Message is generated in Construct Deposit Message
const privateKey = "0x1234"; // Private key of the address
const wallet = new ethers.Wallet(privateKey);
const signature = await wallet.signMessage(message);
const { v, r, s } = ethers.utils.splitSignature(signature);
await fetch(`${GAS_TANK_ENDPOINT}/balances/increase`, {
method: "POST",
headers: {
"Content-Type": "application/json"
"Authorization": `Bearer ${jwtToken}`, // JWT token
},
body: JSON.stringify({
address: address,
tokenAddress: "string", // Token contract address for deposit
chain: "string", // The blockchain network [!code highlight]
owner: "string", // The owner's address (can match the 'address' field) [!code highlight]
spender: "string", // Gas Tank's internal address [!code highlight]
value: "string", // Amount of deposited token [!code highlight]
deadline: 0, // Date for checking the validity of the signature [!code highlight]
v: v,
r: r,
s: s
}),
})
.then((response) => {
// Balance deposit successfully
})
.catch((error) => {
// Catch & handle the error
});
Withdraw balance
This endpoint allows users to withdraw their balance from the Gas Tank platform.
To withdraw the balance, you need to sign the message with the private key of the address you want to withdraw the balance from. The signature
field is the signature of the message signed by the address owner and message
is generated in Aonstruct Withdraw Message.
Same as the Deposit balance, you can sign a string of data using ethers.js, below is an example of how to sign a message using ethers.js and withdraw the balance.
import { ethers } from "ethers";
const web3 = new Web3(window.ethereum);
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
const address = "0x1234567890123456789012345678901234567890"; // Address to withdraw balance
const message = message; // Message is generated in Construct Withdraw Message
const privateKey = "0x1234"; // Private key of the address
const wallet = new ethers.Wallet(privateKey);
const signature = await wallet.signMessage(message);
await fetch(`${GAS_TANK_ENDPOINT}/balances/withdraw`, {
method: "POST",
headers: {
"Content-Type": "application/json"
"Authorization": `Bearer ${jwtToken}`, // JWT token
},
body: JSON.stringify({
address: address,
tokenAddress: "string", // Token contract address for withdraw [!code highlight]
amount: "string", // Amount of withdraw token [!code highlight]
chain: "string", // The blockchain network [!code highlight]
recipient: "string", // The recipient's wallet address [!code highlight]
message: message,
signature: signature
}),
})
.then((response) => {
// Balance withdrawn successfully
})
.catch((error) => {
// Catch & handle the error
});
Internal transfer
This endpoint allows users to create an internal transfer task on the Gas Tank platform. The internal transfer task is used to transfer balance from one address to another address on the Gas Tank platform. The signature
field is the signature of the message signed by the address owner and message
is generated in Construct Internal Transfer Message.
import { ethers } from "ethers";
const web3 = new Web3(window.ethereum);
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
const address = "0x1234567890123456789012345678901234567890"; // Address to transfer balance
const message = message; // Message is generated in Construct Internal Transfer Message
const privateKey = "0x1234"; // Private key of the address
const wallet = new ethers.Wallet(privateKey);
const signature = await wallet.signMessage(message);
await fetch(`${GAS_TANK_ENDPOINT}/balances/transfer`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
body: JSON.stringify({
address: address,
tokenAddress: "string", // Token contract address for transfer [!code highlight]
amount: "string", // Amount of transfer [!code highlight]
chain: "string", // The blockchain network [!code highlight]
recipient: "string", // The recipient's wallet address [!code highlight]
message: message,
signature: signature,
}),
})
.then((response) => {
// Internal transfer task created successfully
})
.catch((error) => {
// Catch & handle the error
});
Get a quote for consuming balance
This endpoint allows users to generate a quote for consuming their balance on the Gas Tank platform.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/balances/consume/quote`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
body: JSON.stringify({
address: "string", // Your wallet address
minDestinationAmount: "string", // Minimum amount of the token to consume
destinationChain: "string", // The blockchain network
}),
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
.catch((error) => {
// Catch & handle the error
});
{
"expectedOutput": "string",
"fee": "string",
"spentAssets": [
{
"tokenAddress": "string",
"amount": "string",
"chain": "string"
}
]
}
Consume balance
This endpoint allows users to consume their balance on the Gas Tank platform.
To consume the balance, you need to sign the message with the private key of the address you want to consume the balance from. The signature
field is the signature of the message signed by the address owner and message
is generated in Construct Consume Message.
Same as the Deposit balance/Withdraw balance, you can sign a string of data using ethers.js, below is an example of how to sign a message using ethers.js and consume the balance.
import { ethers } from "ethers";
const web3 = new Web3(window.ethereum);
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
const address = "0x1234567890123456789012345678901234567890"; // Address to consume balance
const message = message; // Message is generated in Construct Consume Message
const privateKey = "0x1234"; // Private key of the address
const wallet = new ethers.Wallet(privateKey);
const signature = await wallet.signMessage(message);
await fetch(`${GAS_TANK_ENDPOINT}/balances/consume`, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
body: JSON.stringify({
address: address,
minDestinationAmount: "string", // Minimum amount of the token to consume
destinationAddress: "string", // The recipient's wallet address
destinationChain: "string", // The blockchain network
message: message,
signature: signature,
}),
})
.then((response) => {
// Balance consumed successfully
})
.catch((error) => {
// Catch & handle the error
});
Get user balance queue update
This endpoint allows users to get the balance queue update for any job ongoing (e.g., deposit, withdrawal, transfer, consume).
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/transactions`, {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
.catch((error) => {
// Catch & handle the error
});
{
"additionalProp1": [
{
"id": "string",
"type": "string",
"address": "string",
"tokenAddress": "string",
"amount": "string",
"chain": "string",
"destinationChain": "string",
"destinationAddress": "string",
"permitObject": {},
"processed": true,
"processedMetadata": {},
"pendingTransactions": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chain": "ethereum",
"transactionHash": "0x6b175474e89094c44da98b954eedeac495271d0f",
"blockNumber": 123456,
"balanceUpdateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"confirmed": false,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z"
}
],
"createdAt": "2024-04-11T04:13:07.102Z",
"updatedAt": "2024-04-11T04:13:07.102Z"
}
],
...
}
Get balance queue update by ID
This endpoint allows users to get the balance queue update for a specific ID (e.g., deposit, withdrawal, transfer, consume).
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/transactions/${id}`, {
method: "GET",
headers: {
"Content-Type": "application",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
.catch((error) => {
// Catch & handle the error
});
{
"id": "string",
"type": "string",
"address": "string",
"tokenAddress": "string",
"amount": "string",
"chain": "string",
"destinationChain": "string",
"destinationAddress": "string",
"permitObject": {},
"processed": true,
"processedMetadata": {},
"pendingTransactions": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chain": "ethereum",
"transactionHash": "0x6b175474e89094c44da98b954eedeac495271d0f",
"blockNumber": 123456,
"balanceUpdateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"confirmed": false,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z"
}
],
"createdAt": "2024-04-11T04:17:30.107Z",
"updatedAt": "2024-04-11T04:17:30.107Z"
}
Get pending transactions by address
This endpoint allows users to get pending transactions for a specific address. Results returned a list of pending transactions.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(
`${GAS_TANK_ENDPOINT}/transactions/pending/${address}`, // Address to retrieve pending transaction
{
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
},
)
.then((response) => {
console.log(response);
// Handle & do something with the response
})
.catch((error) => {
// Catch & handle the error
});
[
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chain": "ethereum",
"transactionHash": "0x6b175474e89094c44da98b954eedeac495271d0f",
"blockNumber": 123456,
"balanceUpdateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"confirmed": false,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z"
},
...
]
Get fee for a given amount
This endpoint allows users to get the fee for a given amount in a specific chain.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(
`${GAS_TANK_ENDPOINT}/fees/${chain}`, // Chain to get fee
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${jwtToken}`, // JWT token
},
},
)
.then((response) => {
console.log(response);
// Handle & do something with the response
})
.catch((error) => {
// Catch & handle the error
});
{
"high": "string",
"medium": "string",
"low": "string"
}
Other services
This section provides information about the other services provided by the Gas Tank API. APIs in this section not require JWT token for authentication.
Get information about the Gas Tank
This endpoint provides information about the conversion rates between different tokens and fees for deposit, withdrawal and consume actions.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/balances/info`, {
method: "GET",
headers: {
"Content-Type": "application/json",
},
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
.catch((error) => {
// Catch & handle the error
});
{
"conversionRates": {
"xdefi": {
"eth": 0.00003406230336183101,
"bnb": 0.00020052618581142264,
"usdc": 0.13496037812654052,
"usdt": 0.1349557894736842,
...
},
"eth": {
"xdefi": 29357.967644682656,
"usdt": 3763.926315789474,
...
},
... // Other pairs
},
"spenderAddresses": [
"0x0E87C393120410d1edd00Ae5b616419795c5B57D"
],
"fees": {
"deposit": {
"fees": {
"high": "357840000000000",
"medium": "357420000000000",
"low": "357210000000000"
}
},
"withdraw": {
"fees": {
"high": "357840000000000",
"medium": "357420000000000",
"low": "357210000000000"
}
},
"consume": {
"fees": {
"high": "357840000000000",
"medium": "357420000000000",
"low": "357210000000000"
}
}
}
}
Check the status of the application
This endpoint provides information about the status of the Gas Tank application and its dependencies.
const GAS_TANK_ENDPOINT = "https://gas-tank.xdefi.services";
await fetch(`${GAS_TANK_ENDPOINT}/healthcheck`, {
method: "GET",
headers: {
"Content-Type": "application/json",
},
})
.then((response) => {
console.log(response);
// Handle & do something with the response
})
.catch((error) => {
// Catch & handle the error
});
{
"status": "OK",
"database": "Connected",
"mnemonic": "Set",
"nats": "Connected"
}