API Reference

API Reference

Table of Contents

WalletManagerTon

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

Constructor

new WalletManagerTon(seed, config)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
• config (object): Configuration object
  • tonClient (object | TonClient): TON client configuration or instance
    • url (string): TON Center v2 JSON-RPC URL (e.g., 'https://toncenter.com/api/v2/jsonRPC')
    • secretKey (string, optional): API key for TON Center
  • transferMaxFee (number | bigint, optional): Maximum fee amount for transfer operations (in nanotons)
  • transactionMaxFee (number | bigint, optional): Maximum fee amount for native sendTransaction() and signTransaction() operations (in nanotons)

Example:

const wallet = new WalletManagerTon(seedPhrase, {
  tonClient: {
    url: 'https://toncenter.com/api/v2/jsonRPC',
    secretKey: 'your-api-key'
  },
  transferMaxFee: 1000000000, // Maximum Jetton transfer fee in nanotons
  transactionMaxFee: 1000000000 // Maximum native send/sign fee in nanotons
})

Methods

getAccount(index)

Returns a wallet account at the specified index.

Parameters:

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

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

Example:

const account = await wallet.getAccount(0)

getAccountByPath(path)

Returns a wallet account at the specified BIP-44 derivation path.

Parameters:

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

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

Example:

const account = await wallet.getAccountByPath("0'/0/1")

getFeeRates()

Returns normal and fast fee rates from the mainnet TON API configuration. Through 1.0.0-beta.14, this method always requests https://tonapi.io/v2, does not follow the configured tonClient network, and returns the same calculated value for both fields.

Returns: Promise\<FeeRates\> - Object containing normal and fast fee rates

Example:

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

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

Properties

seed

The wallet manager's sensitive raw seed bytes. A manager created with a seed phrase converts it to bytes before storing it; a signer-backed manager returns undefined.

Type: Uint8Array | undefined

WalletAccountTon

Individual TON wallet account implementation. Extends WalletAccountReadOnlyTon and implements IWalletAccount.

Constructor

new WalletAccountTon(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 (object): Configuration object
  • tonClient (object | TonClient): TON client configuration or instance
    • url (string): TON Center v2 JSON-RPC URL
    • secretKey (string, optional): API key for TON Center
  • transferMaxFee (number | bigint, optional): Maximum fee amount for transfer operations
  • transactionMaxFee (number | bigint, optional): Maximum fee amount for native sendTransaction() and signTransaction() operations

Example:

const account = new WalletAccountTon(seedPhrase, "0'/0/0", {
  tonClient: {
    url: 'https://toncenter.com/api/v2/jsonRPC',
    secretKey: 'your-api-key'
  },
  transferMaxFee: 10000000, // Maximum Jetton transfer fee in nanotons
  transactionMaxFee: 10000000 // Maximum native send/sign fee in nanotons
})

Methods

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 readOnlyAccount = new WalletAccountReadOnlyTon(publicKey, { tonClient: { url: '...' } })
const isValid = await readOnlyAccount.verify('Hello, World!', signature)
console.log('Signature valid:', isValid)

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)

Builds and signs an external-message body without broadcasting it. This is not an offline operation: it requires a configured TON client to read the wallet's current sequence number and, when transactionMaxFee is set, to estimate the fee. Added in v1.0.0-beta.8.

Parameters:

• tx (object): The transaction object (same shape as sendTransaction)
  • to (string): Recipient TON address (e.g., 'EQ...')
  • value (number | bigint): Amount in nanotons (1 TON = 1,000,000,000 nanotons)
  • bounceable (boolean, optional): Whether the destination address is bounceable
  • body (string | Cell, optional): Optional message body. A string whose decoded first four bytes match a TON BoC magic is decoded as a base64-serialized Cell; any other string is sent as a text comment. A magic-prefixed string that is not a valid BoC throws.

