SDK Integration Guide: Connect to TON Apps & Mini Wallets with API Documentation

If you've previously integrated Ton Connect, this guide will streamline your development process while maintaining compatibility. Similarly, developers familiar with OKX Connect can transition seamlessly to ProviderSDK for multi-network support.

SDK Installation Methods

CDN Integration

Add this script to your HTML header (replace "latest" with specific versions like "1.3.7" when needed):

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

After loading, reference the global object:

const connector = new OKXTonConnectSDK.OKXTonConnect();

NPM Installation

For module-based projects:

npm install @okx/ton-connect-sdk

SDK Initialization

Create your connection instance with metadata:

const okxTonConnect = new OKXTonConnect({
  metaData: {
    name: "YourAppName",
    icon: "https://yourdomain.com/app-icon.png" // 180x180px PNG recommended
  }
});

Wallet Connection Process

Establish wallet connectivity to retrieve addresses and signing parameters:

async function connectWallet() {
  const connection = await okxTonConnect.connect({
    tonProof: "<signature_data>",
    openUniversalLink: true // Recommended for mobile environments
  });
  
  // PC browsers should use connection.universalLink for QR generation
}

Best Practices

• Enable openUniversalLink for mobile/TG environments
• Disable for PC browsers and use returned universalLink for QR codes
• Implement QR code dismissal after successful connection

Connection Management

Restoring Sessions

okxTonConnect.restoreConnection().then(() => {
  console.log("Session restored");
});

Disconnecting Wallets

okxTonConnect.disconnect();

Connection Status Check

const isConnected = okxTonConnect.connected;

Transaction Handling

Sending Transactions

const transactionResult = await okxTonConnect.sendTransaction(
  {
    validUntil: Math.floor(Date.now() / 1000) + 300, // 5-minute validity
    messages: [{
      address: "0:recipient_address",
      amount: "1000000000", // in nanoton
      payload: "base64_encoded_data"
    }]
  },
  {
    onRequestSent: () => console.log("Signature request sent")
  }
);

Event Monitoring

Wallet State Changes

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

// Call unsubscribe() when monitoring is no longer needed

System Events

Account Management

Retrieving Account Data

const account = okxTonConnect.getAccount();
console.log("Connected address:", account.address);

Wallet Information

const wallet = okxTonConnect.getWallet();
console.log("Wallet details:", wallet);

Error Handling

Common Error Codes

👉 Explore advanced integration examples

FAQ Section

How do I switch between testnet and mainnet?

The SDK automatically detects chain configuration based on the connected wallet. No manual switching required.

What's the recommended QR code library?

Any QR generation library will work. We recommend qrcode.js for web implementations.

Can I customize the connection timeout?

Yes, set the validUntil parameter in your transaction objects (unix timestamp).

👉 Need live support? Contact our developer team

How often should I check connection status?

Only monitor status when actively needing wallet interaction. Remember to unsubscribe listeners when inactive.

What's the maximum transaction validity?

We recommend 300 seconds (5 minutes) for most use cases to balance security and convenience.