# How to work with Toncoin using AppKit (https://docs-orhepa2tm-ton-core-docs.vercel.app/llms/ecosystem/appkit/toncoin/content.md)



<Callout>
  [Initialize the AppKit](/llms/ecosystem/appkit/init/content.md) before using examples on this page.
</Callout>

## Balance [#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](#on-demand-balance-check) 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](#continuous-balance-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](/llms/ecosystem/appkit/init/content.md). Obtain and provide the key from the selected client to access higher requests-per-second limits.

### On-demand balance check [#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.

<Callout type="caution">
  Do not store the balance check results anywhere in the application state, as they become outdated quickly. For UI purposes, do [continuous balance monitoring](#continuous-balance-monitoring).
</Callout>

<CodeGroup>
  <CodeBlockTabs defaultValue="React">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React">
        React
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React">
      ```tsx  icon="react"
      import { useBalance } from '@ton/appkit-react';

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

        return (
          <p>TON wallet balance in fractional Toncoin: {balance ?? '0'}</p>
        );
      };
      ```
    </CodeBlockTab>

    <CodeBlockTab value="TypeScript">
      ```ts  icon="globe"
      import { getBalance } from '@ton/appkit';

      const balance = await getBalance(kit);
      if (balance) {
        console.log('TON wallet balance in fractional Toncoin:', balance);
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Continuous balance monitoring [#continuous-balance-monitoring]

Obtain real-time balance updates with a [streaming API provider](/llms/ecosystem/appkit/init/content.md) 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 [#with-streaming]

Modify the following examples according to the application logic:

<CodeGroup>
  <CodeBlockTabs defaultValue="React">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React">
        React
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React">
      ```tsx  icon="react" expandable
      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>
        );
      };
      ```
    </CodeBlockTab>

    <CodeBlockTab value="TypeScript">
      ```ts  icon="globe" expandable
      // 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();
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

#### Only polling [#only-polling]

Modify the following examples according to the application logic:

<CodeGroup>
  <CodeBlockTabs defaultValue="React">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React">
        React
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React">
      ```tsx  icon="react" expandable
      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>
        );
      };
      ```
    </CodeBlockTab>

    <CodeBlockTab value="TypeScript">
      ```ts  icon="globe" expandable
      // 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();
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Transfers [#transfers]

Modify the following examples according to the application logic:

<CodeGroup>
  <CodeBlockTabs defaultValue="React (component)">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="React (component)">
        React (component)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="React (hook)">
        React (hook)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="TypeScript">
        TypeScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="React (component)">
      ```tsx  icon="react"
      // 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}
          />
        );
      };
      ```
    </CodeBlockTab>

    <CodeBlockTab value="React (hook)">
      ```tsx  icon="react"
      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>
        );
      };
      ```
    </CodeBlockTab>

    <CodeBlockTab value="TypeScript">
      ```ts  icon="globe"
      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.
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Confirm transaction delivery [#confirm-transaction-delivery]

TON achieves transaction [finality](https://en.wikipedia.org/wiki/Blockchain#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](#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](/llms/ecosystem/ton-connect/message-lookup/content.md) covers finding transactions by external message hash, waiting for confirmations, and applying message normalization.

## Next steps [#next-steps]

<Columns cols="2">
  <Card title="Work with jettons" icon="coins" horizontal="true" href="/ecosystem/appkit/jettons" />
</Columns>

## See also [#see-also]

* [Transaction fees](/llms/foundations/fees/content.md)
* [AppKit overview](/llms/ecosystem/appkit/overview/content.md)
* [TON Connect overview](/llms/ecosystem/ton-connect/content.md)