Ton Wallet SDK Integration Guide for DApps

·

Integrating a secure and efficient wallet connection into your decentralized application (DApp) is crucial for delivering a seamless user experience on the TON (The Open Network) blockchain. This guide provides a comprehensive walkthrough of using the OKX Ton Connect SDK to enable wallet connectivity, transaction handling, and real-time state monitoring — all while minimizing development overhead and supporting cross-platform functionality.

Whether you're building a Web3-powered mini-app, integrating with Telegram environments, or launching a full-scale DApp on TON, this SDK streamlines integration with minimal setup.

👉 Discover how easy it is to integrate wallet connectivity into your DApp today.

Core Keywords

These keywords reflect the central themes of this guide and are naturally integrated throughout to align with search intent and enhance SEO performance.

SDK Installation

You can install the OKX Ton Connect SDK using either CDN or npm, depending on your project's architecture and deployment needs.

Using CDN

To include the SDK via CDN, add the following script tag to your HTML file:

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

You may replace latest with a specific version number such as 1.3.7 for better stability and version control.

Once loaded, the SDK becomes available as a global object:

const connector = new OKXTonConnectSDK.OKXTonConnect();

This method is ideal for frontend-only projects or rapid prototyping where build tools aren’t in use.

Using npm

For modern JavaScript applications using package managers, run:

npm install @okxweb3/okx-ton-connect-sdk

Then import it in your code:

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

Using npm allows for better tree-shaking, TypeScript support, and integration with bundlers like Webpack or Vite.

👉 Get started with seamless wallet integration in under 5 minutes.

Initialization

Before connecting to a wallet, initialize the SDK with your app’s metadata:

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

Parameters

This step ensures users recognize your application when authorizing wallet access, enhancing trust and conversion rates.

Connect to Wallet

Establish a secure connection to retrieve the user’s wallet address and enable transaction signing.

await okxTonConnect.connect({
  tonProof: 'custom-proof-data',           // Optional: used for authentication
  redirect: 'tg://resolve...',             // Required in Telegram mini-apps
  openUniversalLink: true                  // Recommended on mobile
});

Parameters

Recommendations

The method returns a universal link that can be rendered as a QR code on desktop for easy mobile pairing.

Restore Connection

Preserve user sessions by restoring previous connections without re-authentication:

await okxTonConnect.restoreConnection();

This asynchronous method checks for an existing session and reconnects automatically if valid. Ideal for improving UX by reducing repeated login prompts.

No parameters required. Use this during app initialization to maintain continuity.

Disconnect Wallet

Terminate the current session securely:

await okxTonConnect.disconnect();

This removes all local session data and disconnects the wallet. Always call this before attempting to switch accounts or log out.

Check Connection Status

Verify whether a wallet is currently connected:

const isConnected = okxTonConnect.connected;

Returns true if connected, false otherwise. Useful for conditional rendering in UI components.

Send Transaction

Initiate and sign transactions through the connected wallet:

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

Parameters

Returns a Promise resolving to { boc: string }, the signed transaction in Base64-encoded BoC format.

Monitor Wallet State Changes

Listen for real-time updates on connection and transaction status:

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

// Call later to clean up listener
unsubscribe();

Wallet Info Object Includes:

Use this to update UI states dynamically and respond to authentication events.

Listen to Events

Subscribe to specific lifecycle events for granular control:

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

window.addEventListener('OKX_TON_TRANSACTION_SIGNED', () => {
  alert('Transaction confirmed!');
});

Supported Events

These events empower developers to create responsive interfaces that react instantly to user actions.

Get Account & Wallet Information

Retrieve current account details:

const account = okxTonConnect.getAccount(); // Returns account object
const wallet = okxTonConnect.getWallet();   // Returns wallet info

Useful for displaying user balances, profile info, or transaction history within your DApp.

Error Handling

Common error codes you might encounter:

Handle these gracefully in your UI to improve user retention and trust.

Frequently Asked Questions (FAQ)

Q: Can I use this SDK outside of Telegram mini-apps?
A: Yes. While optimized for Telegram environments, the SDK works across web browsers and mobile apps supporting universal links.

Q: Is user data stored by OKX during connection?
A: No. The connection is non-custodial and privacy-preserving. Only public addresses and signatures are shared.

Q: How do I handle failed transaction signings?
A: Listen for the OKX_TON_TRANSACTION_SIGNING_FAILED event or catch errors in the promise chain.

Q: Does this support multiple wallets?
A: You must disconnect the current wallet before connecting a new one. Multi-wallet management must be handled at the app level.

Q: Can I customize the connection UI?
A: The connection flow is managed by the OKX App, but you can customize prompts via metadata (name, icon).

Q: Is there a testnet version available?
A: Yes. The SDK supports both mainnet and testnet configurations through chain detection.

👉 Start integrating with confidence using reliable Web3 infrastructure.