TON Injected Provider API: Connect Browser Wallets & Integrate Web3 DApps

·

Integrating decentralized applications (DApps) with blockchain wallets is a critical step in delivering seamless Web3 experiences. The TON Injected Provider API enables developers to connect their DApps directly with browser extension wallets like OKX Wallet, allowing secure user authentication, transaction signing, and real-time blockchain interactions—all while adhering to the widely adopted Ton Connect protocol.

This guide dives deep into the functionality, structure, and implementation of the TON Injected Provider API, focusing on how developers can leverage it to build robust, user-friendly Web3 applications on The Open Network (TON).

Understanding the Injected Provider API

The Injected Provider API is a JavaScript interface embedded by wallet extensions—such as OKX Wallet—into websites users visit. This allows DApps to interact directly with the user’s wallet without requiring external SDKs for basic operations.

Through this API, your DApp can:

Unlike standalone SDKs, the injected provider works out-of-the-box once the user has a compatible wallet installed, reducing integration complexity and improving onboarding speed.

👉 Discover powerful tools to test your Web3 integrations quickly and securely.

Compatibility with Ton Connect Protocol

OKX Wallet's TON API fully complies with the official Ton Connect protocol, ensuring interoperability across compliant wallets and DApps. This standardization means your application can support multiple wallets with minimal configuration changes.

For enhanced developer experience, consider using the TON Connect SDK, which abstracts common tasks such as session management, QR code handling, and connection persistence.

However, when building lightweight or performance-critical applications, direct use of the injected provider offers greater control and reduced bundle size.

Accessing the Injected Provider Object

When a user with OKX Wallet visits your DApp, the wallet injects a global object into the webpage context. This object exposes key properties and methods for interacting with the wallet.

The following are the primary components exposed:

deviceInfo

Provides metadata about the user's device and wallet environment:

Use this to tailor UI/UX based on device capabilities or display compatibility warnings.

walletInfo

Describes the wallet itself:

This data can be used to show verified wallet badges or help users confirm they're connecting to a legitimate provider.

protocolVersion

Indicates the current Ton Connect protocol version supported by OKX Wallet. As of now, it returns 2, aligning with the latest standard.

Ensure your DApp checks this value during initialization to avoid unsupported method calls.

Establishing Wallet Connection with connect()

The connect() method initiates a secure session between your DApp and the user's wallet.

Parameters

🔐 Security Tip: Always validate the manifest file is served over HTTPS and signed if possible.

Return Value

Returns a Promise that resolves to a ConnectEvent object upon successful connection. This includes:

Example Usage

const provider = window.okxwallet.ton;
const result = await provider.connect({
  protocolVersion: 2,
  message: {
    manifestUrl: "https://your-dapp.com/manifest.json",
    items: ["ton_addr", "ton_proof"]
  }
});
console.log(result.address); // e.g., UQB...

👉 Start integrating secure wallet connections in minutes—explore advanced tools here.

Restoring Previous Connections

Use restoreConnection() to re-establish a session without prompting the user again. This method only retrieves basic account info (ton_addr) and fails silently if no active session exists.

Ideal for improving user experience on page reloads or app restarts.

try {
  const session = await provider.restoreConnection();
  console.log("Connected as:", session.address);
} catch (error) {
  console.log("No previous session found.");
}

Sending Transactions and Messages via send()

The send() method allows your DApp to request transaction signing and broadcasting.

Parameters

Using sendTransaction

Sends a transaction request to the wallet for approval.

Parameters:

Example:

{
  "valid_until": 1735689234,
  "messages": [
    {
      "address": "UQD...",
      "amount": "500000000",
      "payload": "te6ccg..."
    }
  ]
}

Upon approval, the wallet returns a signed transaction blob via the Promise resolution.

Managing Session Lifecycle

Disconnecting with send("disconnect")

Allows users to manually end their session:

await provider.send({ method: "disconnect", id: 1 });

Triggers cleanup on both client and wallet sides.

Event Listening with listen() and on/off

Stay updated on wallet state changes in real time.

Using listen(callback)

Registers a callback to receive all events:

const unsubscribe = provider.listen((event) => {
  console.log("Event:", event.type);
});
// Call unsubscribe() to stop listening

Returns an unsubscribe function for cleanup.

Using on() and off() (OKX-Specific)

Non-standard but useful for handling specific events:

function handleAccountChange(address) {
  console.log("Switched to:", address);
}
provider.on("accountChanged", handleAccountChange);

// Later remove listener
provider.off("accountChanged", handleAccountChange);

Frequently Asked Questions (FAQ)

Q: Is the Injected Provider API secure?
A: Yes. It operates within the browser’s security model, requiring explicit user consent for all actions like connecting or signing. No private keys are ever exposed to the DApp.

Q: Can I use this API with other wallets besides OKX Wallet?
A: While designed for OKX Wallet, any wallet supporting Ton Connect v2 and injecting similar interfaces may work. However, always test across targets for consistency.

Q: What happens if a user revokes access?
A: The DApp receives a disconnect event. Subsequent calls will fail until reconnection.

Q: How do I handle expired sessions?
A: Use restoreConnection() on load. If it fails, prompt the user to reconnect.

Q: Can I send multiple transactions at once?
A: Yes—include up to four messages in a single sendTransaction call. They’ll be processed sequentially but not guaranteed in order on-chain.

Q: Why use injected providers over SDKs?
A: Injected providers reduce dependency overhead and offer faster initialization, ideal for minimalistic or embedded DApps.

Final Thoughts

The TON Injected Provider API streamlines Web3 integration by offering direct, efficient access to user wallets. Whether you're building a decentralized exchange (DEX), NFT marketplace, or gaming platform, mastering this API ensures smoother user journeys and stronger security foundations.

With native support for Ton Connect standards and flexible event handling, OKX Wallet empowers developers to create truly responsive and trustworthy DApps on TON.

👉 Accelerate your Web3 development with reliable infrastructure and tools.