How to work with Toncoin using WalletKit on the Web platform

To work with Toncoin, the wallet service needs to handle contract balances and perform transfers initiated from dApps and from within the wallet service itself.

Balances

Blockchain state changes constantly as new blocks are produced. This has implications for when and how to check TON wallet contract balances:

• Discrete one-off checks have almost no value on their own — the state might change immediately after the query completes, invalidating its results. Thus, such checks are only practical when handling transaction requests.
• Continuous monitoring is useful for UI display, showing the most recent balance to users, but should not be used for transaction confirmations.

Notice that both cases require querying the blockchain data via the API client set during the WalletKit initialization. Obtain and provide the key from the selected client to access higher requests-per-second limits.

On-demand balance check

Use the getBalance() method to check the wallet contract balance in TON wallets managed by WalletKit. The balance is returned in nanoToncoin, with 1 Toncoin equal to 10⁹ nanoToncoin.

TypeScript

async function getBalance(walletId: string): Promise<string | undefined> {
  // Get TON wallet instance
  const wallet = kit.getWallet(walletId);
  if (!wallet) return;

  // Query its balance in nanoToncoin
  return await wallet.getBalance();
}

The most practical use of one-off balance checks is right before approving a transaction request. At this point, the actual wallet contract balance usually is not less than the checked amount, though it might be higher if new funds arrived right after the check.

TypeScript

// An enumeration of various common error codes
import { SEND_TRANSACTION_ERROR_CODES } from '@ton/walletkit';

kit.onTransactionRequest(async (event) => {
  const wallet = kit.getWallet(event.walletId ?? '');
  if (!wallet) {
    console.error('Wallet not found for a transaction request', event);
    await kit.rejectTransactionRequest(event, {
      code: SEND_TRANSACTION_ERROR_CODES.UNKNOWN_ERROR,
      message: 'Wallet not found',
    });
    return;
  }

  // Calculate the minimum balance needed for this transaction
  const balance = BigInt(await wallet.getBalance());
  const minNeededBalance = event.request.messages.reduce(
    (acc, message) => acc + BigInt(message.amount),
    0n,
  );

  // Reject early if balance is clearly insufficient
  if (balance < minNeededBalance) {
    await kit.rejectTransactionRequest(event, {
      code: SEND_TRANSACTION_ERROR_CODES.BAD_REQUEST_ERROR,
      message: 'Insufficient balance',
    });
    return;
  }

  // Proceed with the regular transaction flow
  // ...
});

Continuous balance monitoring

Poll the balance at regular intervals to keep the displayed value up to date. Use an appropriate interval based on UX requirements — shorter intervals provide fresher data but increase API usage.

This example should be modified according to the wallet service’s logic:

TypeScript

// Not runnable: implement the updateUI()!

/**
 * Starts the monitoring of a given `walletId`,
 * calling `onBalanceUpdate()` every `intervalMs` milliseconds
 *
 * @returns a function to stop monitoring
 */
export function startBalanceMonitoring(
  walletId: string,
  onBalanceUpdate: (balance: string) => void,
  intervalMs: number = 10_000,
): () => void {
  let isRunning = true;

  const poll = async () => {
    while (isRunning) {
      const wallet = kit.getWallet(walletId);
      if (wallet) {
        const balance = await wallet.getBalance();
        onBalanceUpdate(balance);
      }
      await new Promise((resolve) => setTimeout(resolve, intervalMs));
    }
  };

  // Start monitoring
  poll();

  // Return a cleanup function to stop monitoring
  return () => {
    isRunning = false;
  };
}

// Usage
const stopMonitoring = startBalanceMonitoring(
  walletId,
  // The updateUI() function is exemplary and should be replaced by
  // a wallet service function that refreshes the
  // state of the balance displayed in the interface
  (balance) => updateUI(balance),
);

// Stop monitoring once it is no longer needed
stopMonitoring();

Transfers from dApps

When a connected dApp requests a Toncoin transfer, the wallet service follows this flow:

Emulation and preview

WalletKit tries to automatically emulate every incoming transaction request before presenting it to the user. The emulation result is available in the event.preview.data object, which can be undefined if emulation was skipped:

TypeScript

kit.onTransactionRequest(async (event) => {
  if (!event.preview.data) {
    console.log('Transaction emulation skipped');
  } else if (event.preview.data.result === 'success') {
    // Emulation succeeded — show the predicted money flow
    const { ourTransfers } = event.preview.data.moneyFlow;

    // This is an array of values,
    // where positive amounts mean incoming funds
    // and negative amounts — outgoing funds
    console.log('Predicted transfers:', ourTransfers);
  } else {
    // Emulation failed — warn the user but allow proceeding
    console.warn('Transaction emulation failed:', event.preview);
  }

  // Present the preview to the user and await their decision
  // ...
});

