Integrating a secure and user-friendly wallet connection into your decentralized application (DApp) is essential for delivering a seamless Web3 experience. With OKX Connect, developers can easily enable Tron-based wallet connectivity, transaction signing, and user authentication — all within a clean, customizable UI framework.
This guide walks you through the full integration process of OKX Connect for Tron-compatible DApps, covering installation, initialization, wallet connection, transaction handling, message signing, and error management — with clear code patterns and best practices.
Installation and Initialization
Before integrating OKX Connect into your DApp, ensure the OKX App is updated to version 6.96.0 or later. The SDK can be installed via npm:
npm install @okxconnect/sdkOnce installed, initialize the OKXUniversalConnectUI instance to provide a UI layer for wallet interactions such as connection prompts, transaction confirmations, and sign requests.
Configuration Parameters
The initialization accepts a configuration object with the following properties:
dappMetaDataname: Your DApp’s display name (non-unique).icon: Public URL of your app icon in PNG or ICO format (SVG not supported). Recommended size: 180x180px.
actionsConfigurationmodals: Controls when UI alerts appear during actions. Options:'before','success','error', or'all'. Default:'before'.returnStrategy: Deep link strategy after user action (e.g., sign/reject). For mobile apps:${scheme}://${host}.tmaReturnUrl: For Telegram Mini Apps — options include'back','none', or a custom deep link liketg://resolve.
uiPreferencestheme: Set toTHEME.DARK,THEME.LIGHT, or'SYSTEM'to follow device settings.
language: Supported locales include'en_US','zh_CN','es_ES','fr_FR','ru_RU','de_DE','ja_JP', and more. Defaults to'en_US'.
👉 Get started with seamless Tron wallet integration today.
Return Value
- Returns an instance of
OKXUniversalConnectUI, which powers all subsequent wallet operations.
Connecting to a Tron Wallet
To begin interacting with a user’s wallet, establish a session by requesting connection permissions.
Request Parameters
connectParamsnamespaces: Required chain namespaces. For Tron:{ tron: { chains: ['tron:mainnet'] } }. If unsupported chains are included, the wallet rejects the request.optionalNamespaces: Additional chains that won’t block connection if unsupported.defaultChain: Optional default chain ID (e.g.,'tron:mainnet').sessionConfigredirect: Post-connection redirect URL. For Telegram Mini Apps:'tg://resolve'.
Return Value (Promise)
Upon successful connection:
topic: Unique session identifier.chains: Array of connected chain IDs.accounts: List of connected wallet addresses.methods: Supported methods (e.g.,tron_signTransaction).defaultChain: Default chain for the session.dappInfo: Your app’s metadata (name, icon).
This structured response enables dynamic DApp behavior based on user wallet state.
Getting Account Information
After connection, retrieve the user’s Tron wallet address.
Request Parameter
chainId: Specify the network, e.g.,'tron:mainnet'.
Return Value
{
"address": "TQa1WU5d..."
}Use this address to personalize UI elements, check balances, or load user-specific data from smart contracts.
Signing Messages
Securely authenticate users by requesting digital signatures on arbitrary messages.
Request Parameters
message: String to be signed (e.g., "Login to MyDApp").chainId(optional): Target chain, e.g.,'tron:mainnet'.
Return Value
A Promise resolving to a signed message string (hex-encoded), verifiable on-chain.
This method is ideal for non-transactional authentication flows without gas costs.
Signing Messages (V2)
An enhanced version with stricter chain enforcement.
Request Parameters
message: Message string.chainId: Required chain context (e.g.,'tron:mainnet').
Return Value
Same as V1 — returns a signed message string.
V2 ensures better compatibility with chain-specific signing standards and should be preferred in production environments.
Preparing and Signing Transactions
To interact with Tron smart contracts or transfer tokens, prepare transactions using TronWeb.
Step 1: Initialize Provider
const provider = new OKXTronProvider(okxUniversalConnectUI);This provider bridges your DApp with the user’s wallet for secure transaction signing.
SignTransaction
Sign a raw transaction without broadcasting it.
Request Parameters
transaction: Object built viaTronWeb.transactionBuilder.chainId(optional): Execution chain (e.g.,'tron:mainnet').
Return Value
Signed transaction object, ready for manual broadcast or further processing.
Useful for advanced workflows like batched operations or off-chain analysis.
SignAndSendTransaction
The most commonly used method for executing on-chain actions.
Request Parameters
transaction: Constructed using TronWeb.chainId: Target network (e.g.,'tron:mainnet').
Return Value
A Promise resolving to the transaction hash upon success.
This method handles both signing and broadcasting — perfect for token swaps, NFT mints, or contract calls.
👉 Enable one-click Tron transactions in your DApp now.
Disconnecting the Wallet
Allow users to securely end their session.
await okxUniversalConnectUI.disconnect();This removes the active session and clears sensitive data. Required before attempting to reconnect with a different wallet.
Event Handling
OKX Connect emits real-time events such as:
session_establishedtransaction_signeduser_rejected_requestsession_disconnected
Subscribe to these events to update your UI dynamically and improve user feedback.
Error Codes and Troubleshooting
Handle common exceptions gracefully using built-in error codes:
| Error Code | Meaning |
|---|---|
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR | Unexpected internal issue |
ALREADY_CONNECTED_ERROR | Connection already active |
NOT_CONNECTED_ERROR | No active session found |
USER_REJECTS_ERROR | User denied request |
METHOD_NOT_SUPPORTED | Action not allowed by wallet |
CHAIN_NOT_SUPPORTED | Chain not available in wallet |
WALLET_NOT_SUPPORTED | Incompatible wallet type |
CONNECTION_ERROR | Failed to establish connection |
Proper error handling enhances UX and reduces user drop-off during onboarding.
Frequently Asked Questions
How do I support Telegram Mini Wallets?
Configure the tmaReturnUrl in actionsConfiguration to 'back' or a Telegram deep link like tg://resolve. This ensures users return to your Mini App after signing.
Can I use SVG icons for my DApp?
No. Only PNG or ICO formats are supported for the icon field. Use a 180x180px PNG for optimal display.
Is OKX Connect free to use?
Yes. There are no fees for integrating or using OKX Connect in your DApp. Users pay standard network fees for transactions.
What Tron networks are supported?
Currently supports tron:mainnet. Testnet support may vary — always verify chain compatibility before requesting connection.
How do I handle multiple chain requests?
Use namespaces for required chains and optionalNamespaces for fallbacks. This prevents connection failure when some chains aren't supported.
Can I customize the modal appearance?
Yes. Through uiPreferences, you can set light/dark mode, language, and modal behavior (before, success, error) to match your brand.
👉 Unlock full Tron wallet functionality in minutes.
Core Keywords
- Tron wallet integration
- OKX Connect API
- DApp wallet connection
- Tron transaction signing
- Web3 wallet SDK
- Decentralized app authentication
- Message signing Web3
- Connect to Tron DApp
By following this guide, developers can build robust, secure, and user-centric DApps on the Tron blockchain using OKX Connect — streamlining onboarding, boosting engagement, and ensuring compliance with modern Web3 standards.