npm package: @gasfree-kit/ton-gasless
Description: Gasless USDT transfers on TON via sponsored relay
Latest version: 0.3.0

# @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`](../core/README.md) 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

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

Peer dependencies:

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

## Configuration

```ts
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

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

const seedPhrase = await generateSeedPhrase();
```

### 2. Set up a wallet

```ts
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:

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

### 3. Check USDT balance

```ts
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

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

console.log(estimate.data.fee);
```

### 5. Execute the gasless transfer

```ts
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