This guide details the process of integrating and utilizing the OKX Web3 UI for connecting to Sui-compatible wallets, enabling users to sign transactions and interact with decentralized applications (DApps). The UI provides a streamlined interface, allowing users to connect via a mobile app or directly within Telegram using the OKX Mini Wallet.
Installation and Initialization
To begin integrating OKX Connect into your DApp, ensure you have updated the OKX App to version 6.90.1 or later. You can integrate the necessary package using npm.
Before initiating a wallet connection, you must create a UI object. This object will handle subsequent operations like connecting wallets and sending transactions.
The initialization function is structured as follows:OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language)
Request Parameters
dappMetaData (object): Metadata describing your DApp.
name(string): The name of your application. This is not used as a unique identifier.icon(string): A URL pointing to your application's icon. The image must be in a format like PNG or ICO (SVG is not supported). A 180x180px PNG is recommended for optimal display.
actionsConfiguration (object): Configures modal behavior and return strategies.
modals(('before' | 'success' | 'error')[] | 'all'): Defines which modal notifications to display during a transaction process. The default is 'before'.returnStrategy(string 'none' |${string}://${string}): For app wallets, this specifies the deep link return strategy after a user signs or rejects a request. Within Telegram, you can configure this totg://resolve.tmaReturnUrl(string 'back' | 'none' |${string}://${string}): Specifies the return strategy for the Telegram Mini Wallet after a user signs or rejects a request. Use 'back' to close the wallet and return to the DApp, 'none' to take no action, or a custom deep link. The default is 'back'.
uiPreferences (object): Controls the UI's appearance.
theme: Sets the color theme. Options include THEME.DARK, THEME.LIGHT, or "SYSTEM".
- language: Sets the UI language. Supported options include "en_US", "zh_CN", and several others. The default is "en_US".
Return Value
- OKXUniversalConnectUI: The initialized UI object instance.
Connecting a Wallet
The connection process retrieves a user's wallet address, which serves as a unique identifier and is essential for signing transactions.
Use the following method to open the connection modal:okxUniversalConnectUI.openModal(connectParams: ConnectParams);
Request Parameters
connectParams (ConnectParams): The parameters required to establish a connection.
namespaces(Record<string, ConnectNamespace>): Essential information for the connection request. For Sui, the key is "sui". The connection will be rejected if the wallet does not support any of the requested chains.chains(string[]): An array of Chain IDs.optionalNamespaces(Record<string, ConnectNamespace>): Optional information for the connection request. For Sui, the key is "sui". The connection will still proceed even if these optional chains are not supported.sessionConfig(object): Configuration for the session.redirect(string): A deep link URL for redirection after a successful connection. For Telegram Mini Apps, this is typically set to "tg://resolve".
Return Value
A Promise that resolves to a session object containing:
topic(string): A unique session identifier.namespaces(Record<string, any>): Information about the successfully connected namespaces.chains(string[]): The connected chain information.accounts(string[]): The connected account addresses.methods(string[]): The list of supported methods for the current namespace.defaultChain(string, optional): The default chain for the current session.sessionConfig(SessionConfig, optional): The session configuration.dappInfo(object): The DApp information provided during initialization.name(string)icon(string)
Connecting a Wallet and Signing
This method combines the wallet connection process with an immediate request to sign data. The signature result is returned via a "connect_signResponse" event.
Request Parameters
- connectParams: The same ConnectParams object used for a standard connection.
signRequest (RequestParams[]): An array containing the signature request. Only one method is supported simultaneously.
method(string): The name of the method to call. Sui supports "sui_signMessage" and "sui_signPersonalMessage".chainId(string): The Chain ID where the method should be executed. This chain must be included in thenamespacesparameter.params(unknown[] | Record<string, any> | object | undefined): The parameters required for the specified method.
Return Value
- The return value is identical to the standard wallet connection promise, resolving with the session object.
Checking Wallet Connection Status
You can check if a wallet is currently connected to your DApp.
Return Value
boolean: Returnstrueif a wallet is connected, otherwisefalse.
Disconnecting a Wallet
This method disconnects the currently connected wallet and deletes the active session. You must disconnect the current wallet before attempting to connect a different one.
Preparing Transactions
To send transactions for signing or execution, you first need to create an OKXSuiProvider object. This provider is constructed by passing the initialized okxUniversalConnectUI object.
Getting Account Information
After a successful connection, you can retrieve basic information about the connected account.
suiProvider.getAccount();
Return Value
An object containing:
address(string): The connected wallet address.publicKey(string): The public key of the account (requires App version 6.92.0 or later).
Signing a Message
This method requests the wallet to sign a message.
Request Parameters
SuiSignMessageInput (object):
message(Uint8Array): The message to be signed, represented as a Uint8Array.
Return Value
A Promise that resolves to an object containing:
messageBytes(string)signature(string)
Signing a Personal Message
This method is used specifically for signing personal messages.
Request Parameters
SuiSignMessageInput (object):
message(Uint8Array): The personal message to be signed, represented as a Uint8Array.
Return Value
A Promise that resolves to an object containing:
bytes(string)signature(string)
Signing a Transaction
This method requests the wallet to sign a transaction without immediately broadcasting it to the network.
Request Parameters
Parameters are specific to the transaction being constructed.
Return Value
A Promise that resolves to an object containing:
signature(string): The generated signature.transactionBlockBytes(string): The bytes of the signed transaction block.
Signing and Sending a Transaction
This method requests the wallet to both sign a transaction and broadcast it to the Sui network for execution.
Request Parameters
Parameters are specific to the transaction being constructed.
Return Value
A Promise that resolves to an object containing:
confirmedLocalExecution(boolean)digest(string): The transaction digest hash.txBytes(string)
Handling Event Listeners
The UI SDK emits events to notify your DApp of state changes, such as session updates or responses to signature requests. The event types and handling mechanisms for Sui are consistent with those used for EVM-compatible chains. For a detailed list of events and their payloads, refer to the comprehensive 👉 Web3 wallet integration documentation.
Understanding Error Codes
Various errors can occur during the connection, signing, or transaction process. The error codes and their meanings for the Sui integration are the same as those defined for EVM-compatible chains. Consult the relevant documentation section for a full list of error codes and troubleshooting guidance.
Frequently Asked Questions
What is the OKX Web3 UI?
The OKX Web3 UI is a software development kit that provides pre-built user interface components. Developers can use it to easily integrate wallet connection and transaction signing features into their decentralized applications, offering a seamless experience for users on both mobile apps and platforms like Telegram.
What are the main benefits of using the UI over the SDK?
The primary advantage is a faster development cycle. The UI handles the complex rendering of modals, transaction prompts, and wallet selection screens, saving developers significant time and effort. It ensures a consistent, user-friendly experience that matches the OKX wallet's native design.
How do I handle users who reject a connection or signature request?
The SDK manages rejection flows automatically through its modal system. Your application should listen for relevant events (like connect_signResponse) and handle the promise rejections returned by the API calls. The error object will contain a code and message explaining the reason for the rejection, such as user denial.
Can I customize the appearance of the connection modal?
Yes, but the customization options are primarily limited to the overall theme (light or dark mode) and language settings through the uiPreferences object during initialization. Extensive UI customization typically requires using the underlying SDK instead of the pre-built UI components.
What is the difference between 'sui_signMessage' and 'sui_signPersonalMessage'?
While both are used for signing data, sui_signPersonalMessage is typically used for a standard format intended for user authentication or verification purposes. The specific implementation and formatting of the message may differ between the two methods, so it's important to use the one that matches your DApp's requirements and the expectations of the Sui network.
My transaction failed with an error code. Where can I find more information?
Error codes are standardized across OKX's Web3 tools. For a detailed explanation of any error code you encounter, please refer to the official error code documentation that covers EVM-compatible chains, as the same codes and meanings apply to the Sui integration.