This guide will walk you through how to enable the automated consolidation of funds from multiple individual wallets into a central Master Wallet using sponsored gas transactions.

Terminology

Master Wallet (Destination Wallet) This is a central wallet you create, where all incoming deposits (USDT/USD on Ethereum or Tron) from your user wallets will be automatically transferred.

Sponsored Gas Transaction Allows you to offload gas costs to any Waltrex wallet, eliminating friction and optimizing operational efficiency. This feature supports all ERC-20 and TRC-20 tokens.

Gas Wallet: A dedicated wallet used to enable gas delegation and cover transaction fees on behalf of Deposit Wallets (the source wallets).

When is the Gas Wallet needed?

For the one-time token approval transaction that authorizes the Sponsor.
To cover ongoing gas fees for Sponsored Transfers.

One-time token approval for the Sponsor For standard ERC-20 and TRC-20 tokens, Deposit Wallets must complete a one-time approval transaction that authorizes a Gas Wallet to move specific tokens. This setup requires an initial gas injection; however, once approved, the Deposit Wallet no longer needs additional gas. To streamline this process, a small amount of gas is automatically transferred from your Gas Wallet immediately after first deposit.

📘
Transaction Policy Enforcement:
Sponsored Gas transactions are safeguarded by Waltrex's Transaction Policy framework. The Token Approval policy rule allows you to whitelist specific Gas Wallet while restricting all other interactions. Importantly, the policy is enforced at the Deposit Wallet level, not the Gas Wallet, ensuring all transfers comply with organizational security rules.

How it Works

Step 1: Whitelist Wallets

To activate this service, you must create both a Master Wallet and a Gas Wallet with Ethereum and Tron addresses. Share these wallet addresses with your Waltrex contact to have them whitelisted. There are two ways to complete this setup:

Step 2: Fund the Gas Wallet

To ensure the AutoSweep service functions correctly, your Gas Wallet must have sufficient balances on both Ethereum and Tron networks. This wallet is responsible for covering gas fees during the automation process.

🚧
If the Gas Wallet does not have enough balance in ETH or TRX, the AutoSweep process will fail, and deposits will remain in the source wallet without being forwarded to your Master Wallet.

Recommended:

Maintain a small buffer of ETH and TRX for covering energy and bandwidth costs.
You can monitor Gas Wallet balances and set up alerts to avoid service disruptions due to insufficient funds.

Step 3: Webhook Handling and Event Overview

Once the service is activated, every deposit made to your wallets will be automatically redirected to your Master Wallet. To help you monitor and respond to wallet activity in real time, webhook notifications will be sent at each key step of the automation process.
To enable this, you’ll need to configure a webhook endpoint to receive these notifications. Follow this guide to set it up.

step-by-step breakdown of the webhook event flow:

Deposit Received
A deposit is made to one of your Deposit Wallets.
→ You receive a webhook with eventType:transaction-created.

{  
  "data": {
    "eventType": "transaction-created",
    "payload": {
      "id": "<deposit-id>"
    }
  }
}

The AutoSweep system verifies if Deposit Wallet has token approval for the Sponsor.
This setup requires a one-time token approval, which involves an additional gas transfer. This approval is triggered automatically after the first deposit is made to a wallet.
1. Token approval
  If approval is triggered upon the wallet’s first deposit:
  → The system initiates a gas top-up from your Gas Wallet to the Deposit Wallet.
  → A new webhook is triggered with eventType:transaction-created for the gas transfer.
```
{  
  "data": {
    "eventType": "transaction-created",
    "payload": {
      "id": "<gas-tx-id>"
    }
  }
}
```
Transfer Confirmed
Once the deposit transaction is mined/confirmed on-chain:
→ The system initiates the Sponsored Gas Transaction to your Master Wallet.
→ A new webhook is triggered with eventType:transaction-created indicating the start of the sweep.

{  
  "data": {
    "eventType": "transaction-created",
    "payload": {
      "id": "<master-tx-id>"
    }
  }
}

Sweep Transaction Confirmed
When the final transfer to the Master Wallet is completed:
→ You receive a final webhook with eventType:transaction-updated newStatus:mined/confirmed — completing the flow.

{  
  "data": {
    "eventType": "transaction-updated",
    "payload": {
      "id": "<sponsored-tx-id>",
      "newStatus": "confirmed"
    }
  }
}

🚧
Ensure your backend is set up to correctly handle and validate each webhook event in this flow. Implementing proper logic to track transaction statuses and avoid duplicate processing is crucial to prevent mishandling or failed fund movements.

Step 4: Test Integration

Before going live, it's important to test the full automation flow to ensure your webhook handling and wallet setup are working correctly. You can perform tests on either the Ethereum or Tron networks, using mainnet or testnet.

Testnet or Mainnet Support

The integration supports both environments. Simply make sure that your Master Wallet and Gas Wallet are created on the appropriate blockchain network.

Dashboard Wallet Setup

Testnet: Ethereum testnet or Tron testnet
Mainnet: Ethereum mainnet or Tron mainnet

API Wallet Setup

Testnet:

"networks": [
    "networks/ethereum-testnet",
    "networks/tron-testnet"
  ],

Mainnet:

"networks": [
    "networks/ethereum-mainnet",
    "networks/tron-mainnet"
  ],

🚧
Ensure all wallet addresses used for testing belong to the same network. Mixing testnet and mainnet addresses will result in failed transactions.

Getting Testnet Funds

To test on Ethereum or Tron testnets, you'll need to fund your Gas Wallet with testnet ETH or testnet TRX. These funds are required to cover the initial token approval and gas top-up transactions during the AutoSweep process.

Ethereum Testnet

You can obtain testnet ETH from public faucets such as:

These faucets may require a GitHub or social media login to prevent abuse.

Tron Testnet

To get testnet TRX, use the official Tron faucet:

Tron Shasta Testnet Faucet

USDT Testnet

To get testnet USDT, use this telegram group:

TronOfficialDevelopersGroupEn

Once your Gas Wallet is funded on the appropriate network, you're ready to trigger a test deposit and verify the full webhook and AutoSweep flow.