TON Gasless Transactions in WDK.

In this post, we will cover Gasless transactions on the TON chain using the WDK wallet modules.

On TON, users shouldn't need Toncoin just to move USD₮. Unlike EVM chains, where gasless requires external bundler infrastructure (EVM Gasless Transactions in WDK or Solana Gasless Transactions in WDK), TON has paymaster support built into the protocol. The @tetherto/wdk-wallet-ton-gasless module lets users send TON and Jetton tokens (like USD₮) without having to hold TON for fees.

Step 1: Understand How Gasless Works on TON

The flow is the same pattern in all the WDK's modules, doesn't matter the chain:

1. The user signs a USD₮ (Jetton) transfer
2. A paymaster submits it and pays the TON gas
3. The paymaster is repaid in USD₮, deducted in the same transaction

Because paymasters are native to TON, there's no bundler and no smart-account deployment. What you do need is API access to TON infrastructure, and this is where TON is a little unusual: the module talks to two separate services, each with its own key.

Step 2: Get Your API Keys

Integrating with TON requires two API keys from two separate services, one for TonAPI (used by @ton-api/client, which powers the gasless features) and one for Toncenter (used by TonClient for RPC node access).

1. TonAPI Key: via TON Console

Keys are managed at tonconsole.com. The same key works for both mainnet and testnet. For testnet, use https://testnet.tonapi.io as the base URL.

Steps:

• Go to https://tonconsole.com
• Sign in with a TON wallet via TON Connect, there's no email/password, you authenticate yourself with your Telegram account

• You will be asked to authenticate in your Telegram App

• You will receive a success message, and you will be able to close the sesión also from your Telegram Chat. And you will be redirected to the TonConsole dashboard.

• Navigate to TON API → API Keys "TON API". You will see your keys, and also the "Create API Key" button.

• Click Create API Key, give it a name, and copy the result

Usage in code:

tonApiClient: {
  url: 'https://tonapi.io',  // no /v2 — the client appends it automatically
  secretKey: 'YOUR_TONAPI_KEY'
}

⚠️ Critical: the @ton-api/client package appends /v2 to the base URL automatically. Always use https://tonapi.io with no version suffix — otherwise every request fails with a 404. This one is easy to lose an afternoon to.

2. Toncenter Key, via Telegram Bot

Toncenter is used for the tonClient (RPC node access). Keys are issued through a Telegram bot, there's no web dashboard.

Steps:

• Open Telegram and start @tonapibot (mainnet). For testnet, use @tontestnetapibot

• Send /start

• Select Manage API Keys → Create API Key

• Copy the generated key

Usage in code:

tonClient: {
  url: 'https://toncenter.com/api/v2/jsonRPC',
  secretKey: 'YOUR_TONCENTER_KEY'
}

Quick Reference

Both services work without keys at heavily reduced rate limits, fine for a first hello-world, painful for anything real.

Step 3: Register the Gasless Wallet

Install the module in your project. We support Node.js and Bare runtimes. For more information, check Introduction to WDK: Tether's Wallet Development Kit.

npm install @tetherto/wdk @tetherto/wdk-wallet-ton-gasless

Next, you will have to register the module with WDK. The process and structure are the same as with every other chain in this series; the only thing that changes is the configuration.

import WDK from '@tetherto/wdk'
import WalletManagerTonGasless from '@tetherto/wdk-wallet-ton-gasless'

const seedPhrase = 'your seed phrase here' // only for development and testing

const wdk = new WDK(seedPhrase)
  .registerWallet('ton-gasless', WalletManagerTonGasless, {
    tonClient: {
      url: 'https://toncenter.com/api/v2/jsonRPC',
      secretKey: 'YOUR_TONCENTER_KEY'   // from the Telegram bot
    },
    tonApiClient: {
      url: 'https://tonapi.io',          // no /v2!
      secretKey: 'YOUR_TONAPI_KEY'       // from TON Console
    },
    paymasterToken: {
      address: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs' // USDT Jetton master
    },
    transferMaxFee: 10000000
  })

