Integrate TON Web3 Wallets with OKX SDK: A Developer’s Guide

Connecting decentralized applications (dApps) to Web3 wallets on The Open Network (TON) has never been easier. Whether you're building a mini-app, a full-fledged dApp, or integrating DEX functionalities, the OKX TON Connect SDK streamlines wallet connectivity, transaction signing, and session management—offering robust support across platforms and networks.

This guide walks you through every step of using the OKX TON SDK, from installation to advanced event handling, ensuring seamless integration while minimizing development overhead.

Why Use the OKX TON Connect SDK?

If you've previously used Ton Connect, you can continue leveraging familiar patterns with enhanced functionality. For developers who have worked with OKX Connect, switching to the Provider SDK reduces redundancy and unlocks cross-network request capabilities—ideal for multi-chain dApp environments.

The OKX TON SDK supports:

• QR-based and deep-link connections
• Session restoration
• Real-time wallet state monitoring
• Secure transaction signing
• Cross-platform compatibility (iOS, Android, web)

👉 Get started with secure, scalable Web3 integrations using OKX’s powerful tools.

Install the SDK

You can integrate the OKX TON Connect SDK via CDN or npm—choose the method that best fits your development workflow.

Using CDN

Add the following script tag to your HTML file. Replace latest with a specific version (e.g., 1.6.1) for production stability:

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

After loading, the SDK is available as a global object:

const connector = new OKXTonConnectSDK.OKXTonConnect();

Using npm

Run the install command:

npm install @okxweb3/ton-connect-sdk

Then import it into your project:

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

Initialize the SDK

Before connecting a wallet, initialize the SDK with metadata about your application.

const okxTonConnect = new OKXTonConnect({
  metaData: {
    name: 'My TON dApp',
    icon: 'https://mydapp.com/icon.png' // Must be PNG or ICO (180x180px recommended)
  }
});

Parameters

• metaData — Object containing:

  • name: Your app’s display name (not used as an identifier)
  • icon: Public URL to your app’s icon in PNG or ICO format (SVG not supported)

This initialization prepares the connector for wallet interactions such as connection, transaction signing, and event listening.

Connect a Wallet

To authenticate users and obtain their wallet address, use the connect() method.

const universalLink = await okxTonConnect.connect({
  tonProof: 'auth_payload_123',
  redirect: 'tg://resolve?domain=mybot',
  openUniversalLink: true
});

Request Options

• tonProof (optional): A string for proof-of-possession authentication.
• redirect (optional): Deep link to return users after action completion (useful in Telegram mini-apps).
• openUniversalLink (optional): If true, attempts to open the OKX app directly; if unavailable, redirects to download page.

Return Value

Returns a Promise<string> containing a universal link used to generate a QR code on desktop browsers.

Best Practices

• On mobile devices or within Telegram, set openUniversalLink: true.
• On desktop, set it to false and render the returned universal link as a scannable QR code.

👉 Easily connect users across platforms—see how OKX simplifies Web3 onboarding.

Restore Previous Connection

Automatically restore an active session when users revisit your dApp or refresh the page.

okxTonConnect.restoreConnection();

No parameters required. This method checks for existing sessions and re-establishes the wallet link silently.

Use this during app initialization to maintain continuity in user experience.

Disconnect Wallet

Terminate the current session and clear stored data.

okxTonConnect.disconnect();

Always call this before attempting to switch wallets or log out users.

Check Connection Status

Verify whether a wallet is currently connected:

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

Alternatively, use state listeners for real-time updates.

Send Transactions

Request users to sign and send transactions securely through their OKX wallet.

const result = await okxTonConnect.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 600,
  from: 'UQB...', // optional
  messages: [
    {
      address: 'UQC...',
      amount: '100000000', // in nanotons
      payload: 'base64cell...', // optional
      stateInit: 'base64cell...' // optional
    }
  ]
}, {
  onRequestSent: () => console.log('Signature request sent')
});

Response

Returns a Promise<{ boc: string }> where boc is the signed message in Base64 format—ready for blockchain submission.

Ensure validUntil is set appropriately to prevent stale transactions.

Listen for Wallet State Changes

Monitor connection lifecycle events like connect, disconnect, or errors.

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

Call unsubscribe() when cleanup is needed (e.g., component unmount).

Wallet Info Structure

Includes:

• Wallet name, platform (android/ios), version
• Account details (address, public key)
• Chain ID (-239 for TON)
• Signature proof data (if using tonProof)

Listen for Events

Subscribe to granular events for better UX control:

Example:

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

These events allow you to update UI states dynamically—enhancing responsiveness and trust.

Get Account & Wallet Information

Retrieve current account details:

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

Get connected wallet metadata:

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

Useful for personalizing interfaces or validating network compatibility.

Error Handling

The SDK throws standardized errors during operations. Handle them gracefully:

Wrap calls in try-catch blocks and provide clear feedback.

Frequently Asked Questions

How do I support both mobile and desktop connections?

Use conditional logic: enable openUniversalLink: true on mobile for direct app opening; on desktop, generate QR codes from the returned universal link.

Can I connect multiple wallets?

No—only one wallet can be connected at a time. Always call disconnect() before initiating a new connection.

Is tonProof required?

No, but it enhances security by proving wallet ownership during login. Recommended for authentication flows.

What networks does this SDK support?

Primarily designed for The Open Network (TON), but OKX’s broader Provider SDK supports multi-chain environments including Ethereum, Tron, and more.

How long does a session last?

Sessions persist until manually disconnected or cleared by browser storage policies. Use restoreConnection() to re-establish without re-scanning.

Can I customize the connection UI?

While connection prompts appear in the OKX app, you control all pre-connection UI elements—customize buttons, modals, and onboarding flows freely.

👉 Unlock advanced Web3 features with OKX’s developer-first infrastructure.

Core Keywords

• TON Web3 integration
• OKX Connect SDK
• Connect TON wallet
• DApp wallet connection
• Send TON transactions
• Web3 wallet API
• Blockchain SDK
• Decentralized app development

By combining ease of integration with powerful real-time capabilities, the OKX TON Connect SDK empowers developers to build responsive, secure, and user-friendly dApps on The Open Network.