Discover and install building blocks to extend your WDK integration.
@tetherto/wdk-wallet-ton-gasless
Gasless transactions on TON
Loading README…
Full Changelog: https://github.com/tetherto/wdk-wallet-ton-gasless/compare/v1.0.0-beta.5...v1.0.0-beta.6
TON blockchain wallet
Bitcoin SegWit wallet with BIP-39/BIP-44 support
Ethereum and EVM-compatible chains wallet
Note: This package is currently in beta. Please test thoroughly in development environments before using in production.
A simple and secure package to manage gasless transactions on the TON blockchain. This package provides a clean API for creating, managing, and interacting with TON wallets using BIP-39 seed phrases and TON-specific derivation paths, with support for gasless transactions through a paymaster system.
This module is part of the WDK (Wallet Development Kit) project, which empowers developers to build secure, non-custodial wallets with unified blockchain access, stateless architecture, and complete user control.
For detailed documentation about the complete WDK ecosystem, visit docs.wallet.tether.io.
tonClient and/or tonApiClient configs to enable automatic round-robin failoverTo install the @tetherto/wdk-wallet-ton-gasless package, follow these instructions:
You can install it using npm:
@tetherto/wdk-wallet-ton-gaslessFor accounts where you have the seed phrase and full access:
For addresses where you don't have the seed phrase:
⚠️ Important Note: Direct transaction sending using sendTransaction() is not supported in WalletAccountTonGasless. This is a gasless implementation that handles transactions through a gasless provider instead of direct blockchain transactions.
For sending tokens, please use the transfer() method instead.
Transfer Jetton tokens and estimate fees using WalletAccountTonGasless. Uses paymaster for gasless operations.
Sign and verify messages using WalletAccountTonGasless.
Retrieve current fee rates using WalletManagerTonGasless.
Clear sensitive data from memory using dispose methods in WalletAccountTonGasless and WalletManagerTonGasless.
| Class | Description | Methods |
|---|---|---|
| WalletManagerTonGasless | Main class for managing TON wallets with gasless features. Extends WalletManager from @tetherto/wdk-wallet. | Constructor, Methods |
| WalletAccountTonGasless | Individual TON wallet account with gasless features. Extends WalletAccountReadOnlyTonGasless and implements IWalletAccount from @tetherto/wdk-wallet. | Constructor, Methods, Properties |
The main class for managing TON wallets with gasless features.
Extends WalletManager from @tetherto/wdk-wallet.
Parameters:
seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytesconfig (object, optional): Configuration object
tonClient (object | TonClient): TON client configuration or instance
url (string): TON Center API URL (e.g., 'https://toncenter.com/api/v3')secretKey (string, optional): API key for TON CentertonApiClient (object | TonApiClient): TON API client configuration or instance
url (string): TON API URL (e.g., 'https://tonapi.io/v3')secretKey (string, optional): API key for TON APIpaymasterToken (object): Paymaster token configuration
address (string): The address of the paymaster tokentransferMaxFee (number | bigint, optional): Maximum fee amount for transfer operations (in nanotons)Example:
| Method | Description | Returns |
|---|---|---|
getAccount(index) | Returns a wallet account at the specified index | Promise<WalletAccountTonGasless> |
getAccountByPath(path) | Returns a wallet account at the specified BIP-44 derivation path | Promise<WalletAccountTonGasless> |
getFeeRates() | Returns current fee rates for transactions | Promise<{normal: bigint, fast: bigint}> |
dispose() | Disposes all wallet accounts, clearing private keys from memory | void |
getAccount(index)Returns a gasless TON wallet account at the specified index using BIP-44 derivation path m/44'/607'.
Parameters:
index (number, optional): The index of the account to get (default: 0)Returns: Promise<WalletAccountTonGasless> - The gasless TON wallet account
Example:
getAccountByPath(path)Returns a gasless TON wallet account at the specified BIP-44 derivation path.
Parameters:
path (string): The derivation path (e.g., "0'/0/0", "1'/0/5")Returns: Promise<WalletAccountTonGasless> - The gasless TON wallet account
Example:
getFeeRates()Returns current fee rates for TON transactions (used by paymaster for gasless operations).
Returns: Promise<{normal: bigint, fast: bigint}> - Object containing fee rates in nanotons
normal: Standard fee rate for normal confirmation speedfast: Higher fee rate for faster confirmationExample:
dispose()Disposes all gasless TON wallet accounts and clears sensitive data from memory.
Returns: void
Example:
Represents an individual wallet account with gasless features. Implements IWalletAccount from @tetherto/wdk-wallet.
Parameters:
seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytespath (string): BIP-44 derivation path (e.g., "0'/0/0")config (object, optional): Configuration object
tonClient (object | TonClient): TON client configuration or instance
url (string): TON Center API URLsecretKey (string, optional): API key for TON CentertonApiClient (object | TonApiClient): TON API client configuration or instance
url (string): TON API URLsecretKey (string, optional): API key for TON APIpaymasterToken (object): Paymaster token configuration
address (string): The address of the paymaster tokentransferMaxFee (number | bigint, optional): Maximum fee amount for transfer operations (in nanotons)| Method | Description | Returns |
|---|---|---|
getAddress() | Returns the account's TON address | Promise<string> |
sign(message) | Signs a message using the account's private key | Promise<string> |
verify(message, signature) | Verifies a message signature | Promise<boolean> |
transfer(options, config?) | Transfers tokens using gasless transactions | Promise<{hash: string, fee: bigint}> |
quoteTransfer(options, config?) | Estimates the fee for a token transfer | Promise<{fee: bigint}> |
getBalance() | Returns the native TON balance (in nanotons) | Promise<bigint> |
getTokenBalance(tokenAddress) | Returns the balance of a specific token | Promise<bigint> |
getPaymasterTokenBalance() | Returns the balance of the paymaster token | Promise<bigint> |
dispose() | Disposes the wallet account, clearing private keys from memory | void |
getAddress()Returns the account's TON address.
Returns: Promise<string> - The TON address
Example:
sign(message)Signs a message using the account's private key.
Parameters:
message (string): Message to signReturns: Promise<string> - Signature as hex string
Example:
verify(message, signature)Verifies a message signature using the account's public key.
Parameters:
message (string): Original messagesignature (string): Signature as hex stringReturns: Promise<boolean> - True if signature is valid
Example:
transfer(options, config?)Transfers tokens using gasless transactions where the paymaster covers transaction fees.
Parameters:
options (object): Transfer options
token (string): Token contract address (e.g., 'EQ...')recipient (string): Recipient TON address (e.g., 'EQ...')amount (number | bigint): Amount in token's base unitsconfig (object, optional): Override configuration
paymasterToken (object, optional): Override default paymaster token
address (string): Paymaster token addresstransferMaxFee (number | bigint, optional): Override maximum feeReturns: Promise<{hash: string, fee: bigint}> - Object containing hash and fee (typically 0 or covered by paymaster)
Example:
quoteTransfer(options, config?)Estimates the fee for a token transfer (typically covered by paymaster in gasless operations).
Parameters:
options (object): Same as transfer parameters
token (string): Token contract addressrecipient (string): Recipient TON addressamount (number | bigint): Amount in token's base unitsconfig (object, optional): Same as transfer configuration
paymasterToken (object, optional): Override default paymaster tokentransferMaxFee (number | bigint, optional): Override maximum feeReturns: Promise<{fee: bigint}> - Object containing estimated fee (typically 0 or covered by paymaster)
Example:
getBalance()Returns the account's native TON balance in nanotons.
Returns: Promise<bigint> - Balance in nanotons
Example:
getTokenBalance(tokenAddress)Returns the balance of a specific token (Jetton).
Parameters:
tokenAddress (string): The token contract addressReturns: Promise<bigint> - Token balance in token's smallest unit
Example:
getPaymasterTokenBalance()Returns the balance of the paymaster token used for gasless operations.
Returns: Promise<bigint> - Paymaster token balance in token's smallest unit
Example:
dispose()Disposes the wallet account, securely erasing the private key from memory.
Returns: void
Example:
| Property | Type | Description |
|---|---|---|
index | number | The derivation path's index of this account |
path | string | The full derivation path of this account |
keyPair | object | The account's key pair (⚠️ Contains sensitive data) |
⚠️ Security Note: The keyPair property contains sensitive cryptographic material. Never log, display, or expose the private key.
Represents a read-only wallet account with gasless features.
Parameters:
publicKey (string | Uint8Array): The account's public keyconfig (object, optional): Configuration object
tonClient (object | TonClient): TON client configuration or instance
url (string): TON Center API URLsecretKey (string, optional): API key for TON CentertonApiClient (object | TonApiClient): TON API client configuration or instance
url (string): TON API URLsecretKey (string, optional): API key for TON APIpaymasterToken (object): Paymaster token configuration
address (string): The address of the paymaster token| Method | Description | Returns |
|---|---|---|
getBalance() | Returns the native TON balance (in nanotons) | Promise<bigint> |
getTokenBalance(tokenAddress) | Returns the balance of a specific token | Promise<bigint> |
getPaymasterTokenBalance() | Returns the balance of the paymaster token | Promise<bigint> |
quoteTransfer(options, config?) | Estimates the fee for a token transfer | Promise<{fee: bigint}> |
verify(message, signature) | Verifies a message signature | Promise<boolean> |
getBalance()Returns the account's native TON balance in nanotons.
Returns: Promise<bigint> - Balance in nanotons
Example:
getTokenBalance(tokenAddress)Returns the balance of a specific token (Jetton).
Parameters:
tokenAddress (string): The token contract addressReturns: Promise<bigint> - Token balance in token's smallest unit
Example:
getPaymasterTokenBalance()Returns the balance of the paymaster token used for gasless operations.
Returns: Promise<bigint> - Paymaster token balance in token's smallest unit
Example:
quoteTransfer(options, config?)Estimates the fee for a token transfer (typically covered by paymaster in gasless operations).
Parameters:
options (object): Transfer options
token (string): Token contract addressrecipient (string): Recipient TON addressamount (number | bigint): Amount in token's base unitsconfig (object, optional): Override configuration
paymasterToken (object, optional): Override default paymaster token
address (string): Paymaster token addresstransferMaxFee (number | bigint, optional): Override maximum feeReturns: Promise<{fee: bigint}> - Object containing estimated fee (typically 0 or covered by paymaster)
Example:
verify(message, signature)Verifies a message signature using the account's public key.
Parameters:
message (string): Original messagesignature (string): Signature as hex stringReturns: Promise<boolean> - True if signature is valid
Example:
This package works with the TON blockchain, including:
dispose() method to clear private keys from memory when donetransferMaxFee in config to prevent excessive transaction feesThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
For support, please open an issue on the GitHub repository.
| WalletAccountReadOnlyTonGasless | Read-only TON wallet account with gasless features. Extends WalletAccountReadOnly from @tetherto/wdk-wallet. | Constructor, Methods |
npm install @tetherto/wdk-wallet-ton-gaslessimport WalletManagerTonGasless, {
WalletAccountTonGasless,
WalletAccountReadOnlyTonGasless
} from '@tetherto/wdk-wallet-ton-gasless'
// Use a BIP-39 seed phrase (replace with your own secure phrase)
const seedPhrase = 'test only example nut use this real life secret phrase must random'
// Create wallet manager with TON client config
const wallet = new WalletManagerTonGasless(seedPhrase, {
tonClient: {
url: 'https://toncenter.com/api/v3',
secretKey: 'your-api-key' // Optional
},
tonApiClient: {
url: 'https://tonapi.io/v3',
secretKey: 'your-ton-api-key' // Optional
},
paymasterToken: {
address: 'EQ...' // Paymaster token contract address
},
transferMaxFee: 1000000000n // Optional: Maximum fee in nanotons
})
// Get a full access account
const account = await wallet.getAccount(0)
// Convert to a read-only account
const readOnlyAccount = await account.toReadOnlyAccount()import WalletManagerTonGasless from '@tetherto/wdk-wallet-ton-gasless'
// Assume wallet is already created
// Get the first account (index 0)
const account = await wallet.getAccount(0)
const address = await account.getAddress()
console.log('Account 0 address:', address)
// Get the second account (index 1)
const account1 = await wallet.getAccount(1)
const address1 = await account1.getAddress()
console.log('Account 1 address:', address1)
// Get account by custom derivation path
// Full path will be m/44'/607'/0'/0/5
const customAccount = await wallet.getAccountByPath("0'/0/5")
const customAddress = await customAccount.getAddress()
console.log('Custom account address:', customAddress)
// Note: All addresses are TON addresses (EQ... or UQ...)
// All accounts inherit the provider configuration from the wallet managerimport WalletManagerTonGasless from '@tetherto/wdk-wallet-ton-gasless'
// Assume wallet and account are already created
// Get native TON balance (in nanotons)
const balance = await account.getBalance()
console.log('Native TON balance:', balance, 'nanotons') // 1 TON = 1000000000 nanotons
// Get Jetton token balance
const jettonContract = 'EQ...'; // Jetton contract address
const jettonBalance = await account.getTokenBalance(jettonContract);
console.log('Jetton balance:', jettonBalance);
// Get paymaster token balance (important for gasless operations)
const paymasterBalance = await account.getPaymasterTokenBalance();
console.log('Paymaster token balance:', paymasterBalance);
// Note: TON client is required for balance checks
// Make sure wallet was created with a tonClient configurationimport { WalletAccountReadOnlyTonGasless } from '@tetherto/wdk-wallet-ton-gasless'
// Create a read-only account with public key
const publicKey = '...'; // Replace with the actual public key
const readOnlyAccount = new WalletAccountReadOnlyTonGasless(publicKey, {
tonClient: {
url: 'https://toncenter.com/api/v3',
secretKey: 'your-api-key' // Optional
},
tonApiClient: {
url: 'https://tonapi.io/v3',
secretKey: 'your-ton-api-key' // Optional
},
paymasterToken: {
address: 'EQ...' // Paymaster token contract address
}
})
// Check native TON balance
const balance = await readOnlyAccount.getBalance()
console.log('Native balance:', balance, 'nanotons')
// Check paymaster token balance
const paymasterBalance = await readOnlyAccount.getPaymasterTokenBalance()
console.log('Paymaster token balance:', paymasterBalance)
// Check any other Jetton token balance
const tokenBalance = await readOnlyAccount.getTokenBalance('EQ...')
console.log('Token balance:', tokenBalance)
// Note: Jetton balance checks use the standard Jetton wallet interface
// Make sure the contract address is correct and implements the Jetton standard// Transfer Jetton tokens using gasless transactions
const transferResult = await account.transfer({
token: 'EQ...', // Jetton contract address
recipient: 'EQ...', // Recipient's TON address
amount: 1000000000n // Amount in Jetton's base units (use BigInt for large numbers)
}, {
paymasterToken: { // Optional: override default paymaster token
address: 'EQ...'
},
transferMaxFee: 1000000000n // Optional: maximum allowed fee
});
console.log('Transfer hash:', transferResult.hash);
console.log('Transfer fee:', transferResult.fee, 'nanotons');
// Quote token transfer fee
const transferQuote = await account.quoteTransfer({
token: 'EQ...', // Jetton contract address
recipient: 'EQ...', // Recipient's TON address
amount: 1000000000n // Amount in Jetton's base units
})
console.log('Transfer fee estimate:', transferQuote.fee, 'nanotons')
// Note: Gas fees are paid by the paymaster token
// Ensure sufficient paymaster token balance before transfers// Sign a message
const message = 'Hello, TON!'
const signature = await account.sign(message)
console.log('Signature:', signature)
// Verify a signature
const isValid = await account.verify(message, signature)
console.log('Signature valid:', isValid)// Get current fee rates
const feeRates = await wallet.getFeeRates();
console.log('Normal fee rate:', feeRates.normal, 'nanotons');
console.log('Fast fee rate:', feeRates.fast, 'nanotons');// Dispose wallet accounts to clear private keys from memory
account.dispose()
// Dispose entire wallet manager
wallet.dispose()new WalletManagerTonGasless(seed, config)const wallet = new WalletManagerTonGasless(seedPhrase, {
tonClient: {
url: 'https://toncenter.com/api/v3',
secretKey: 'your-api-key'
},
tonApiClient: {
url: 'https://tonapi.io/v3',
secretKey: 'your-ton-api-key'
},
paymasterToken: {
address: 'EQ...'
},
transferMaxFee: '1000000000' // Maximum fee in nanotons
})const account = await wallet.getAccount(0)
const address = await account.getAddress()
console.log('Gasless TON account address:', address)const account = await wallet.getAccountByPath("0'/0/1")
const address = await account.getAddress()
console.log('Custom path gasless address:', address)const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'nanotons')
console.log('Fast fee rate:', feeRates.fast, 'nanotons')
// Note: These fees are typically covered by the paymaster in gasless transactionswallet.dispose()
// All gasless accounts and private keys are now securely wiped from memorynew WalletAccountTonGasless(seed, path, config)const address = await account.getAddress()
console.log('Gasless TON address:', address) // EQBvW8Z5...const signature = await account.sign('Hello TON Gasless!')
console.log('Signature:', signature)const isValid = await account.verify('Hello TON Gasless!', signature)
console.log('Signature valid:', isValid)const result = await account.transfer({
token: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', // USDT Jetton
recipient: 'EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG',
amount: 1000000n // 1 USDT (6 decimals)
})
console.log('Gasless transfer hash:', result.hash)
console.log('Fee (covered by paymaster):', result.fee, 'nanotons')const quote = await account.quoteTransfer({
token: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', // USDT Jetton
recipient: 'EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG',
amount: 1000000n // 1 USDT (6 decimals)
})
console.log('Estimated fee (paymaster will cover):', quote.fee, 'nanotons')const balance = await account.getBalance()
console.log('TON balance:', balance, 'nanotons')
console.log('Balance in TON:', Number(balance) / 1e9)// Get USDT Jetton balance (6 decimals)
const usdtBalance = await account.getTokenBalance('EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs')
console.log('USDT balance:', Number(usdtBalance) / 1e6)const paymasterBalance = await account.getPaymasterTokenBalance()
console.log('Paymaster token balance:', paymasterBalance)
// This balance is used to cover transaction fees in gasless operationsaccount.dispose()
// Private key is now securely wiped from memorynew WalletAccountReadOnlyTonGasless(publicKey, config)const balance = await readOnlyAccount.getBalance()
console.log('TON balance:', balance, 'nanotons')
console.log('Balance in TON:', Number(balance) / 1e9)// Get USDT Jetton balance (6 decimals)
const usdtBalance = await readOnlyAccount.getTokenBalance('EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs')
console.log('USDT balance:', Number(usdtBalance) / 1e6)const paymasterBalance = await readOnlyAccount.getPaymasterTokenBalance()
console.log('Paymaster token balance:', paymasterBalance)
// This balance indicates how much the account can use for gasless transactionsconst quote = await readOnlyAccount.quoteTransfer({
token: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', // USDT Jetton
recipient: 'EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG',
amount: 1000000n // 1 USDT (6 decimals)
})
console.log('Estimated fee (paymaster will cover):', quote.fee, 'nanotons')
console.log('Estimated fee in TON:', Number(quote.fee) / 1e9)const isValid = await readOnlyAccount.verify('Hello TON Gasless!', signature)
console.log('Signature valid:', isValid)# Install dependencies
npm install
# Build TypeScript definitions
npm run build:types
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix# Run tests
npm test
# Run tests with coverage
npm run test:coverage