SDK Integration for TON: Connect Apps or Mini Wallets to Web3

Integrating decentralized applications (DApps) with blockchain wallets is a critical step in delivering seamless Web3 experiences. This guide provides a comprehensive walkthrough of how to use the OKX Ton Connect SDK to integrate your application or mini wallet with the TON (The Open Network) ecosystem. Whether you're building on mobile, desktop, or within Telegram, this documentation ensures smooth connectivity, transaction handling, and real-time state management.

Designed for developers familiar with Ton Connect, this SDK reduces development overhead while supporting multi-network requests—making it ideal for scalable DApp architectures.

Core Keywords

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

Installing the SDK

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

Using CDN

To integrate 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 (e.g., 1.6.1) for better control over updates.

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

const connector = new OKXTonConnectSDK.OKXTonConnect();

This method is ideal for quick prototyping or frontend-only projects where package managers aren't used.

Using npm

For modern JavaScript environments, install the SDK using npm:

npm install @okxweb3/ton-connect-sdk

Then import it into your project:

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

👉 Get started with secure, high-performance Web3 integration today.

Initializing the SDK

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

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

Parameters

metaData (Object)
- name (string): The display name of your app.
- icon (string): Public URL of your app’s icon. Must be in PNG or ICO format (SVG not supported). A 180×180 pixel PNG is optimal for clarity across devices.

This initialization sets up the foundation for all subsequent interactions, including connection, transaction signing, and event listening.

Connecting a Wallet

To authenticate users and access their wallet address, use the connect() method:

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

Request Parameters

tonProof (string, optional): Message for proof-of-ownership signature.
redirect (string, optional): Deep link to return to your app after action completion (especially useful in Telegram).
openUniversalLink (boolean, optional): If true, attempts to open the OKX App directly; falls back to download page if not installed.

Return Value

Returns a Promise resolving to a universal link. On desktop, generate a QR code from this link for mobile scanning.

Best Practices

Set openUniversalLink: true on mobile browsers and Telegram.
On desktop, set it to false and render a QR code for easy mobile pairing.

👉 Unlock full Web3 functionality with seamless wallet onboarding.

Restoring a Previous Connection

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

okxTonConnect.restoreConnection();

This method checks for active sessions and reconnects silently, improving user experience during page refreshes or app relaunches.

No parameters or return values—just call it during initialization.

Disconnecting the Wallet

To terminate the current session:

okxTonConnect.disconnect();

Use this when users log out or switch accounts. It clears local session data and notifies the connected wallet.

Always disconnect before attempting a new connection to avoid conflicts.

Checking Connection Status

Verify whether a wallet is currently connected:

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

Alternatively, use getAccount() or getWallet() methods to retrieve active data and infer connection status.

Sending Transactions

Send transactions securely through the user’s wallet:

const result = await okxTonConnect.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 600,
  messages: [
    {
      address: 'UQD...',
      amount: '100000000',
      payload: 'base64-encoded-boc'
    }
  ]
});

Transaction Object

validUntil: Unix timestamp after which the transaction expires.
from: Sender address (optional; defaults to current wallet).
messages: Array of 1–4 transfer objects containing:
- address: Recipient TON address.
- amount: Amount in nanotons.
- payload: Optional Base64-encoded BOc cell.
options.onRequestSent: Callback triggered once request is sent to wallet.

Returns

A Promise resolving to { boc: "signed-transaction-in-base64" }.

Monitoring Wallet State Changes

Listen for real-time updates in connection status:

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

Callback Data (`walletInfo`)

Includes:

Wallet name, platform (iOS/Android), version.
Account details: address (raw format), public key, chain ID (-239 for TON).
Supported features (e.g., sendTransaction).

Call unsubscribe() when no longer needed to prevent memory leaks.

Listening to Events

Subscribe to specific lifecycle events:

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

Available Events

OKX_TON_CONNECTION_STARTED
OKX_TON_CONNECTION_COMPLETED
OKX_TON_CONNECTION_ERROR
OKX_TON_DISCONNECTION
OKX_TON_TRANSACTION_SIGNED
OKX_TON_TRANSACTION_SIGNING_FAILED

These help track user behavior and trigger UI updates accordingly.

Retrieving Account and Wallet Information

Fetch current account:

const account = okxTonConnect.getAccount();

Get wallet details:

const wallet = okxTonConnect.getWallet();

Both return null if not connected. Use them post-connection to personalize user interfaces or validate permissions.

Error Handling

Common errors include:

Code	Description
UNKNOWN_ERROR	Unexpected internal failure
ALREADY_CONNECTED_ERROR	Attempted duplicate connection
NOT_CONNECTED_ERROR	Operation requires active connection
USER_REJECTS_ERROR	User denied request
METHOD_NOT_SUPPORTED	Feature unsupported by wallet
CONNECTION_ERROR	Network or protocol issue

Handle these gracefully in your UI to maintain trust and usability.

Frequently Asked Questions

Q: Can I use this SDK outside of Telegram?
A: Yes. While optimized for Telegram mini-apps, it works across web, mobile browsers, and native apps using deep links or QR codes.

Q: Is user privacy protected during connection?
A: Absolutely. The SDK uses non-custodial authentication—your app never accesses private keys. All signatures occur within the user’s secure wallet environment.

Q: What networks does this support?
A: Primarily The Open Network (TON), with multi-chain support available via OKX Connect’s extended ProviderSDK.

Q: How do I debug connection issues?
A: Enable logging in development mode and listen to error events like OKX_TON_CONNECTION_ERROR. Check metadata formatting and network reachability.

Q: Can I customize the connection flow?
A: Limited customization is allowed via metadata (name/icon). The actual UI is managed by the OKX wallet for security consistency.

Q: Are there rate limits or usage fees?
A: No. The SDK is free to use with no imposed rate limits, making it suitable for high-traffic DApps.

👉 Enhance your DApp with powerful tools and real-time blockchain access.