Terminology

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 a 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.

Prerequisites

Before you can start using Autoswap, reach out to your Waltrex account manager with the following:

Markets: which currency corridors you need (e.g. USDT TRC-20 → MXN)
Whitelisted bank accounts: the account(s) where converted funds will be settled. These must be verified by Waltrex before going live.
Gas Wallet: Create a wallet used to enable gas delegation and cover transaction fees on behalf of Deposit Wallets (the source wallets). There are two ways to complete this setup:

Dashboard Wallet Setup

API Wallet Setup

To ensure the AutoSwap service functions correctly, your Gas Wallet must have sufficient balances of the supported blockchains' native tokens. This wallet is responsible for covering gas fees during the automation process.

⚠️
If the Gas Wallet doesn't have enough balance, the AutoSwap process will fail, and deposits will remain in the source wallet without being settled in your selected Fiat currency.

Once confirmed, Waltrex will enable Autoswap on your account. Every deposit made to your wallets will be automatically settled in your selected Fiat currency. 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.

How it works

Each conversion follows a three-step lifecycle:

End user deposits → Create order → Funds settled

This flow is fully automated. Your only responsibility is to display the end user's unique wallet address. A webhook is triggered at each status change, so your system stays in sync in real time.

Create a quote (Optional)

Request a quote for the conversion you want to offer your end user. The quote locks in an exchange rate for a limited time (25s). This step is only necessary if you want to display an estimated target amount to the end user before they complete their deposit.

POST /waltrex-conversions/private/v1/quotes
authorization: Bearer YOUR_TOKEN
x-irs-csrf-token: YOUR_CSRFTOKEN
Content-Type: application/json
{
  "coinFrom": "USDT",
  "chainFrom": "TRX",
  "coinTo": "MXN",
  "amountFrom": "1000"
 }

Response fields you need:

Field	Description
`target_amount`	The fiat currency the beneficiary will receive
`expires_at`	Timestamp after which this quote is no longer valid. Request a new quote to continue

Deposit Flow

Before displaying a wallet address to your end user, check whether they already have one assigned:

Check if the end user already has a wallet. Query your system to see if this end user has used AutoSwap before.
Create or retrieve the wallet.
- First-time user: Generate a new unique wallet address for this end user.
- Returning user: Retrieve their existing wallet address.
Display the wallet address. Show the end user their unique wallet address so they can complete the deposit.

ℹ️
Each end user must have a unique wallet address. This is what allows Waltrex to automatically attribute an incoming deposit to the correct user and authenticate who made it, without manual matching on your end.

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 Autoswap 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.

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 complete the order
→ A new webhook is triggered with eventType:transaction-created indicating the start of the sweep.
```
{  
  "data": {
    "eventType": "transaction-created",
    "payload": {
      "id": "<wallet-tx-id>"
    }
  }
}
```
Swap Transaction Confirmed
When the transaction is confirmed, the order process begins
→ You receive a webhook with eventType:transaction-updated newStatus:mined/confirmed
```
{  
  "data": {
    "eventType": "transaction-updated",
    "payload": {
      "id": "<sponsored-tx-id>",
      "newStatus": "confirmed"
    }
  }
}
```
Funds settled
When the order process is completed
→ You receive a final webhook with eventType:transaction-updated newStatus:completed — completing the flow.
```
{  
  "data": {
    "eventType": "transaction-updated",
    "payload": {
      "id": "<order-tx-id>",
      "newStatus": "completed"
    }
  }
}
```

Going live checklist

Markets confirmed with your Waltrex account manager
Bank account(s) whitelisted and verified
Gas wallet created and funded
Webhook endpoint registered and returning 200 OK
Correctly handling first-time vs returning end users when assigning wallets
Handling all transaction-created and transaction-updated webhook events, including confirmed and completed statuses