Approve or reject

After showing the preview, handle the user’s decision:

TypeScript

import {
  // An enumeration of various common error codes
  SEND_TRANSACTION_ERROR_CODES,
  // The transfer type
  type TransactionTraceMoneyFlowItem,
} from '@ton/walletkit';

kit.onTransactionRequest(async (event) => {
  try {
    // Show the emulation preview to the wallet service user
    const preview = event.preview;
    const isEmulationSuccessful = preview.data?.result === 'success';

    // Build a confirmation message
    let confirmMessage = 'Confirm this transaction?';
    if (isEmulationSuccessful) {
      const transfers = preview.data.moneyFlow?.ourTransfers || [];
      confirmMessage = `Send ${formatTransfers(transfers)}?`;
    } else {
      confirmMessage = 'Emulation failed or skipped. Proceed anyway?';
    }

    // Handle user's decision
    if (confirm(confirmMessage)) {
      // Approve — this sends the transaction to the blockchain
      // and returns the signed message BoC to the dApp
      await kit.approveTransactionRequest(event);
      console.log('Transaction approved and sent');
    } else {
      // Reject — notify the dApp that the user declined
      await kit.rejectTransactionRequest(event, {
        code: SEND_TRANSACTION_ERROR_CODES.USER_REJECTS_ERROR,
        message: 'User rejected the transaction',
      });
    }
  } catch (error) {
    console.error('Transaction handler error:', error);
    await kit.rejectTransactionRequest(event, {
      code: SEND_TRANSACTION_ERROR_CODES.UNKNOWN_ERROR,
      message: 'Transaction processing failed',
    });
  }
});

function formatTransfers(transfers: Array<TransactionTraceMoneyFlowItem>): string {
  const formatNano = (value: string, decimals: number = 9): string => {
    const bigintValue = BigInt(value);
    const isNegative = bigintValue < 0n;
    const absoluteValue = bigintValue < 0n ? -bigintValue : bigintValue;
    const str = absoluteValue.toString().padStart(decimals + 1, '0');

    const intPart = str.slice(0, -decimals) || '0';
    const fracPart = str.slice(-decimals).replace(/0+$/, '');

    const formatted = fracPart ? `${intPart}.${fracPart}` : intPart;
    return `${isNegative ? '-' : ''}${formatted}`;
  };

  return transfers.map((t) => `${formatNano(t.amount)} ${t.assetType}`).join(', ');
}

Confirm transaction delivery

TON achieves transaction finality after a single masterchain block confirmation, where new blocks are produced approximately every 3 seconds. Once a transaction appears in a masterchain block, it becomes irreversible.

Therefore, to reliably confirm the transaction delivery and status, one needs to check whether a transaction has achieved masterchain finality using the selected API client.

That said, the wallet service should not block the UI while waiting for such confirmation. After all, with continuous wallet balance monitoring and subsequent transaction requests, users will receive the latest information either way. Confirmations are only needed to reliably display a list of past transactions, including the most recent ones.

For detailed transaction tracking and message lookups, the message lookup guide covers finding transactions by external message hash, waiting for confirmations, and applying message normalization.

Transfers in the wallet service

Transactions can be created directly from the wallet service (not from dApps) and fed into the regular approval flow via handleNewTransaction() method of the WalletKit. It creates a new transaction request event, enabling the same UI confirmation-to-transaction flow for both dApp-initiated and wallet-initiated transactions.

This example should be modified according to the wallet service’s logic:

TypeScript

import type { TONTransferRequest, Base64String } from '@ton/walletkit';

async function sendToncoin(
  // Sender's TON `walletId` as a string
  walletId: string,
  // Recipient's TON wallet address as a string
  recipientAddress: string,
  // Amount in nanoToncoins
  nanoAmount: BigInt,
  // Optional comment string
  comment?: string,
  // Optional payload body as a BoC in Base64-encoded string
  payload?: Base64String,
) {
  if (comment && payload) {
    console.error('Cannot attach both a comment or a payload body');
    return;
  }

  const fromWallet = kit.getWallet(walletId);
  if (!fromWallet) {
    console.error('No wallet contract found');
    return;
  }

  const transferParams: TONTransferRequest = {
    recipientAddress: recipientAddress,
    transferAmount: nanoAmount.toString(),
    // Optional comment OR payload, not both
    ...(comment && { comment }),
    ...(payload && { payload }),
  }

  // Build transaction content
  const tx = await fromWallet.createTransferTonTransaction(transferParams);

  // Route into the normal flow,
  // triggering the onTransactionRequest() handler
  await kit.handleNewTransaction(fromWallet, tx);
}

See also

• Handle transaction requests
• Transaction fees
• WalletKit overview
• TON Connect overview