Ton Wallet Integration with SDK: Connect, Send Transactions & Monitor State

·

Integrating a secure and seamless wallet connection into your decentralized application (DApp) on the TON blockchain is essential for delivering a smooth user experience. Whether you're building a DEX, NFT marketplace, or Web3-powered service, leveraging the right SDK for Ton wallet integration ensures fast, reliable, and scalable interactions between your app and users’ wallets.

This guide walks you through the complete process of integrating the OKX Ton Connect SDK — from installation and initialization to sending transactions and monitoring real-time wallet events — all while following best practices in Web3 development.

Why Use the OKX Ton Connect SDK?

The OKX Ton Connect SDK streamlines the integration of TON-based wallets into your DApp. If you’ve previously worked with Ton Connect or OKX Connect, this SDK allows for backward compatibility and reduces development overhead. It supports simultaneous multi-network requests and provides robust tools for handling connections, transaction signing, and state monitoring.

By using this SDK, developers gain access to:

👉 Discover how easy it is to integrate Ton wallet connectivity today.

SDK Installation

You can install the OKX Ton Connect SDK via CDN or npm, depending on your project setup.

Install via CDN

Add the following script tag to your HTML file:

<script src="https://cdn.okx.com/sdk/ton-connect/latest.js"></script>

You may replace latest with a specific version (e.g., 1.3.7) for better control over updates.

Once loaded, the SDK is available globally as OKXTonConnectSDK. Initialize it like so:

const connector = new OKXTonConnectSDK.OKXTonConnect();

Install via npm

Run the following command in your terminal:

npm install @okxconnect/ton-connect-sdk

Then import it into your project:

import { OKXTonConnect } from '@okxconnect/ton-connect-sdk';

Initialize the SDK

Before connecting to a wallet, create an instance of the SDK with metadata about your application.

const okxTonConnect = new OKXTonConnect({
  metaData: {
    name: 'My DApp', // Your app's display name
    icon: 'https://mydapp.com/icon.png' // 180x180px PNG recommended
  }
});

Parameters

This metadata appears during the wallet connection prompt, helping users identify your app securely.

Connect to a Wallet

To initiate a wallet connection and retrieve user account details:

okxTonConnect.connect({
  tonProof: 'payload-for-proof',
  redirect: 'tg://resolve...',
  openUniversalLink: true
});

Connection Options

Return Value

A promise resolving to a universal link string. On desktop, generate a QR code from this link so users can scan with the OKX app.

Best Practices

👉 See live demos of seamless Ton wallet connections in action.

Restore Previous Connection

If a user has connected before, restore their session without re-prompting:

await okxTonConnect.restoreConnection();

This method checks for existing sessions and reconnects silently if valid — improving UX by reducing repeated interactions.

Use this when your DApp loads to maintain continuity.

Disconnect Wallet

To disconnect the current wallet and clear the session:

okxTonConnect.disconnect();

Always disconnect before attempting to switch wallets.

Check Connection Status

Verify whether a wallet is currently connected:

if (okxTonConnect.connected) {
  console.log('Wallet is connected');
}

Useful for conditionally rendering UI elements like "Connect Wallet" buttons or balance displays.

Send a Transaction

Send blockchain transactions securely through the wallet:

const result = await okxTonConnect.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 600, // 10 minutes from now
  from: 'UQB...', // optional sender address
  messages: [
    {
      address: 'UQC...', // recipient
      amount: '500000000', // amount in nanotons
      payload: 'base64-boc-payload' // optional
    }
  ]
}, {
  onRequestSent: () => console.log('Signature request sent')
});

Parameters

Returns

A Promise resolving to { boc: string }, where boc is the signed transaction body in Base64 format.

Monitor Wallet State Changes

Listen for real-time changes in wallet status:

const unsubscribe = okxTonConnect.onStatusChange(
  (walletInfo) => {
    console.log('Wallet connected:', walletInfo);
  },
  (error) => {
    console.error('Connection error:', error);
  }
);

Wallet Info Object Includes:

Call unsubscribe() when no longer monitoring to free up resources.

Listen to Specific Events

Subscribe to granular events during the connection and transaction flow:

Example:

window.addEventListener('OKX_TON_CONNECTION_COMPLETED', () => {
  console.log('User successfully connected wallet');
});

These events help track user behavior and debug issues in real time.

Retrieve Account & Wallet Information

Get details about the connected account:

const account = okxTonConnect.getAccount();
console.log(account.address); // e.g., "UQB..."

And wallet info:

const wallet = okxTonConnect.getWallet();
console.log(wallet.appName); // e.g., "OKX Wallet"

Useful for personalizing user interfaces or logging analytics.

Error Handling

Common error codes include:

Handle these gracefully in both UI and logs.

Frequently Asked Questions (FAQ)

What is Ton Connect SDK used for?

The Ton Connect SDK enables DApps to securely connect with TON-compatible wallets like OKX Wallet. It handles authentication, transaction signing, and real-time state updates.

Can I use this SDK in Telegram mini apps?

Yes. The SDK fully supports Telegram environments. Use the redirect parameter with Telegram deep links (tg://) to return users after signing.

Is it safe to use openUniversalLink on desktop?

No. Set openUniversalLink: false on desktop. Instead, generate a QR code from the returned universal link for mobile scanning.

How do I handle transaction timeouts?

Always set a reasonable validUntil timestamp (e.g., 5–10 minutes). Transactions submitted after this time will be rejected by the network.

Does the SDK support multiple wallets?

Not simultaneously. You must disconnect the current wallet before connecting a new one.

Can I customize the connection UI?

While the connection flow is handled by the OKX app, you can customize your DApp’s trigger buttons, loading states, and post-connect UI using event listeners.

👉 Start integrating with one of the most reliable Ton wallet SDKs available.

Core Keywords

With robust features, clear documentation, and strong community support, the OKX Ton Connect SDK is a powerful choice for any developer building on the TON blockchain.