In the evolving landscape of Web3, seamless wallet integration is crucial for delivering a smooth user experience. For developers building decentralized applications (DApps) on the Aptos blockchain, integrating a reliable and user-friendly wallet interface can significantly enhance adoption and engagement. The OKX Connect SDK offers not only robust functionality but also a fully featured UI layer that simplifies wallet onboarding — especially for DApps operating within Telegram.
Whether your users are interacting via a mobile app or a Telegram Mini App, OKX Connect enables them to either launch the OKX mobile wallet or use the built-in OKX Telegram Mini Wallet without leaving the chat environment. This flexibility reduces friction and improves conversion rates across platforms.
👉 Discover how easy it is to integrate Web3 login and transactions into your DApp today.
Installing and Initializing the UI
To begin using the OKX Connect UI, ensure that the OKX App is updated to version 6.92.0 or higher. This ensures compatibility with the latest features and security updates.
You can integrate OKX Connect into your DApp using npm:
npm install @okxconnect/sdkBefore initiating any wallet connection, you must first create an instance of OKXUniversalConnectUI. This object powers all UI-driven interactions such as connecting wallets, signing messages, and approving transactions.
Configuration Parameters
The initialization accepts several configuration options to tailor the user experience:
dappMetaData(object)name(string): Your DApp’s display name (not used as a unique identifier).icon(string): URL of your app icon in PNG or ICO format (SVG not supported). Recommended size: 180x180px.
actionsConfiguration(object)modals: Controls when prompts appear during actions —'before','success','error', or'all'. Default:'before'.returnStrategy: Deep link strategy after user action (approve/reject) in app wallets. Usetg://resolvefor Telegram environments.tmaReturnUrl: For Telegram Mini Apps, defines post-signing behavior:'back'(closes wallet, returns to DApp),'none', or a custom deep link. Default:'back'.
uiPreferences(object)theme: Choose fromTHEME.DARK,THEME.LIGHT, or"SYSTEM"for automatic theme detection.
language(string)
Supported locales include:"en_US","zh_CN","es_ES","fr_FR","de_DE", and more. Defaults to"en_US".
Returns
OKXUniversalConnectUI— The main interface for all wallet operations.
This setup prepares your DApp for secure, localized, and visually consistent Web3 interactions.
Connecting a Wallet
Connecting a wallet allows your DApp to retrieve the user's address — essential for authentication and transaction signing.
Request Parameters
connectParams(ConnectParams)namespaces: Required blockchain namespaces. For Aptos, use"aptos"; for EVM chains, use"eip155". If any requested chain isn't supported, the wallet will reject the connection.chains: Array of chain IDs (e.g.,"aptos:mainnet").defaultChain?: Optional default chain ID.
optionalNamespaces: Additional namespaces that won’t block connection if unsupported.sessionConfig:redirect: Post-connection redirect URL. In Telegram Mini Apps, set to"tg://resolve".
Returns (Promise)
topic: Unique session identifier.namespaces: Active namespace details.chains: Connected chain list.accounts: User account addresses.methods: Supported methods (e.g.,aptos_signMessage).defaultChain?: Current default chain.dappInfo: Name, icon, and redirect info passed during setup.
Once connected, your DApp can proceed with authenticated actions like signing or transacting.
👉 See how top Aptos DApps streamline wallet login with one click.
Connect and Sign in One Step
For faster onboarding, you can combine wallet connection with message signing — ideal for authentication flows.
Additional Parameters
signRequest(RequestParams[])
Only one method allowed at a time:method: Must be"aptos_signMessage"for Aptos.chainId: Chain where the method executes (must be innamespaces).params: Method-specific parameters (varies by request type).
The signed result is returned via the connect_signResponse event.
This approach reduces steps for users while securely verifying ownership of the wallet address.
Check Wallet Connection Status
Before performing sensitive operations, verify whether a wallet is currently connected.
Returns
boolean:trueif connected; otherwise,false.
Use this check at page load or before transaction initiation to guide users through reconnection if needed.
Prepare Transactions with OKXAptosProvider
To interact with the Aptos blockchain, instantiate an OKXAptosProvider using the underlying OKXUniversalProvider.
This provider enables your DApp to construct and submit transactions securely through the user’s approved wallet session.
Retrieve Wallet Address and Public Key
Request Parameter
chain(string): Chain ID for which to fetch the address. Defaults to the first connected Aptos chain.
Returns
address(string): User’s wallet address.publicKey(string): Corresponding public key.
These values are essential for identity verification, transaction building, and off-chain message validation.
Sign Messages
Securely request users to sign arbitrary messages — useful for login authentication or data integrity checks.
Parameters
message(object)address?: Include wallet address in message.application?: Include DApp domain.chainId?: Include current chain ID.message: Text shown to the user.nonce: A unique string generated by your DApp.
chain(string): Target chain for signing (required when multiple chains are connected).
Returns (Promise)
address,application,chainId,nonce,prefix("APTOS"),fullMessage: Complete message signed by the user.signature: Hex-encoded cryptographic signature.
This method follows Aptos standards and ensures transparency in what users sign.
Sign a Single Transaction
Submit one transaction for user approval and signing.
Parameters
transaction: Transaction payload (object orSimpleTransaction).chain: Execution chain (recommended; required with multi-chain connections).
Returns
Promise<Buffer>: Raw signed transaction buffer.
Ideal for custom transaction pipelines or batch processing outside the SDK.
Sign and Broadcast Multiple Transactions
Execute multiple transactions in sequence with a single approval prompt.
Parameters
transactions: Array of transaction objects.chain: Target blockchain.
Returns
Promise<string>: Final transaction hash (on-chain confirmation).
Efficient for complex operations like asset swaps or multi-step smart contract calls.
Disconnect Wallet
Terminate the active session and clear stored data.
Use this when users log out or switch accounts. Always disconnect before attempting a new connection to avoid conflicts.
Event Handling
OKX Connect emits real-time events such as:
- Session established
- User disconnection
- Transaction confirmations
- Signing requests
Subscribe to these events to update UI states dynamically and improve responsiveness.
Error Codes
Common exceptions during interaction:
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR: Unexpected failure.ALREADY_CONNECTED_ERROR: Attempted duplicate connection.NOT_CONNECTED_ERROR: Action requires prior connection.USER_REJECTS_ERROR: User denied request.METHOD_NOT_SUPPORTED: Unsupported method call.CHAIN_NOT_SUPPORTED: Chain not available in wallet.WALLET_NOT_SUPPORTED: Incompatible wallet type.CONNECTION_ERROR: Network or handshake failure.
Handle these gracefully with user-friendly messages to maintain trust and usability.
👉 Turn errors into smooth recovery paths — start optimizing your flow now.
Frequently Asked Questions (FAQ)
Q: Can I use OKX Connect UI in Telegram Mini Apps?
A: Yes. Users can either open the full OKX mobile app or stay within Telegram using the integrated Mini Wallet — providing seamless access without app switching.
Q: What chains does OKX Connect support?
A: It supports Aptos (aptos) and EVM-based chains (eip155). You can connect both required and optional chains based on your DApp's needs.
Q: Is SVG supported for DApp icons?
A: No. Only PNG and ICO formats are accepted. Use a 180x180px PNG for best results.
Q: How do I handle multi-chain transactions?
A: Always specify the chain parameter when signing or sending transactions. This avoids ambiguity when users are connected to multiple networks.
Q: Can I customize the UI theme?
A: Yes. Set theme to 'DARK', 'LIGHT', or 'SYSTEM' to match your DApp’s design language.
Q: What happens if a user rejects a transaction?
A: The promise rejects with USER_REJECTS_ERROR. Catch this error to prompt retry or cancel flow appropriately.
By leveraging OKX Connect’s UI capabilities, developers can deliver professional-grade Web3 experiences on Aptos with minimal effort — focusing more on innovation and less on integration complexity.