How to work with Jettons using WalletKit on the Web platform

Jettons are fungible tokens on TON, similar to ERC-20 tokens on Ethereum. Unlike Toncoin, which is the native TON currency used in all transfers, each Jetton has a separate master (minter) contract and an individual wallet contract for each holder.

For example, USDT on TON is implemented as a Jetton, and its minter contract address is EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs. By providing this address and the recipient’s TON wallet contract address, WalletKit knows which tokens to send and to whom.

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

Balances

Jetton balances are stored in individual Jetton wallet contracts, one per holder per Jetton kind.

It is possible to obtain the current Jetton balance by providing the address of the Jetton master (minter) contract for a given Jetton, or by querying a TON wallet. The latter can be done either by the getJettons() method of wallet adapters or by calling kit.jettons.getAddressJettons() and passing it the TON wallet address.

Similar to Toncoin balance checks, discrete one-off checks have limited value on their own and continuous monitoring should be used for UI display.

On-demand balance check

Use the getJettonBalance() method to check a specific Jetton balance for a wallet managed by WalletKit. The balance is returned in the smallest Jetton unit, where 1 token equals 10^decimals smallest units.

TypeScript

// Jetton master (minter) contract address
// E.g., USDT on TON has the following address in mainnet:
// EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
const JETTON_MASTER_ADDRESS = '<JETTON_MASTER_ADDRESS>';

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

  // Query Jetton balance in smallest Jetton units
  return await wallet.getJettonBalance(JETTON_MASTER_ADDRESS);
}

The most practical use of one-off balance checks is right before approving a transaction request. At this point, the actual 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';

// Address of the Jetton master (minter) contract
const JETTON_MASTER_ADDRESS = '<JETTON_MASTER_ADDRESS>';

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

  // Check Jetton balance before proceeding
  const jettonBalance = BigInt(await wallet.getJettonBalance(JETTON_MASTER_ADDRESS));

  // Calculate minimum needed from the transaction request:
  // transfers include Toncoin for fees plus Jetton amounts
  const minNeededJettons = calculateJettonAmount(event.request.messages);

  // Reject early if Jetton balance is clearly insufficient
  if (jettonBalance < minNeededJettons) {
    await kit.rejectTransactionRequest(event, {
      code: SEND_TRANSACTION_ERROR_CODES.BAD_REQUEST_ERROR,
      message: 'Insufficient Jetton 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 wallet's Jetton balance,
 * calling `onBalanceUpdate()` every `intervalMs` milliseconds
 *
 * @returns a function to stop monitoring
 */
export function startJettonBalanceMonitoring(
  walletId: string,
  jettonMasterAddress: 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.getJettonBalance(jettonMasterAddress);
        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 = startJettonBalanceMonitoring(
  walletId,
  // Jetton master (minter) contract address
  // E.g., USDT on TON mainnet:
  'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
  // 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 Jetton transfer, the wallet service follows the same flow as Toncoin transfers: the dApp sends a transaction request through the bridge, WalletKit emulates it and presents a preview, the user approves or declines, and the result is returned to the dApp.

TypeScript

kit.onTransactionRequest(async (event) => {
  if (!event.preview.data) {
    console.warn('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);

    // Filter Jetton transfers specifically
    const jettonTransfers = ourTransfers.filter(
      (transfer) => transfer.assetType === 'jetton',
    );
    console.log('Jetton transfers:', jettonTransfers);
  } else {
    // Emulation failed — warn the user but allow proceeding
    console.warn('Transaction emulation failed:', event.preview);
  }

  // By knowing the Jetton master (minter) contract address,
  // one can obtain and preview Jetton's name, symbol and image.
  //
  // Present the enriched preview to the user and await their decision.
  // ...
});

There is an additional consideration for Jetton transfers: they involve multiple internal messages between contracts. As such, Jetton transfers always take longer than regular Toncoin-only transfers.

As with Toncoin transfers, the wallet service should not block the UI while waiting for confirmation. With continuous wallet balance monitoring and subsequent transaction requests, users will receive the latest information either way. Confirmations are only needed to display a list of past transactions reliably.

Transfers in the wallet service

Jetton transactions can be created directly from the wallet service (not from dApps) and fed into the regular approval flow via the 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 JettonsTransferRequest } from '@ton/walletkit';

async function sendJetton(
  // Sender's TON `walletId` as a string
  walletId: string,
  // Jetton master (minter) contract address
  jettonAddress: string,
  // Recipient's TON wallet address as a string
  recipientAddress: string,
  // Amount in the smallest Jetton units (accounting for decimals)
  jettonAmount: bigint,
  // Optional comment string
  comment?: string,
) {
  const fromWallet = kit.getWallet(walletId);
  if (!fromWallet) {
    console.error('No wallet contract found');
    return;
  }

  const transferParams: JettonsTransferRequest = {
    jettonAddress,
    recipientAddress,
    transferAmount: jettonAmount.toString(),
    // Optional comment
    ...(comment && { comment: comment }),
  };

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

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

See also

Jettons:

• Jettons overview
• Jetton transfers
• Token metadata and decimals

General:

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