API Reference

Table of Contents

WalletManagerTonGasless

The main class for managing gasless TON wallets. Extends WalletManager from @tetherto/wdk-wallet.

Constructor

new WalletManagerTonGasless(seed, config)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• config (TonGaslessWalletConfig): Configuration object
  • tonClient (object | TonClient | array): TON client configuration, instance, or an array of configurations or instances for failover
    • url (string): TON Center API URL (e.g., 'https://toncenter.com/api/v3')
    • secretKey (string, optional): API key for TON Center
  • tonApiClient (object | TonApiClient | array): TON API client configuration, instance, or an array of configurations or instances for failover
    • url (string): TON API URL (e.g., 'https://tonapi.io/v2')
    • secretKey (string, optional): API key for TON API
  • paymasterToken (object): Paymaster token configuration
    • address (string): Paymaster Jetton master contract address
  • retries (number, optional): Failover retries used when tonClient and tonApiClient are arrays (default: 3)
  • transferMaxFee (number | bigint, optional): Maximum fee for transfer operations

Example:

const wallet = new WalletManagerTonGasless(seedPhrase, {
  tonClient: {
    url: 'https://toncenter.com/api/v3',
    secretKey: 'your-api-key'
  },
  tonApiClient: {
    url: 'https://tonapi.io/v2',
    secretKey: 'your-tonapi-key'
  },
  paymasterToken: {
    address: 'EQ...'
  },
  retries: 3,
  transferMaxFee: 1000000000
})

Methods

getAccount(index)

Returns a gasless wallet account at the specified index. Index n derives the account at m/44'/607'/n'.

Parameters:

• index (number, optional): The index of the account to get (default: 0)

Returns: Promise\<WalletAccountTonGasless\> - The wallet account

Example:

// Derivation path m/44'/607'/0'
const account = await wallet.getAccount(0)

getAccountByPath(path)

Returns a gasless wallet account at the specified BIP-44 derivation path, relative to m/44'/607'.

Parameters:

• path (string): The derivation path (e.g., "0'")

Returns: Promise\<WalletAccountTonGasless\> - The wallet account

Example:

// Derivation path m/44'/607'/1'
const account = await wallet.getAccountByPath("1'")

getFeeRates()

Returns current fee rates for transactions based on blockchain config.

Returns: Promise\<{normal: number, fast: number}\> - Object containing fee rates

Example:

const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal)
console.log('Fast fee rate:', feeRates.fast)

dispose()

Disposes all wallet accounts, clearing private keys from memory.

Example:

wallet.dispose()

WalletAccountTonGasless

Individual gasless TON wallet account implementation. Extends WalletAccountReadOnlyTonGasless and implements IWalletAccount.

Constructor

new WalletAccountTonGasless(seed, path, config)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• path (string): BIP-44 derivation path (e.g., "0'/0/0")
• config (TonGaslessWalletConfig): Configuration object (same as WalletManagerTonGasless)

Methods

getAddress()

Returns the account's address.

Returns: Promise\<string\> - The account's TON address

Example:

const address = await account.getAddress()
console.log('Account address:', address)

sign(message)

Signs a message using the account's private key.

Parameters:

• message (string): The message to sign

Returns: Promise\<string\> - The message signature

Example:

const signature = await account.sign('Hello, World!')
console.log('Signature:', signature)

signTransaction(tx)

Not supported on the gasless module. This method always throws. The gasless module only supports paymaster-funded Jetton transfers through transfer(). Use the standard @tetherto/wdk-wallet-ton module for offline transaction signing.

Parameters:

• tx (TonTransaction): The transaction

Returns: Promise\<never\> - Never resolves; always throws

Example:

// Throws: "Method 'signTransaction(tx)' not supported on ton gasless."
await account.signTransaction({ to: 'EQ...', value: 1000000000n })

sendTransaction(tx)

Not supported on the gasless module. This method always throws. To move funds, use transfer(), which relays a paymaster-funded Jetton transfer.

Parameters:

• tx (TonTransaction): The transaction

Returns: Promise\<never\> - Never resolves; always throws

Example:

