Skip to main content

​
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

Balances are returned as strings representing fractional Toncoin units. For example, '0.1' is a balance of 0.1 Toncoin or 100000000 nanoToncoin. Decimal precision of Toncoin is 9 digits, so the smallest possible balance is '0.000000001' Toncoin or 1 nanoToncoin. 
import { useBalance } from '@ton/appkit-react';

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

  return (
    <p>TON wallet balance in fractional Toncoin: {balance ?? '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: balance,
    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 in fractional Toncoin: {balance ?? '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' or '1' Toncoin.
  const toncoin = '<FRACTIONAL_AMOUNT>';

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

      // Toncoin amount
      amount={toncoin}

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

      // (optional) Add custom button title
      // 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.

​
Next steps

Work with jettons

​
See also