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.12, 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

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)

When tx is a Cell, WDK estimates its fee, enforces transactionMaxFee, and passes that exact body to the matching opened WalletContractV5R1.send() call. It does not rebuild the body, refresh its sequence number, or re-sign it.

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)

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 receipt if it has been mined.

Through 1.0.0-beta.12, the initial receipt lookup always queries mainnet TON Center v3. Do not rely on this method for testnet receipts; see Network Selection.

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')
}

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

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 if it has been mined.

Through 1.0.0-beta.12, the initial receipt lookup always queries mainnet TON Center v3. Do not rely on this method for testnet receipts; see Network Selection.

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
   */
  body?: string | Cell;
}

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.12
   * @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?