How to work with Toncoin using AppKit

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

import { getBalance } from '@ton/appkit';

const balance = await getBalance(kit);
if (balance) {
  console.log('TON wallet balance in fractional Toncoin:', balance);
}

Continuous balance monitoring

Obtain real-time balance updates with a streaming API provider and fallback to polling at regular intervals to keep the displayed value up to date. For polling, use an appropriate interval based on UX requirements — shorter intervals provide fresher data but increase API usage.

With streaming

Modify the following examples according to the application logic:

import {
  useBalance,
  useWatchBalance,
} from '@ton/appkit-react';

export const BalanceCard = () => {
  // Polling
  const {
    data: balance,
    isLoading,
    error,
    refetch,
  } = useBalance();

  // Hook enabling real-time balance updates for the currently selected wallet.
  useWatchBalance();

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

  return (
    <div>
      {isLoading ? (
        <p>Loading the balance...</p>
      ) : (
        <p>TON wallet balance in fractional Toncoin: {balance ?? '0'}</p>
      )}
    </div>
  );
};

// Not runnable: implement the updateUI()
import {
  type AppKit,
  Network,
  hasStreamingProvider,
  watchBalance,
} from '@ton/appkit';

export function startBalanceMonitoring(
  kit: AppKit,
  onBalanceUpdate: (balance: string) => void,
  network: Network = Network.mainnet(),
): () => void {
  if (!hasStreamingProvider(kit, network)) {
    throw new Error([
      `No streaming provider registered for network ${network.chainId}. `,
      'Register one via kit.streamingManager.registerProvider(...) first.',
    ].join());
  }

  return watchBalance(kit, {
    network,
    onChange: (update) => {
      if (update.status === 'finalized') {
        onBalanceUpdate(update.balance);
      }
    },
  });
}

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

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

Only polling

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

// Not runnable: implement the updateUI()
import { type AppKit, getBalance } from '@ton/appkit';

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

  const poll = async () => {
    while (isRunning) {
      const balance = await getBalance(kit);
      if (balance) {
        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(
  kit,
  // The updateUI() function is exemplary and should be replaced by
  // an app 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

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}
    />
  );
};

import { useTransferTon } from '@ton/appkit-react';

export const SendToncoin = () => {
  const { mutate: transfer, isPending, error, data } = useTransferTon();

  const handleTransfer = () => {
    transfer({
      // Where to send Toncoin to.
      // For example: 'UQ...'
      recipientAddress: '<TON_WALLET_ADDRESS>',

      // Fractional Toncoin amount string.
      // For example, '0.1' or '10' Toncoin.
      amount: '<FRACTIONAL_AMOUNT>',

      // (optional) Comment string. Defaults to none if not provided.
      comment: 'Hello from AppKit!',

      // (optional) Payload data encoded as a Base64 string.
      //            Overrides the `comment`, if provided.
      payload: '<PAYLOAD>',

      // (optional) Initial state (code and data) for deploying a new contract,
      //            encoded as a Base64 string
      stateInit: '<STATE_INIT>',
    });
  };

  return (
    <div>
      <button onClick={handleTransfer} disabled={isPending}>
        {isPending ? 'Transferring...' : 'Transfer TON'}
      </button>
      {error && <div>Error: {error.message}</div>}
      {data && (
        <div>
          <p>Transfer successful: {data.boc}</p>
        </div>
      )}
    </div>
  );
};

import {
  type AppKit,
  type Base64String,
  // Single-call transfer
  transferTon,
  // Two-step transfer: create a transaction object separately from sending it
  createTransferTonTransaction,
  sendTransaction,
} from '@ton/appkit';

async function sendToncoin(
  /** Initialized AppKit instance */
  kit: AppKit,
  /** Recipient's TON wallet address as a string */
  recipientAddress: string,
  /** Amount in fractional Toncoin */
  amount: string,
  /** Optional comment string */
  comment?: string,
  /** Optional payload body as a BoC in Base64-encoded string */
  payload?: Base64String,
  /**
   * Optional initial state (code and data) for deploying a new contract,
   * stored as a BoC in Base64-encoded string
   */
  stateInit?: Base64String,
) {
  // Sign and send via TON Connect
  const result = await transferTon(kit, {
    recipientAddress,
    amount,
    // Optional comment OR payload, not both
    ...(comment && { comment }),
    ...(payload && { payload }),
    ...(stateInit && { stateInit }),
  });
  console.log('Transaction sent:', result.boc);

  // Alternatively, build the transaction first with createTransferTonTransaction,
  // then pass the resulting object to the sendTransaction function.
}

Confirm transaction delivery

TON achieves transaction finality after a single masterchain block confirmation. 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, watchTransactions() streaming, 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.

Ecosystem

Payment processing

Standard contracts

Contract development

Tolk language

TVM: TON Virtual Machine

Blockchain foundations

Legacy languages

Contributing

How to work with Toncoin using AppKit

Balance

On-demand balance check

Continuous balance monitoring

With streaming

Only polling

Transfers

Confirm transaction delivery

Next steps

Work with jettons

See also

​Balance

​On-demand balance check

​Continuous balance monitoring

​With streaming

​Only polling

​Transfers

​Confirm transaction delivery

​Next steps

Work with jettons

​See also

Balance

On-demand balance check

Continuous balance monitoring

With streaming

Only polling

Transfers

Confirm transaction delivery

Next steps

See also