Skip to main content
Initialize the AppKit before using examples on this page.

​
Balance

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 making outgoing transfers.
  • 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 AppKit initialization. Obtain and provide the key from the selected client to access higher requests-per-second limits.

​
On-demand balance check

Toncoin balances are returned in nanoToncoin units, with 1 Toncoin equal to 109 nanoToncoin.
Do not store the balance check results anywhere in the wallet service’s state, as they become outdated quickly. For UI purposes, do continuous balance monitoring.
import { useBalance } from '@ton/appkit-react';

export const BalanceCard = () => {
  const { data: nanoToncoin } = useBalance();

  return (
    <p>TON wallet balance: {nanoToncoin ?? '0'}</p>
  );
};

​
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. Modify the following examples according to the application logic: 
import { useBalance } from '@ton/appkit-react';

export const BalanceCard = () => {
  const {
    data: nanoToncoin,
    isLoading: isBalanceLoading,
    isError: isBalanceError,
    refetch: onRefresh,
  } = useBalance();

  if (isBalanceError) {
    return (
      <div>
        <p>Error retrieving balance</p>
        <button onClick={() => onRefresh()}>Try again</button>
      </div>
    );
  }

  return (
    <div>
      {isBalanceLoading ? (
        <p>Loading the balance...</p>
      ) : (
        <p>TON wallet balance: {nanoToncoin ?? '0'}</p>
      )}
    </div>
  );
};

​
Transfers

Modify the following examples according to the application logic: 
// Pre-built UI component for sending Toncoin transactions by clicking a button.
// It handles success and error states while being customizable.
import { SendTonButton } from '@ton/appkit-react';

export const SendToncoin = () => {
  // For example: 'UQ...'
  const recipientAddress = '<TON_WALLET_ADDRESS>';
  // For example, 0.1 Toncoin becomes 100000000 nanoToncoin
  const nanoToncoin = '<NANOTONCOIN_AMOUNT>';

  return (
    <SendTonButton
      // Where to send Toncoin to
      recipientAddress={recipientAddress}

      // NanoToncoin amount
      amount={nanoToncoin}

      // (optional) Comment string
      comment="Hello from AppKit!"

      // (optional) Add custom button text
      // Defaults to Send X TON, where X is Toncoin amount
      text="Send TON"

      // (optional) Handle successes
      onSuccess={(result) => console.log('Transaction sent:', result)}

      // (optional) Handle errors
      onError={(error) => console.error('Transaction failed:', error)}

      // (optional) Add custom CSS classes
      className=''

      // (optional) When set to `true`, the button is disabled
      disabled={false}
    />
  );
};

​
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. Applications should not block the UI while waiting for such confirmation. With continuous 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.

​
See also