@tetherto/wdk-wallet-ton-gasless

Note: This package is currently in beta. Please test thoroughly in development environments before using in production.

Manage TON wallets and relay Jetton transfers through TON API gasless paymaster flows. The package derives TON accounts from BIP-39 seed phrases, reads native TON and Jetton balances, and pays transfer fees with a configured paymaster Jetton instead of native TON.

About WDK

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.wdk.tether.io.

Installation

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

Quick Start

Existing wallets: getAccount(index) changed its default derivation in v1.0.0-beta.5, from m/44'/607'/0'/0/{index} to m/44'/607'/{index}'. The same seed therefore produces different addresses after upgrading from v1.0.0-beta.4 or earlier. Use getAccountByPath("0'/0/0") to reopen the old account at index 0; see Configuration for migration details.

Provide a TON Center JSON-RPC client for chain queries, a TON API client for gasless estimation and relay, and a paymaster Jetton supported by the service's gasless configuration. Use the TON API origin without /v2; the client adds that prefix. Add secretKey to either client configuration from secure runtime configuration when your provider requires one.

Gasless operations support Jetton transfers through transfer() only. Native sendTransaction(), quoteSendTransaction(), and signTransaction() are not supported.

The mnemonic below is public test data; never use it to hold funds. Keep seed phrases and API keys out of source control. This example requires configuration: replace every EQ... placeholder with a valid mainnet address, and adjust the amount and fee cap for the selected Jettons' decimals. Before transferring, verify the token, recipient, and paymaster addresses; check the account's transfer-token and paymaster-token balances; and set transferMaxFee. Quoted and charged fees use the paymaster Jetton's base units.

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

const seedPhrase = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'

const wallet = new WalletManagerTonGasless(seedPhrase, {
  tonClient: {
    url: 'https://toncenter.com/api/v2/jsonRPC',
  },
  tonApiClient: {
    url: 'https://tonapi.io',
  },
  paymasterToken: {
    address: 'EQ...', // Paymaster Jetton master contract address
  },
  transferMaxFee: 10_000_000n, // Paymaster Jetton base units
})

try {
  const account = await wallet.getAccount(0)
  const paymasterBalance = await account.getPaymasterTokenBalance()
  console.log('Paymaster token balance:', paymasterBalance)

  const transfer = {
    token: 'EQ...', // Jetton master contract address
    recipient: 'EQ...',
    amount: 1_000_000n, // Jetton base units
  }

  const quote = await account.quoteTransfer(transfer)
  console.log('Estimated fee:', quote.fee)

  const result = await account.transfer(transfer)
  console.log('Transaction hash:', result.hash)
} finally {
  wallet.dispose()
}

Key Capabilities

• BIP-44 Derivation Paths: Derive TON accounts under m/44'/607'
• Multi-Account Management: Derive multiple accounts from one seed phrase
• Gasless Jetton Transfers: Estimate and relay Jetton transfers through TON API's gasless service
• Paymaster Fee Controls: Pay commissions in a configured Jetton and reject transfers above transferMaxFee
• TON and Jetton Balances: Query native TON, Jetton, and paymaster-token balances
• Transaction Tracking: Look up transactions with getTransaction() and poll for finality with waitForTransaction()
• Provider Failover: Supply arrays of TON Center and TON API clients with configurable retries
• Message Signing: Sign messages and verify signatures with TON accounts
• Read-Only Accounts: Monitor TON wallets from public keys without private-key access
• Secure Memory Disposal: Clear private keys from memory when done

Compatibility

• TON Mainnet
• TON Testnet with matching TON Center and TON API testnet clients and a supported paymaster Jetton. getFeeRates() still returns mainnet fee rates, regardless of the configured clients.
• TON Center-compatible clients with JSON-RPC for chain queries and /api/v3 on the same origin for transaction lookup
• TON API endpoints with gasless support for fee estimation and transaction relay
• Node.js and Bare runtimes

Documentation

Community

Join the WDK Discord to connect with other developers.

Support

For support, please open an issue on GitHub or reach out via email.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.