Returns: Promise\<Cell\> - The signed body as a TON Cell. It is the body accepted by the matching opened WalletContractV5R1.send() call, not a complete external-message BOC that can be posted directly to TON Center.

Throws: Error if the estimated transaction fee exceeds transactionMaxFee when configured.

Example:

const cell = await account.signTransaction({
  to: 'EQ...', // TON address
  value: 1000000000 // 1 TON in nanotons
});
// `cell` is not broadcast by signTransaction().

sendTransaction(tx)

Sends a TON transaction and returns its signed transfer body hash and fee.

Parameters:

• tx (TonTransaction | Cell): A transaction object or signed transfer-body Cell
  • to (string): Recipient TON address (e.g., 'EQ...')
  • value (number | bigint): Amount in nanotons (1 TON = 1,000,000,000 nanotons)
  • bounceable (boolean, optional): Whether the address is bounceable (TON-specific, optional)
  • body (string | Cell, optional, object input): A Cell is used as the message body. A string whose decoded first four bytes match a TON BoC magic is decoded as a base64-serialized Cell; any other string is sent as a text comment. A magic-prefixed string that is not a valid BoC throws.

When tx is a top-level Cell, WDK estimates its fee, enforces transactionMaxFee, and passes that exact signed transfer body to the matching opened WalletContractV5R1.send() call. It does not rebuild the body, refresh its sequence number, or re-sign it. A base64 string in TonTransaction.body is an object-input message body, not a complete signed transaction.

Returns: Promise\<{hash: string, fee: bigint}\> - Object containing the signed transfer body hash as lowercase hex and the fee in nanotons

Throws: Error if the estimated transaction fee exceeds transactionMaxFee when configured.

Example:

const result = await account.sendTransaction({
  to: 'EQ...', // TON address
  value: 1000000000 // 1 TON in nanotons
});
console.log('Signed transfer body hash:', result.hash);
console.log('Transaction fee:', result.fee, 'nanotons');

quoteSendTransaction(tx)

Estimates the fee for a transaction.

Parameters:

• tx (TonTransaction | Cell): A transaction object or signed transfer-body Cell
  • to (string): Recipient TON address (e.g., 'EQ...')
  • value (number | bigint): Amount in nanotons (1 TON = 1,000,000,000 nanotons)
  • bounceable (boolean, optional): Whether the address is bounceable (TON-specific, optional)
  • body (string | Cell, optional, object input): A Cell is used as the message body. A string whose decoded first four bytes match a TON BoC magic is decoded as a base64-serialized Cell; any other string is sent as a text comment. A magic-prefixed string that is not a valid BoC throws.

Returns: Promise\<{fee: bigint}\> - Object containing fee estimate (in nanotons)

Example:

const quote = await account.quoteSendTransaction({
  to: 'EQ...', // TON address
  value: 1000000000 // 1 TON in nanotons
});
console.log('Estimated fee:', quote.fee, 'nanotons');

transfer(options)

Transfers Jettons (TON tokens) to another address.

Parameters:

• options (object): Transfer options
  • token (string): Jetton master contract address (TON format, e.g., 'EQ...')
  • recipient (string): Recipient TON address (e.g., 'EQ...')
  • amount (number | bigint): Amount in Jetton's base units

Returns: Promise\<{hash: string, fee: bigint}\> - Object containing the signed transfer body hash as lowercase hex and the fee in nanotons

Example:

const result = await account.transfer({
  token: 'EQ...',      // Jetton master contract address
  recipient: 'EQ...',  // Recipient's TON address
  amount: 1000000000    // Amount in Jetton's base units
});
console.log('Signed transfer body hash:', result.hash);
console.log('Transfer fee:', result.fee, 'nanotons');

quoteTransfer(options)

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

Parameters:

• options (object): Transfer options (same as transfer)
  • token (string): Jetton master contract address (TON format, e.g., 'EQ...')
  • recipient (string): Recipient TON address (e.g., 'EQ...')
  • amount (number | bigint): Amount in Jetton's base units