console.log('TON gasless wallet registered')

What's happening:

• tonClient: RPC access to the TON network via Toncenter.
• tonApiClient: the TonAPI connection that powers the gasless flow.
• paymasterToken.address: the Jetton the paymaster charges fees in (USD₮ here).
• transferMaxFee: a cap on the fee, in token base units. If the quoted fee exceeds it, the transfer throws instead of overpaying.

Step 4: Send Your First Gasless Transaction

Once the wallet is registered, we can send USD₮ from an account that holds zero TON. As always, we quote first, show users the exact cost before they commit:

const tonAccount = await wdk.getAccount('ton-gasless', 0)
const usdtMasterTon = 'EQCxE6mUtQJKFnGfaSJFkwcKe8jkU9MZvKaQcuarUuWFHt6f'
const recipientTon = 'EQA-0...' // TON address

// Estimate the fee first
const quote = await tonAccount.quoteTransfer({
  token: usdtMasterTon,     // Jetton contract address
  recipient: recipientTon,
  amount: 1000000n          // 1 USDT (6 decimals)
})

console.log('Gas fee:', Number(quote.fee) / 1e6, 'USDT')

// Send — the paymaster covers the TON gas
try {
  const result = await tonAccount.transfer({
    token: usdtMasterTon,
    recipient: recipientTon,
    amount: 1000000n
  }, {
    transferMaxFee: 500000n // optional per-call cap: 0.5 USDT
  })

  console.log('✅ Transaction hash:', result.hash)
  console.log('Fee paid:', Number(result.fee) / 1e6, 'USDT')
} catch (error) {
  console.error('Transfer failed:', error.message)
}

What's happening:

• Token transfers use transfer() with token, recipient, and amount, note that sendTransaction() is not supported in the TON gasless module; all sends go through the gasless provider via transfer().
• token points to the Jetton master contract; Jetton is TON's token standard, the equivalent of EVM's token contract address.
• recipient is a TON address; mainnet addresses start with EQ or UQ, not 0x.
• The paymaster recognizes the Jetton transfer, covers the TON gas fee, and deducts the fee from your USD₮ balance in a single transaction.
• The optional second argument is a per-call override: here we cap this transfer's fee at 0.5 USD₮ with transferMaxFee. You can also override paymasterToken per call.
• result.hash is the transaction hash to track on a TON explorer; result.fee is the actual fee paid, which may differ slightly from the quote if network conditions changed.
• Everything else is the identical WDK pattern: estimate → send → confirm. In fact, transfer() has the same signature on TRON and Solana too.

Common errors:

• 404 on every TonAPI call: you included /v2 in the tonApiClient.url. Remove it.
• 429 Too Many Requests: you're on the no-key or free tier. Add your keys or upgrade.
• sendTransaction() fails or is rejected: it's not supported in the gasless module; use transfer().
• Fee above transferMaxFee: the quoted fee exceeds your cap (from the config or the per-call override). Raise it or retry when the network is cheaper.
• "Insufficient balance": your USD₮ balance must cover the amount + fee.

Key Insights

• TON needs two keys from two services: TonAPI (web console, wallet login) and Toncenter (Telegram bot). Budget five minutes for each.
• The /v2 trap is real: https://tonapi.io, never https://tonapi.io/v2.
• Paymasters are protocol-native on TON: no bundler, no smart account, just the transfer plus a fee in USD₮.
• Same WDK pattern: only jettonMaster (instead of tokenAddress), and the address format change.

What's next

Follow WDK's official X account to stay up to date with all the announcements. Join us on Discord, the best place to ask questions, share what you're building, and get help directly from the team.

All four modules are already documented and ready to use. And if you'd enjoy a more guided, step-by-step take with extra tips along the way, we've got you. Coming up:

• TRON Gasless Transactions in WDK

And after that, more to come. Protocol Integration: Swaps, Bridges, and Lending with WDK, where we layer DeFi functionality on top of these gasless wallets.

Gasless + swaps + bridges + lending = a complete DeFi experience without ever touching native tokens.