Integrating Web3 functionality into your decentralized application (DApp) has never been easier. With OKX Connect UI, developers can seamlessly enable wallet connectivity, transaction signing, and cross-chain interactions—especially for Solana-compatible chains. Whether your DApp operates on the open web or within Telegram, this robust SDK-powered interface allows users to connect via mobile wallets or directly through the OKX Mini Wallet, all without leaving their current environment.
This guide walks you through the full integration process using OKX’s intuitive UI layer, covering initialization, wallet connection, signing methods, account management, and more—all optimized for Telegram-based DApps and multi-chain experiences.
Installation and Initialization
To begin integrating OKX Connect UI, ensure the OKX App is updated to version 6.90.1 or later. Once updated, install the package via npm:
npm install @okxweb3/connect-uiBefore connecting a wallet, initialize a UI-ready instance that will manage user interactions such as connection prompts, transaction approvals, and error handling.
Configuration Parameters
The initialization accepts several customizable options under dappMetaData, actionsConfiguration, uiPreferences, and language.
dappMetaData (Required)
- name (string): Your DApp's display name.
- icon (string): URL of your app icon in PNG or ICO format (SVG not supported). Recommended size: 180x180px.
actionsConfiguration
- modals:
'before' | 'success' | 'error' | 'all'
Controls when confirmation modals appear during transactions. Default:'before'. - returnStrategy: Deep link strategy after user action (e.g., signing). For apps in Telegram, use
tg://resolve. tmaReturnUrl: Strategy for Telegram Mini App (TMA) wallets:
'back': Close wallet and return to DApp (default).'none': No redirect after action.- Custom deep link:
${protocol}://${host}.
uiPreferences
- theme: Set UI theme:
THEME.DARK,THEME.LIGHT, or"SYSTEM"(follows device settings).
language
Supports multiple locales including:en_US, zh_CN, es_ES, fr_FR, de_DE, ja_JP, and more. Defaults to en_US.
👉 Discover how to embed seamless Web3 login in seconds
Connecting a Wallet
Establishing a secure connection with a user's wallet is the first step toward enabling blockchain interactions. This method retrieves the wallet address and prepares it for transaction signing.
Request Parameters
connectParams
namespaces (object): Required namespace(s) for chain compatibility. For Solana-compatible chains, use
"solana".{ solana: { chains: ["solana:mainnet", "solana:testnet"], defaultChain: "solana:mainnet" } }- optionalNamespaces (object): Fallback chains; connection proceeds even if unsupported.
- defaultChain (optional): Sets the default active chain upon connection.
⚠️ If any required chain in namespaces is unsupported, the wallet will reject the connection.Return Value
A Promise resolves with:
topic: Unique session identifier.namespaces: Active namespaces and supported methods.chains: Connected chain IDs.accounts: Array of connected wallet addresses.methods: List of available actions (e.g.,solana_signMessage).dappInfo: Metadata passed during initialization.
This structured response enables dynamic UI updates based on connected assets and capabilities.
Connect and Sign in One Step
Streamline onboarding by combining wallet connection with an immediate signature request—ideal for authentication flows or message verification.
Additional Parameter
signRequest: An array containing one signing request object:
method: Currently supportssolana_signMessage.chainId: Must be included in declared namespaces.params: Message payload to sign.
The signed data is returned via the connect_signResponse event, allowing real-time handling without additional calls.
👉 See live demos of one-click Web3 authentication
Check Wallet Connection Status
Verify whether a wallet is currently linked to your DApp.
const isConnected = okxUI.isConnected();Return Type: boolean
Use this check at page load or before initiating sensitive operations like trades or NFT mints.
Prepare and Sign Transactions
After connecting, interact with the blockchain by preparing transactions through the OKXSolanaProvider.
Initialize Provider
const provider = new OKXSolanaProvider(okxUniversalConnectUI);All actions respect the original actionsConfiguration set during initialization.
Signing Messages
Authenticate users securely by requesting a digital signature.
Parameters
- message (string): Text to sign.
- chain (string): Target chain ID (required when connected to multiple chains).
Returns
{
publicKey: string;
signature: Uint8Array;
}Commonly used for login systems where the backend verifies ownership of the private key.
Sign Single Transaction
Sign a Solana transaction object (Transaction or VersionedTransaction).
Parameters
- transaction: Raw transaction data.
- chain: Chain ID (recommended for multi-chain setups).
Returns
Signed transaction object ready for broadcasting.
Sign Multiple Transactions
Batch-sign several transactions at once—perfect for complex DeFi operations or NFT batch listings.
Parameters
- transactions: Array of transaction objects.
- chain: Execution chain.
Returns
Array of signed transactions.
Sign and Broadcast Transaction
Execute end-to-end transaction flow: sign and submit to the network in one call.
Parameters
- Same as single transaction signing.
Returns
- Promise
: Transaction hash (e.g., 5jJ...)
Ideal for DEX swaps, token approvals, or staking deposits where immediate feedback is crucial.
Retrieve Wallet Account Information
Get the active wallet address on a specific chain.
Parameter
- chain (optional): Chain ID (e.g.,
"solana:mainnet"). Defaults to first connected Solana chain.
Returns
{
address: string;
publicKey: PublicKey;
}Useful for populating user profiles or balance queries.
Disconnect Wallet
Terminate the current session cleanly.
await okxUI.disconnect();Always disconnect before attempting to reconnect or switch accounts.
Event Handling
Monitor real-time events such as:
session_event: Incoming blockchain events.connect_signResponse: Signature results.session_delete: User-initiated disconnect.
👉 Learn how event-driven architecture improves UX
These events allow responsive interfaces that react instantly to user actions within the wallet.
For full details on event types and payloads, refer to the unified documentation standard shared with EVM-compatible chains.
Error Codes
Standardized error responses help diagnose integration issues quickly. Common codes include:
4001: User rejected request.4100: Unauthorized namespace or method.4200: Method not supported.4900: Chain not connected.
Refer to the comprehensive error code list (aligned with EIP-1474) for debugging guidance during development.
Frequently Asked Questions (FAQ)
Q: Can I use OKX Connect UI in Telegram Mini Apps?
Yes. The UI fully supports Telegram environments. Configure tmaReturnUrl: 'back' so users return to your DApp after signing.
Q: Is Solana the only supported chain?
While focused on Solana-compatible chains, OKX Connect also supports EVM-based networks. Use appropriate namespaces ("solana" or "eip155") based on your target chain.
Q: What happens if a user denies a transaction?
The Promise rejects with error code 4001. Handle this gracefully in your UI—display a message and allow retry options.
Q: Can I customize the modal appearance?
You can set the theme (dark, light, or system) and language during initialization. Full UI component overrides are not supported to maintain security and consistency.
Q: Do users need the OKX App installed?
Yes. The connection relies on deep linking to the OKX mobile app or Mini Wallet within Telegram. Ensure your app detects wallet availability before triggering connect flows.
Q: How do I handle multiple chain support?
Declare both required and optional namespaces during connection. Use the returned chains and methods to dynamically enable/disable features based on what’s actually supported.
By leveraging OKX Connect UI, developers gain a powerful, secure, and user-friendly gateway to Solana-compatible ecosystems, with built-in support for modern Web3 patterns like one-click sign-in, batch transactions, and Telegram integration.