// Throws: "Method 'sendTransaction(tx)' not supported on ton gasless."
await account.sendTransaction({ to: 'EQ...', value: 1000000000n })

verify(message, signature)

Verifies a message signature.

Parameters:

• message (string): The original message
• signature (string): The signature to verify

Returns: Promise\<boolean\> - True if the signature is valid

Example:

const isValid = await account.verify('Hello, World!', signature)
console.log('Signature valid:', isValid)

transfer(options, config?)

Transfers a Jetton using a gasless transaction, paying the fee with the configured paymaster token. This is the only way to move funds on the gasless module: sendTransaction() and signTransaction() are not supported and throw.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): Token contract address
  • recipient (string): Recipient TON address
  • amount (number): Amount in token's base units
• config (object, optional): Override configuration
  • paymasterToken (object, optional): Override default paymaster token
    • address (string): Paymaster token address
  • transferMaxFee (number, optional): Override maximum fee

Returns: Promise\<{hash: string, fee: number}\> - Transfer result

Example:

const result = await account.transfer({
  token: 'EQ...',
  recipient: 'EQ...',
  amount: 1000000000
}, {
  paymasterToken: { address: 'EQ...' },
  transferMaxFee: 2000000000
})

quoteTransfer(options)

Estimates the fee for a Jetton (TON token) transfer.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): Token contract address
  • recipient (string): Recipient TON address
  • amount (number): Amount in token's base units
• config (object, optional): Override configuration
  • paymasterToken (object, optional): Override default paymaster token

Returns: Promise\<{fee: number}\> - Object containing fee estimate (in paymaster token base units)

Example:

const quote = await account.quoteTransfer({
  token: 'EQ...',
  recipient: 'EQ...',
  amount: 1000000000
});
console.log('Transfer fee estimate:', quote.fee, 'paymaster token units');

getBalance()

Returns the native TON balance (in nanotons).

Returns: Promise\<bigint\> - Balance in nanotons

Example:

const balance = await account.getBalance();
console.log('Balance:', balance, 'nanotons');

getTokenBalance(tokenAddress)

Returns the balance of a specific Jetton (TON token).

Parameters:

• tokenAddress (string): The token contract address

Returns: Promise\<bigint\> - Token balance in base units

Example:

const tokenBalance = await account.getTokenBalance('EQ...');
console.log('Token balance:', tokenBalance, 'token base units');

getPaymasterTokenBalance()

Returns the balance of the paymaster Jetton (used for gasless fees).

Returns: Promise\<bigint\> - Paymaster Jetton balance in base units

Example:

const paymasterBalance = await account.getPaymasterTokenBalance();
console.log('Paymaster Jetton balance:', paymasterBalance);

toReadOnlyAccount()

Returns a read-only copy of the account. The same instance is reused on subsequent calls.

Returns: Promise\<WalletAccountReadOnlyTonGasless\> - The read-only account

Example:

const readOnlyAccount = await account.toReadOnlyAccount()

dispose()

Disposes the wallet account, clearing private keys from memory.

Example:

account.dispose()

Properties

The key pair's Uint8Array values are bound to the wallet account: any external change reflects on the internal representation. Treat the key pair as a read-only view of the keys and never mutate its contents.

Example:

const { publicKey, privateKey } = account.keyPair
console.log('Public key length:', publicKey.length)
console.log('Private key length:', privateKey?.length)

WalletAccountReadOnlyTonGasless

Read-only gasless TON wallet account.

Constructor

new WalletAccountReadOnlyTonGasless(publicKey, config)

Parameters:

• publicKey (string | Uint8Array): The account's public key
• config (TonGaslessWalletConfig): Configuration object

Methods

getAddress()

Returns the account's TON address.

Returns: Promise\<string\> - The account's TON address

Example:

const address = await readOnlyAccount.getAddress()
console.log('Account address:', address)

getBalance()

Returns the native TON balance (in nanotons).

Returns: Promise\<bigint\> - Balance in nanotons

Example:

const balance = await readOnlyAccount.getBalance()
console.log('TON balance:', balance, 'nanotons')

