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 v2 JSON-RPC URL (e.g., 'https://toncenter.com/api/v2/jsonRPC')
    • 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 base URL (e.g., 'https://tonapi.io')
    • secretKey (string, optional): API key for TON API
  • paymasterToken (object): Paymaster token configuration
    • address (string): Supported 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 gasless transfer operations
  • transactionMaxFee (number | bigint, optional): Shared wallet config option; native sendTransaction(), quoteSendTransaction(), and signTransaction() are unsupported on this module

Example:

const wallet = new WalletManagerTonGasless(seedPhrase, {
  tonClient: {
    url: 'https://toncenter.com/api/v2/jsonRPC',
    secretKey: 'your-api-key'
  },
  tonApiClient: {
    url: 'https://tonapi.io',
    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 fee rates from the mainnet TON API configuration. Through 1.0.0-beta.9, this method always requests https://tonapi.io/v2, does not follow the configured client network, and returns the same calculated value for both fields.

Returns: Promise\<{normal: bigint, fast: bigint}\> - 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 cached wallet accounts and signers, clearing their derived private keys. In the current beta, this method does not zero or unset the wallet manager's seed bytes.

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 to build signed native transaction bodies.

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 is typed as Promise<TransactionResult> for wallet-interface compatibility, but it always rejects at runtime. To move funds, use transfer(), which relays a paymaster-funded Jetton transfer.

Parameters:

• tx (TonTransaction): The transaction

Returns: Promise\<TransactionResult\> - Interface-compatible return type; never resolves successfully on this module

Example:

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

quoteSendTransaction(tx)

Not supported on the gasless module. This method is inherited for wallet-interface compatibility and always rejects at runtime. Use quoteTransfer() to estimate gasless Jetton transfer fees.

Parameters:

• tx (TonTransaction): The transaction

Returns: Promise\<Omit\<TransactionResult, 'hash'\>\> - Interface-compatible return type; never resolves successfully on this module

Example:

// Throws: "Method 'quoteSendTransaction(tx)' not supported on ton gasless."
await account.quoteSendTransaction({ 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(), quoteSendTransaction(), and signTransaction() are not supported and reject or throw.

Before signing or submitting, the wallet validates the TON API estimate against the requested Jetton transfer. It rejects an altered transfer body, sender, relay, destination, amount, payload, state initialization, expiry, commission, message count, or paymaster commission transfer. Validation resolves the configured paymaster token's Jetton wallet through tonClient, so this flow includes an additional TON RPC lookup and can fail if that provider is unavailable.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): Token contract address
  • recipient (string): Recipient TON address
  • amount (number | bigint): Amount in token's base units
• config (object, optional): Per-call configuration. When supplied, it replaces the wallet-level transfer configuration for this call.
  • paymasterToken (object, required when config is supplied): Paymaster token for this transfer
    • address (string): Paymaster token address
  • transferMaxFee (number | bigint, optional): Override maximum fee. Transfers throw only when the estimated fee is greater than this cap, so an equal estimate is allowed.

Returns: Promise\<{hash: string, fee: bigint}\> - The signed transfer body hash as lowercase hex and the fee in paymaster Jetton base units

Example:

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

quoteTransfer(options, config?)

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

The quote is returned only after the same relay-estimate validation used by transfer(). A rejected estimate is not signed or submitted.

Parameters:

• options (TransferOptions): Transfer options
  • token (string): Token contract address
  • recipient (string): Recipient TON address
  • amount (number | bigint): Amount in token's base units
• config (object, optional): Per-call configuration. When supplied, it replaces the wallet-level quote configuration for this call.
  • paymasterToken (object, required when config is supplied): Paymaster token for this quote
    • address (string): Paymaster token address

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

quoteTransfer() returns a fee estimate only. It does not submit a transfer or return a transaction hash.

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);

getTransaction(hash)

Looks up the signed message-body hash returned by transfer() and returns the normalized TON receipt. Found transactions are confirmed, becoming final when TON Center supplies mc_block_seqno; TON Center does not expose pending or dropped messages. The receipt includes success when native execution details can determine it, the masterchain block and fee when available, and the native TON transaction on transaction.

Throws: NoSuchElementError when TON Center has not indexed the hash. A configured tonClient is required for native transaction retrieval.

const result = await account.transfer({
  token: 'EQ...',
  recipient: 'EQ...',
  amount: 1000000n
})
const transaction = await account.getTransaction(result.hash)

waitForTransaction(hash, options?)

Polls until TON Center indexes the message and the requested finality is reached. Defaults are target: 'confirmed', interval: 4000, timeout: 60000, and maxPollErrors: 3. Because TON Center exposes neither the mempool nor dropped messages, an unseen or dropped transaction eventually throws TimeoutError.

const transaction = await account.waitForTransaction(result.hash, {
  target: 'final',
  timeout: 120000
})

getTransactionReceipt(hash)

Returns the native TON transaction after inclusion. This method is deprecated; use getTransaction() and read its transaction field instead.

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. String values must be hex encoded.
• config (object): Client, retry, and paymaster configuration. transferMaxFee and transactionMaxFee are not accepted by the read-only constructor.

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)

quoteSendTransaction(tx)

Not supported on the gasless module. This method is present for wallet-interface compatibility and always rejects. Use quoteTransfer() to estimate gasless Jetton transfer fees.

Parameters:

• tx (TonTransaction): The transaction

Returns: Promise\<Omit\<TransactionResult, 'hash'\>\> - Interface-compatible return type; never resolves successfully on this module

Example:

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

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 | bigint): Amount in token's base units
• config (object, optional): Per-call configuration. When supplied, it replaces the account's wallet-level quote configuration for this call.
  • paymasterToken (object, required when config is supplied): Paymaster token for this quote
    • address (string): Paymaster token address

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

quoteTransfer() returns a fee estimate only. It does not submit a transfer or return a transaction hash.

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 the native TON transaction after inclusion. This method is deprecated in favor of getTransaction(). The read-only account's getTransaction() and waitForTransaction() use the same message-body-hash, confirmed/final, timeout, and native transaction semantics documented above.

Parameters:

• hash (string): The signed transfer body hash returned by transfer()

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 v2 JSON-RPC URL @example 'https://toncenter.com/api/v2/jsonRPC' */
  url: string;
  /** Optional API key for TON Center */
  secretKey?: string;
};

type TonApiClientConfig = {
  /** TON API base URL @example 'https://tonapi.io' */
  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;

  /**
   * Shared wallet config option. Native sendTransaction(), quoteSendTransaction(),
   * and signTransaction() are unsupported on this gasless module; use transferMaxFee
   * for gasless transfers.
   */
  transactionMaxFee?: 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 | bigint;
}

TransferResult

interface TransferResult {
  /**
   * Signed transfer body hash as a lowercase hex string; pass it to getTransactionReceipt()
   * @example '7f83b1657ff1fc53b92dc18148a1d65dfa13501404a55e63ddfde593f4f5f9d8'
   */
  hash: string;

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

KeyPair

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

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

Need Help?