Connecting to TON wallets is a crucial step in building hybrid dApps with TAC. This guide explains how to integrate TON wallets into your application using the TAC SDK.

TAC SDK supports two methods for sending transactions: using TON Connect for web applications or using a raw wallet via mnemonic for backend services and testing.

TON Connect is the recommended way to connect to TON wallets in web applications. It provides a consistent user experience and supports popular wallets like Tonkeeper and Tonhub.

​
Setting Up TON Connect

First, install the TON Connect UI package:

npm install @tonconnect/ui @tonconnect/ui-react

Then, create a TON Connect instance in your application:

import { TonConnectUI } from '@tonconnect/ui';

// Create TON Connect instance
const tonConnectUI = new TonConnectUI({
  manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
  // Optional: styling parameters
  buttonRootId: 'ton-connect-button'
});

You need to create a TON Connect manifest file and host it at a publicly accessible URL. Learn more about creating a manifest in the TON Connect documentation.

​
React Integration

If you’re using React or Next.js, you can use the TON Connect React components:

import { TonConnectUIProvider, TonConnectButton, useTonWallet } from '@tonconnect/ui-react';

function App() {
  return (
    <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
      <YourApp />
    </TonConnectUIProvider>
  );
}

function YourApp() {
  const wallet = useTonWallet();
  
  return (
    <div>
      <TonConnectButton />
      {wallet && <p>Connected: {wallet.account.address}</p>}
    </div>
  );
}

​
Creating a Sender with TON Connect

Once you have TON Connect set up, you can create a TonConnectSender for use with the TAC SDK:

import { SenderFactory } from '@tonappchain/sdk';

async function createTonConnectSender() {
  // Assuming tonConnectUI is your TonConnectUI instance
  const sender = await SenderFactory.getSender({
    tonConnect: tonConnectUI
  });
  
  return sender;
}

​
Raw Wallet Integration (For Backend/Testing)

For backend services, testing, or situations where TON Connect isn’t suitable, you can use a raw wallet with a mnemonic phrase.

Never expose your mnemonic phrase in frontend code. The raw wallet approach should only be used in secure environments like backend services or local testing.

​
Creating a Raw Sender

import { SenderFactory, Network } from '@tonappchain/sdk';

async function createRawSender() {
  const walletVersion = 'v4'; // TON wallet version
  const mnemonic = process.env.TON_MNEMONIC || ''; // 24 words mnemonic from environment variable
  
  const sender = await SenderFactory.getSender({
    version: walletVersion,
    mnemonic,
    network: Network.TESTNET
  });
  
  return sender;
}

​
Supported Wallet Versions

The TAC SDK supports these TON wallet versions:

  • V2R1
  • V2R2
  • V3R1
  • V3R2
  • V4 (recommended)
  • V5R1
  • HIGHLOAD_V3

​
Complete Wallet Integration Example

Here’s a complete example showing both methods:

import { TacSdk, Network, SenderFactory } from '@tonappchain/sdk';
import { TonConnectUI } from '@tonconnect/ui';

async function initializeWalletIntegration() {
  // Initialize TAC SDK
  const tacSdk = await TacSdk.create({
    network: Network.TESTNET
  });
  
  // Option 1: TON Connect for web applications
  const tonConnectUI = new TonConnectUI({
    manifestUrl: 'https://your-app.com/tonconnect-manifest.json'
  });
  
  // Create sender using TON Connect
  const webSender = await SenderFactory.getSender({
    tonConnect: tonConnectUI
  });
  
  // Option 2: Raw sender for backend/testing
  const backendSender = await SenderFactory.getSender({
    version: 'v4',
    mnemonic: process.env.TON_MNEMONIC || '',
    network: Network.TESTNET
  });
  
  return { tacSdk, webSender, backendSender };
}

​
Error Handling

When creating senders, you might encounter these errors:

  • WalletError: Invalid wallet version provided

Handle these errors properly:

try {
  const sender = await SenderFactory.getSender({
    version: 'v4',
    mnemonic: process.env.TON_MNEMONIC || '',
    network: Network.TESTNET
  });
} catch (error) {
  if (error.name === 'WalletError') {
    console.error('Invalid wallet configuration:', error.message);
  } else {
    console.error('Sender creation error:', error);
  }
}