@gasfree-kit/ton-gasless

⚠️ Deprecation notice (v2.0.0) — the positional methods TonTransfer.transferUSDT, TonTransfer.checkBalance, and TonTransfer.getTransactionEstimateFee are deprecated in favour of the options-object methods TonTransfer.send, TonTransfer.getBalance, and TonTransfer.estimateFee.

The legacy positional methods will be removed three weeks after the v2.0.0 publish date in the next major release. The new methods throw on failure and return a flat result (no { success, message, data } wrapper). Public TON endpoints are used by default — API keys are now optional but recommended for production traffic.

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 TON wallet from a seed phrase
• 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
 ┌────────────┐ ┌───────────────┐
 │  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

After installing, your package manager will prompt you to install the peer dependencies listed in package.json.

Configuration

All URL/API-key fields are optional — the SDK falls back to the public endpoints exported as TON_PUBLIC_ENDPOINTS. For production traffic, register keys with toncenter.com / tonapi.io and pass them in.

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

// Minimal — uses public endpoints with no API keys.
const minimalConfig: TonGaslessClientConfig = {};

// Production — bring your own keys.
const config: TonGaslessClientConfig = {
  tonCenterApiKey: 'your-toncenter-api-key',
  tonApiSecretKey: 'your-tonapi-secret-key',
  // Optional URL overrides (default to public endpoints):
  // tonCenterUrl: 'https://toncenter.com/api/v2/jsonRPC',
  // tonApiUrl: 'https://tonapi.io',
  // transferMaxFee: 1_000_000,
  // usdtAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
};

Config fields

| Field | Purpose | | ----------------- | -------------------------------------------------------- | | tonCenterUrl | TON Center endpoint. Defaults to TON_PUBLIC_ENDPOINTS. | | tonCenterApiKey | TON Center API key. Optional; recommended for prod. | | tonApiUrl | TON API endpoint. Defaults to TON_PUBLIC_ENDPOINTS. | | tonApiSecretKey | TON API secret key. Optional; recommended for prod. | | 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.getBalance({ seedPhrase, config });

console.log(balance.balance); // "42.50"
console.log(balance.balanceRaw); // 42500000n
console.log(balance.address); // wallet address

4. Estimate the fee

const estimate = await TonTransfer.estimateFee({
  seedPhrase,
  config,
  to: 'EQRecipient...',
  amount: '10.00',
});

console.log(estimate.fee); // "0.05" (gasless commission in USDT)

5. Execute the gasless transfer

const result = await TonTransfer.send({
  seedPhrase,
  config,
  to: 'EQRecipient...',
  amount: '50.00',
});

console.log(result.transactionHash);
console.log(result.fee); // bigint, base units
console.log(result.submittedAt);

The legacy positional methods (transferUSDT, checkBalance, getTransactionEstimateFee) remain available and return the previous { success, message, data } envelope. They are marked @deprecated and wrap the new methods above.

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 TON wallet from a seed phrase 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