Returns: Promise\<{fee: bigint}\> - Object containing fee estimate (in nanotons)

Example:

const quote = await account.quoteTransfer({
  token: 'EQ...',      // Jetton master contract address
  recipient: 'EQ...',  // Recipient's TON address
  amount: 1000000000    // Amount in Jetton's base units
});
console.log('Transfer fee estimate:', quote.fee, 'nanotons');

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 Jetton master contract address (TON format, e.g., 'EQ...')

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

Example:

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

getTransactionReceipt(hash)

Returns a transaction's native TON receipt if it has been included in a block. This method is deprecated; use getTransaction() for normalized finality and read its transaction field when you need the native object.

Parameters:

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

Returns: Promise\<TonTransactionReceipt | null\> - Transaction receipt or null if not yet mined

Example:

const result = await account.sendTransaction({
  to: 'EQ...',
  value: 1000000000n
})
const receipt = await account.getTransactionReceipt(result.hash)

if (receipt) {
  console.log('Transaction receipt:', receipt)
} else {
  console.log('Transaction not yet included in a block')
}

getTransaction(hash)

Looks up the signed message-body hash returned by sendTransaction() or transfer() through TON Center v3, then retrieves the native TON transaction through the configured tonClient.

TON Center indexes a transaction only after block inclusion. A found transaction is therefore confirmed, or final when TON Center supplies mc_block_seqno; this API does not expose a pending or dropped state. success is false for aborted or failed compute/action phases, true for a successful generic transaction, and undefined when the native result cannot determine execution success. The receipt also exposes the masterchain block, total fee when available, and native transaction.

Returns: Promise\<TransactionReceipt & TonTransactionDetails\>

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

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

console.log(transaction.finality) // 'confirmed' or 'final'
console.log(transaction.success)  // true, false, or undefined

waitForTransaction(hash, options?)

Polls until TON Center indexes the message and the requested finality is reached. The 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
})

toReadOnlyAccount()

Returns a read-only copy of the account. The read-only account exposes balance and verification methods without holding the private key. The instance is cached, so repeated calls return the same read-only account.

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

Example:

const readOnlyAccount = await account.toReadOnlyAccount()
const address = await readOnlyAccount.getAddress()

dispose()

Disposes the wallet account, clearing private keys from memory.

Example:

account.dispose()

Properties

The key pair arrays are bound to the wallet account: any external change to them is reflected in the account's internal state. Treat the key pair as a read-only view 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)

WalletAccountReadOnlyTon

Read-only TON wallet account.

Constructor

new WalletAccountReadOnlyTon(publicKey, config)

Parameters:

• publicKey (string | Uint8Array): The account's public key. String values must be hex encoded.
• config (object): TON client and retry configuration without send-only fee caps

Methods

getAddress()

Returns the account's address.

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

getBalance()

Returns the native TON balance.

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

getTokenBalance(tokenAddress)

Returns the balance of a specific Jetton.

Parameters:

• tokenAddress (string): The Jetton master contract address

Returns: Promise\<bigint\> - Token balance

quoteSendTransaction(tx)

Estimates the fee for a TON transaction without signing or broadcasting it. For object inputs, a body string whose decoded first four bytes match a TON BoC magic is decoded as a base64-serialized Cell; any other string remains a text comment. A magic-prefixed string that is not a valid BoC throws.

Parameters:

• tx (TonTransaction): The transaction object
  • to (string): Recipient TON address
  • value (number | bigint): Amount in nanotons
  • bounceable (boolean, optional): Whether the destination address is bounceable
  • body (string | Cell, optional): Reviewed message body

Returns: Promise\<{fee: bigint}\> - Fee estimate in nanotons

Throws: Error if no TON client is configured or a magic-prefixed body is not a valid serialized BoC.

Example:

async function quoteReviewedTransaction(readOnlyAccount, reviewedTransaction) {
  const quote = await readOnlyAccount.quoteSendTransaction(reviewedTransaction)
  console.log('Estimated fee:', quote.fee, 'nanotons')
  return quote
}

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 native TON receipt if it has been included in a block. 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 sendTransaction() or transfer()

Returns: Promise\<TonTransactionReceipt | null\> - Transaction receipt or null if not yet mined

Example:

async function logTransactionReceipt(readOnlyAccount, transactionHash) {
  const receipt = await readOnlyAccount.getTransactionReceipt(transactionHash)

  if (receipt) {
    console.log('Transaction receipt:', receipt)
  } else {
    console.log('Transaction not yet included in a block')
  }
}

Types

TonTransaction

interface TonTransaction {
  /**
   * Recipient's TON address in base64 format
   * @example 'EQD4FPq...'
   */
  to: string;

  /**
   * Amount to send in nanotons (1 TON = 1,000,000,000 nanotons)
   * @example 1000000000 // 1 TON
   */
  value: number | bigint;

  /**
   * If set, overrides the bounceability of the transaction
   */
  bounceable?: boolean;

  /**
   * Optional message body. A string whose decoded first four bytes match a TON BoC magic
   * is decoded as a base64-serialized Cell; any other string is sent as a text comment.
   * A magic-prefixed string that is not a valid BoC throws.
   */
  body?: string | Cell;
}

body is part of the transaction-object input. The separate top-level Cell accepted by sendTransaction() and quoteSendTransaction() is a signed transfer body, not a base64 string supplied as TonTransaction.body.

Cell

The signed transaction body returned by signTransaction() is a Cell from @ton/core. It is not re-exported by @tetherto/wdk-wallet-ton.

import type { Cell } from '@ton/core'

This value is the signed transfer body accepted by the matching opened WalletContractV5R1.send() call. It is not a complete external-message BOC.

TransferOptions

interface TransferOptions {
  /**
   * Jetton master contract address
   * @example 'EQD4FPq...'
   */
  token: string;

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

  /**
   * Amount in Jetton's base units
   * @example 1000000000 // Amount depends on token decimals
   */
  amount: number | bigint;
}

TransactionResult

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

  /**
   * Transaction fee in nanotons
   * @example 100000n // 0.0001 TON
   */
  fee: bigint;
}

FeeRates

interface FeeRates {
  /**
   * Mainnet-derived fee rate in nanotons
   * @example 100000000n // 0.1 TON
   */
  normal: bigint;

  /**
   * Same mainnet-derived fee rate as `normal` through v1.0.0-beta.14
   * @example 100000000n // 0.1 TON
   */
  fast: bigint;
}

KeyPair

interface KeyPair {
  /**
   * Ed25519 public key
   */
  publicKey: Uint8Array;

  /**
   * Ed25519 private key (sensitive data; null after the account is disposed)
   * @security Never expose or log this value
   */
  privateKey: Uint8Array | null;
}

TonWalletConfig

interface TonWalletConfig {
  /**
   * TON Center client configuration, a TonClient instance, or an array of
   * either. When an array is provided, any thrown Error causes the wallet to
   * retry on the next client by default.
   */
  tonClient?: TonClientConfig | TonClient | Array<TonClientConfig | TonClient>;

  /**
   * Number of additional retry attempts after the initial call fails, used
   * only when tonClient is an array. Total attempts = 1 + retries.
   * @default 3
   */
  retries?: number;

  /**
   * Maximum allowed fee for transfers (in nanotons)
   * @example 1000000000 // 1 TON
   */
  transferMaxFee?: number | bigint;

  /**
   * Maximum allowed fee for native send/sign operations (in nanotons)
   * @example 1000000000 // 1 TON
   */
  transactionMaxFee?: number | bigint;
}

interface TonClientConfig {
  /**
   * TON Center API endpoint
   * @example 'https://toncenter.com/api/v2/jsonRPC'
   */
  url: string;

  /**
   * Optional API key for higher rate limits
   */
  secretKey?: string;
}

Need Help?