Solana-Compatible Web3 Wallet Integration with UI Support

Integrating Web3 functionality into decentralized applications (dApps) has become increasingly seamless, especially with the rise of user-friendly SDKs and intuitive UI solutions. For developers building on or integrating with Solana-compatible chains, leveraging a clean, responsive interface is key to enhancing user experience. This guide walks you through the complete process of integrating OKX Connect using a UI-based approach—ideal for dApps operating within environments like Telegram, where users can stay in-app while connecting mobile wallets or using the OKX Mini Wallet.

With support for Solana’s ecosystem, this integration enables secure wallet connections, transaction signing, multi-chain operations, and more—all wrapped in an easy-to-use interface.

Getting Started: Installation and Initialization

Before diving into wallet connectivity, ensure your environment is properly configured.

👉 Discover how to seamlessly integrate Web3 into your dApp today.

To begin, update the OKX App to version 6.90.1 or later. This version includes full support for the OKX Connect UI, enabling smooth interaction between your dApp and users' wallets.

You can install the necessary package via npm:

npm install @okxconnect/ui

Once installed, initialize the UI provider by creating an instance of OKXUniversalConnectUI. This object powers all subsequent interactions such as connecting wallets, signing transactions, and managing sessions.

Initialization Parameters

The initialization accepts a configuration object with the following properties:

`dappMetaData`

name (string): Your application's display name.
icon (string): URL to your app’s icon (recommended 180x180px PNG; SVG not supported).

`actionsConfiguration`

modals: Controls when modal prompts appear during actions. Options: 'before', 'success', 'error', or 'all'. Default: 'before'.
returnStrategy: Deep link return strategy for native app wallets (e.g., tg://resolve for Telegram).
tmaReturnUrl: For Telegram Mini Apps, defines behavior after signing:
- 'back' (default): Closes wallet and returns to dApp.
- 'none': No action post-signing.
- Custom deep link: Redirects accordingly.

`uiPreferences`

theme: Set to THEME.DARK, THEME.LIGHT, or "SYSTEM" for automatic theme detection.

`language`

Supports multiple locales including:
en_US, zh_CN, es_ES, fr_FR, de_DE, ja_JP, and more. Defaults to en_US.

Returns

OKXUniversalConnectUI: The main interface object used for all wallet interactions.

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—essential for identification and transaction signing.

Request Parameters

`connectParams`

namespaces: Required namespace(s). For Solana-compatible chains, use "solana".
- If any requested chain isn't supported, the wallet will reject the connection.
- Structure:
```
{
  solana: {
    chains: ['solana:mainnet', 'solana:testnet'],
    defaultChain: 'solana:mainnet'
  }
}
```
optionalNamespaces: Additional namespaces that won’t block connection if unsupported.

Returns (Promise)

Upon successful connection:

topic: Session identifier.
namespaces: Active namespace details.
chains: Connected chain IDs.
accounts: Array of connected account addresses.
methods: Supported methods (e.g., solana_signMessage).
defaultChain: Currently active chain.
dappInfo: Your app’s metadata (name, icon).

Connect and Sign in One Step

For improved UX, you can combine wallet connection with an immediate signature request—useful for authentication flows.

👉 Speed up user onboarding with one-click sign-in solutions.

Additional Parameter

signRequest: An array containing one signing request:
- method: e.g., "solana_signMessage"
- chainId: Must be included in the requested namespaces.
- params: Message or data to sign.

The signature result is emitted via the "connect_signResponse" event.

Returns the same session data as standard connection, plus triggers immediate signing flow.

Check Wallet Connection Status

Determine whether a wallet is currently connected without prompting the user.

Returns

boolean: true if connected, otherwise false.

Useful for UI rendering logic and conditional rendering of connect buttons or wallet features.

Preparing Transactions

To send transactions or sign messages, create an instance of OKXSolanaProvider, passing in the initialized OKXUniversalConnectUI.

All actions (e.g., signing, sending) will follow the behavior defined in actionsConfiguration during initialization.

Signing Operations

Sign a Message

Authenticate users securely by requesting a signature over a message string.

Parameters

message (string): Text to sign.
chain (string): Target chain ID (required when multiple chains are connected).

Returns

{
  publicKey: string,
  signature: Uint8Array
}

Sign a Single Transaction

Sign Solana transaction objects (Transaction or VersionedTransaction).

Parameters

transaction: The unsigned transaction.
chain: Chain ID (recommended even with single-chain setups).

Returns

Signed transaction object ready for broadcasting.

Sign Multiple Transactions

Batch-sign several transactions at once.

Parameters

transactions: Array of transaction objects.
chain: Execution chain.

Returns

Array of signed transactions.

Sign and Broadcast a Transaction

Streamline the process by signing and submitting the transaction in one call.

Returns

Promise: The transaction hash (TXID) upon success.

Ideal for simple transfers or token swaps where minimal user interaction is desired.

Retrieve Wallet Account Information

Fetch active account details from the connected wallet.

Parameter

chain (optional): Chain ID to retrieve address from. Defaults to first connected Solana chain.

Returns

{
  address: string,
  publicKey: PublicKey
}

Useful for displaying balances, NFTs, or personalized content based on wallet ownership.

Disconnect Wallet

Terminate the current session cleanly.

await okxConnectUI.disconnect();

Always disconnect before attempting to reconnect or switch accounts—ensures session integrity and avoids conflicts.

Event Handling

Real-time feedback enhances interactivity. The OKX Connect UI emits events such as:

"session_connected"
"session_disconnected"
"sign_request_sent"
"connect_signResponse"

These allow you to update UI states dynamically—show loaders, confirmations, or error messages based on user actions.

For full event list and usage patterns, refer to general Web3 Connect documentation (shared across EVM and non-EVM chains).

Error Codes

Common errors include:

USER_REJECTED_REQUEST: User denied connection or signing.
UNSUPPORTED_CHAIN: Requested chain not available in wallet.
INVALID_SESSION: Expired or malformed session topic.
CHAIN_MISMATCH: Attempted operation on unconnected chain.

Handle these gracefully with user-facing alerts and retry options.

Frequently Asked Questions (FAQ)

Q: Can I use this integration in Telegram mini apps?
A: Yes. The UI is optimized for Telegram environments. Use tmaReturnUrl: 'back' to return seamlessly to your mini app after signing.

Q: Is Solana the only supported blockchain?
A: While this guide focuses on Solana-compatible chains, OKX Connect also supports EVM-based networks. You can configure multi-chain dApps using namespaces.

Q: Do I need to host any backend services?
A: No. All operations occur client-side. Your dApp communicates directly with the OKX wallet via secure protocols.

Q: What happens if a user switches networks in their wallet?
A: The session reflects the change automatically. Always validate the current chain before executing critical operations.

Q: Are there rate limits or usage fees?
A: There are no usage restrictions or costs associated with the OKX Connect UI SDK.

Q: Can I customize the look and feel of the modals?
A: Limited customization is available via theme settings (dark, light, or system). Full UI overrides are not supported to maintain security and consistency.

👉 Start building powerful Web3 experiences with seamless wallet integration now.