getTokenBalance(tokenAddress)

Returns the balance of a specific token.

Parameters:

• tokenAddress (string): The token contract address

Returns: Promise\<bigint\> - Token balance in base units

Example:

const tokenBalance = await readOnlyAccount.getTokenBalance('EQ...')
console.log('Token balance:', tokenBalance, 'token base units')

getPaymasterTokenBalance()

Returns the balance of the paymaster token (used for gasless fees).

Returns: Promise\<bigint\> - Paymaster token balance in base units

Example:

const paymasterBalance = await readOnlyAccount.getPaymasterTokenBalance()
console.log('Paymaster token balance:', paymasterBalance)

quoteTransfer(options, config?)

Estimates the fee for a token transfer.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): Token contract address
  • recipient (string): Recipient TON address
  • amount (number): Amount in token's base units
• config (object, optional): Override configuration
  • paymasterToken (object, optional): Override default paymaster token

Returns: Promise\<{fee: number}\> - Object containing fee estimate (in paymaster token base units)

Example:

const quote = await readOnlyAccount.quoteTransfer({
  token: 'EQ...',
  recipient: 'EQ...',
  amount: 1000000000
})
console.log('Transfer fee estimate:', quote.fee, 'paymaster token units')

verify(message, signature)

Verifies a message signature.

Parameters:

• message (string): The original message
• signature (string): The signature to verify

Returns: Promise\<boolean\> - True if the signature is valid

Example:

const isValid = await readOnlyAccount.verify('Hello, World!', signature)
console.log('Signature valid:', isValid)

getTransactionReceipt(hash)

Returns a transaction's receipt.

Parameters:

• hash (string): The transaction's hash

Returns: Promise\<TonTransactionReceipt | null\> - The receipt, or null if the transaction has not been included in a block yet

Example:

const receipt = await readOnlyAccount.getTransactionReceipt('transaction-hash')
if (receipt) {
  console.log('Transaction receipt:', receipt)
} else {
  console.log('Transaction not yet included in a block')
}

Types

TonGaslessWalletConfig

type TonClientConfig = {
  /** TON Center API URL @example 'https://toncenter.com/api/v3' */
  url: string;
  /** Optional API key for TON Center */
  secretKey?: string;
};

type TonApiClientConfig = {
  /** TON API URL @example 'https://tonapi.io/v2' */
  url: string;
  /** Optional API key for TON API */
  secretKey?: string;
};

type TonGaslessWalletConfig = {
  /**
   * TON client configuration or instance. Provide an array of configurations
   * or instances to enable failover across clients.
   */
  tonClient: TonClientConfig | TonClient | Array<TonClientConfig | TonClient>;

  /**
   * TON API client configuration or instance. Provide an array of
   * configurations or instances to enable failover across API clients.
   */
  tonApiClient: TonApiClientConfig | TonApiClient | Array<TonApiClientConfig | TonApiClient>;

  /**
   * Paymaster token configuration
   */
  paymasterToken: {
    /** Paymaster Jetton master contract address @example 'EQ...' */
    address: string;
  };

  /**
   * Additional failover retry attempts after the initial call fails, used only
   * when tonClient and tonApiClient are arrays. Total attempts = 1 + retries.
   * @default 3
   */
  retries?: number;

  /**
   * Maximum fee for transfer operations (in paymaster Jetton base units)
   */
  transferMaxFee?: number | bigint;
};

TransferOptions

interface TransferOptions {
  /**
   * Token contract address
   * @example 'EQ...'
   */
  token: string;

  /**
   * Recipient's TON address
   * @example 'EQ...'
   */
  recipient: string;

  /**
   * Amount in token's base units
   */
  amount: number;
}

TransferResult

interface TransferResult {
  /**
   * Transaction hash
   */
  hash: string;

  /**
   * Fee paid in paymaster token units
   */
  fee: number;
}

KeyPair

type KeyPair = {
  /**
   * Public key bytes
   */
  publicKey: Uint8Array;

  /**
   * Private key bytes (sensitive data). Set to null after dispose().
   */
  privateKey: Uint8Array | null;
}

Need Help?