Integrating Web3 wallets into decentralized applications (dApps) is a crucial step in delivering seamless user experiences across blockchain ecosystems. For developers building on the Tron network, connecting via trusted wallet solutions like OKX Connect ensures security, usability, and cross-platform compatibility — especially within Telegram Mini Apps and mobile environments.
This guide walks you through the complete process of integrating OKX Connect into your dApp for Tron-based interactions, from initialization to transaction signing, account management, and error handling — all while maintaining best practices in Web3 development.
Installation and Initialization
Before integrating OKX Connect, ensure that users have OKX App version 6.96.0 or higher installed. This version supports the full suite of Web3 features required for modern dApp interactions.
You can install the OKX Connect SDK using npm:
npm install @okxweb3/connectOnce installed, initialize the connection interface by creating a UI-ready instance. This object will manage all user-facing interactions such as wallet connections, transaction prompts, and signature requests.
Request Parameters
The initialization requires several configuration options:
dappMetaData– Information about your application:name: (string) Your dApp’s display name.icon: (string) URL to your app icon in PNG or ICO format (SVG not supported). Ideally 180x180px.
actionsConfiguration– Controls post-action behavior:modals: ('before' | 'success' | 'error')[] | 'all' — Determines when confirmation dialogs appear during transactions. Default:'before'.returnStrategy: (string) Deep link strategy after user approval/rejection. Usetg://resolvefor Telegram Mini Apps.tmaReturnUrl: ('back' | 'none' |${string}://${string}) — Controls navigation after signing in Telegram Mini Wallet.'back'closes the wallet and returns to the dApp; default is'back'.
uiPreferences:theme: THEME.DARK, THEME.LIGHT, or "SYSTEM" for system-level theme detection.
language: Supported locales include"en_US","zh_CN","es_ES","fr_FR","de_DE", and more. Defaults to"en_US".
👉 Get started with secure Web3 integration today
Returns
OKXUniversalConnectUI: The core interface object used for all subsequent wallet operations.
Connecting to a Wallet
To interact with a user's wallet, you must first establish a connection. This grants access to the wallet address, supported chains, and available methods.
Request Parameters
connectParams:namespaces: Required blockchain namespaces (e.g.,"tron").chains: Array of chain IDs (e.g.,["tron:mainnet"]).defaultChain?: Optional default chain.
optionalNamespaces: Additional namespaces that won’t block connection if unsupported.sessionConfig:redirect: Post-connection deep link (e.g.,tg://resolvefor Telegram).
🔐 If any required chain in namespaces is unsupported, the wallet will reject the connection.Returns (Promise)
Upon successful connection:
topic: Unique session identifier.namespaces: Record of connected namespaces.chains: List of active chain IDs.accounts: Array of connected wallet addresses.methods: Supported RPC methods (e.g., signTransaction).defaultChain: Currently active chain.sessionConfig: Redirect settings.dappInfo: Your app’s metadata (name, icon, etc.).
Preparing Transactions
After connecting, create an instance of OKXTronProvider using the initialized okxUniversalConnectUI. This provider enables interaction with the Tron blockchain using familiar patterns.
Example:
const tronProvider = new OKXTronProvider(okxUniversalConnectUI);This object allows you to build and send transactions securely through the user's wallet.
Retrieving Account Information
To fetch the connected wallet’s address on a specific network:
Request Parameter
chainId: Chain identifier (e.g.,"tron:mainnet").
Returns
Object containing:
address: (string) The user’s public wallet address.
This address serves as both an identity marker and a signing authority for transactions.
Signing Messages
Securely authenticate users by requesting message signatures.
Request Parameters
message: (string) Content to sign.chainId?: Target chain (e.g.,"tron:mainnet").
Returns
- Promise resolving to a signed message string.
Use cases include login authentication, proof-of-wallet ownership, or secure session establishment.
Signing Messages (V2)
An updated method for enhanced compatibility and security.
Request Parameters
message: (string) Message to be signed.chainId: (string) Chain context for signing.
Returns
- Signed message as a string.
👉 Unlock advanced Web3 capabilities with seamless wallet linking
Signing Transactions (signTransaction)
Prepare but do not broadcast a transaction. Ideal for multi-step workflows.
Request Parameters
transaction: (object) Raw transaction data. Can be generated viaTronWeb.transactionBuilder.chainId?: Network where the transaction will be executed.
Returns
- Promise resolving to a signed transaction object.
This gives developers control over when and how transactions are submitted.
Signing and Broadcasting Transactions (signAndSendTransaction)
Automate signing and on-chain submission in one step.
Request Parameters
transaction: (object) Transaction payload.chainId: (string) Target blockchain (e.g.,"tron:mainnet").
Returns
- Promise resolving to the transaction hash (string).
This is ideal for simple transfers, token swaps, or smart contract calls where immediate execution is desired.
Disconnecting the Wallet
To end a session securely:
await okxUniversalConnectUI.disconnect();This removes the current session and clears sensitive data. Always disconnect before attempting to reconnect or switch accounts.
⚠️ To switch wallets, always disconnect first.
Event Handling
OKX Connect emits real-time events for key actions:
"connect": Fired when a wallet connects successfully."disconnect": Triggered on session termination."accountsChanged": Notifies when the active account changes."chainChanged": Emitted when the default chain updates.
Listen to these events to keep your dApp interface synchronized:
okxUniversalConnectUI.on('accountsChanged', (accounts) => {
console.log('Account changed:', accounts);
});Error Codes and Troubleshooting
Common exceptions during integration:
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR: An unexpected issue occurred.OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR: Connection attempt while already connected.OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR: Action requires active connection.OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR: User denied request.OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED: Method not available on this chain/wallet.OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED: Chain not supported by wallet.OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED: Wallet doesn’t support requested feature.OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR: General connection failure.
Handle these gracefully with user-friendly messages to improve UX.
Frequently Asked Questions
Q: What Tron networks are supported?
A: Mainnet (tron:mainnet) and Nile Testnet (tron:testnet) are fully supported. Ensure correct chain IDs are passed during connection.
Q: Can I integrate OKX Connect into a Telegram Mini App?
A: Yes. Use deep links like tg://resolve in redirect and set tmaReturnUrl: 'back' for smooth navigation between Telegram and the wallet.
Q: Is SVG icon support available for dApp branding?
A: No. Only PNG or ICO formats are accepted for the dApp icon. Use a 180x180px PNG for optimal display.
Q: How do I handle user rejection during signing?
A: Catch the USER_REJECTS_ERROR code and prompt users with clear instructions on how to retry or proceed.
Q: Can I connect multiple chains at once?
A: Yes. Use both required (namespaces) and optional (optionalNamespaces) configurations to request access to multiple blockchains without blocking connection if one is unsupported.
Q: Is there rate limiting on API calls?
A: No direct rate limits, but excessive requests may trigger client-side throttling. Implement debouncing for frequent operations like balance checks.
👉 Maximize your dApp’s potential with reliable Web3 onboarding