@gasfree-kit/ton-gasless

Gasless USDT transfers on TON through a sponsored relay.

With this package, the user only needs USDT. The relay pays the TON gas and charges a small fee back in USDT.

What This Package Does

• creates a WDK-backed TON wallet
• quotes the relay fee in USDT
• checks that balance covers transfer amount plus fee
• submits the gasless transfer
• returns a transfer context you can log or persist

Transfer Diagram

 ┌──────────────────────────┐
 │         Your app         │
 └────────────┬─────────────┘
              │
              v
 ┌──────────────────────────┐
 │ @gasfree-kit/ton-gasless │
 └──────┬─────────────┬─────┘
        │             │
        v             v
 ┌────────────┐ ┌───────────────┐
 │  WDK TON   │ │  Relay fee    │
 │  wallet    │ │  quote (USDT) │
 └──────┬─────┘ └───────┬───────┘
        │               │
        └───────┬───────┘
                │
                v
 ┌──────────────────────────┐
 │     Sponsored relay      │
 ├──────────────────────────┤
 │  • Pays TON gas          │
 │  • Deducts USDT fee      │
 └────────────┬─────────────┘
              │
              v
 ┌──────────────────────────┐
 │     TON blockchain       │
 └──────────────────────────┘

Prerequisites

This package depends on @gasfree-kit/core for:

• Seed phrase generation — generateSeedPhrase() creates the mnemonic used to set up wallets
• Address validation — validateTonAddress() catches malformed addresses before sending
• Error classes — GasfreeError, InsufficientBalanceError, etc. for consistent error handling

@gasfree-kit/core is installed automatically as a dependency.

Installation

npm install @gasfree-kit/ton-gasless @gasfree-kit/core

Peer dependencies:

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

Configuration

import type { TonGaslessClientConfig } from '@gasfree-kit/ton-gasless';

const config: TonGaslessClientConfig = {
  tonCenterUrl: 'https://toncenter.com/api/v2',
  tonCenterApiKey: 'your-toncenter-api-key',
  tonApiUrl: 'https://tonapi.io',
  tonApiSecretKey: 'your-tonapi-secret-key',
  // Optional:
  // transferMaxFee: 1_000_000,
  // usdtAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
};

Config fields

| Field | Purpose | | ----------------- | -------------------------------------------------- | | tonCenterUrl | TON Center endpoint used by the wallet client | | tonCenterApiKey | TON Center API key | | tonApiUrl | TON API endpoint | | tonApiSecretKey | TON API secret key | | transferMaxFee | Maximum fee limit in base units, capped by the SDK | | usdtAddress | Optional override for the TON USDT root |

Quick Start

1. Generate a seed phrase

import { generateSeedPhrase } from '@gasfree-kit/core';

const seedPhrase = await generateSeedPhrase();

2. Set up a wallet

import { setupTonGaslessWallet } from '@gasfree-kit/ton-gasless';

const { wallet, account, address } = await setupTonGaslessWallet(seedPhrase, config);

console.log(address);

If you need a specific derivation path:

const walletResult = await setupTonGaslessWallet(seedPhrase, config, "0'/0/0");

3. Check USDT balance

import { TonTransfer } from '@gasfree-kit/ton-gasless';

const balance = await TonTransfer.checkBalance(seedPhrase, config);

console.log(balance.data.usdBalance);
console.log(balance.data.tokenBalance);

4. Estimate the fee

const estimate = await TonTransfer.getTransactionEstimateFee(
  seedPhrase,
  config,
  '10.00',
  'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
);

console.log(estimate.data.fee);

5. Execute the gasless transfer

const result = await TonTransfer.transferUSDT(
  seedPhrase,
  config,
  '50.00',
  'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
);

console.log(result.data.transactionHash);
console.log(result.data.fee);

How The Flow Behaves

1. The SDK validates the recipient address.
2. The SDK asks the relay path for a fee quote.
3. The SDK checks that the wallet balance can cover amount + fee.
4. The transfer is submitted.
5. The relay pays TON gas and deducts the fee in USDT.

Main Exports

| Export | What it does | | ------------------------ | ---------------------------------------------------------- | | setupTonGaslessWallet | Creates the WDK-backed TON wallet and resolves the address | | TonTransfer | Checks balances, estimates fees, and sends transfers | | getTonGaslessConfig | Expands and validates the runtime config | | tonUsdtTokenRoot | Built-in TON USDT root address | | usdtTonBaseUnits | Converts human-readable USDT to base units | | fromTonBaseUnitsToUsdt | Converts base units back to readable USDT | | getTonUsdtValue | Utility helper for TON to USDT conversions |

Safety Notes

• transferMaxFee is capped by the SDK to prevent extreme fee deductions
• invalid TON addresses are rejected before sending
• self-transfers are blocked
• the user must have enough USDT for both transfer amount and fee

License

MIT