The OKX Connect UI provides a streamlined interface for developers to integrate wallet connectivity and transaction functionalities into their decentralized applications (DApps) on the Sui blockchain. This guide covers the essential methods, from initialization to transaction broadcasting, ensuring a smooth user experience whether users are on a mobile app or within a Telegram Mini App environment.
Installation and Initialization
To begin integrating OKX Connect into your DApp, ensure the OKX App is updated to version 6.90.1 or later. Use npm for integration:
// Example npm command
npm install @okx/web3-connectInitialize the UI component with the necessary parameters to create an interface object for wallet operations:
OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language)Key Parameters:
dappMetaData: An object containing:
name: Your application’s name (non-unique identifier).icon: A URL pointing to a PNG or ICO icon (180x180px recommended; SVG not supported).
actionsConfiguration: Configures modal displays and return strategies:
modals: Sets alert modes for transactions ('before','success','error', or'all'; defaults to'before').returnStrategy: For app wallets, defines deep link behavior after user signs/rejects ('none'or a custom deeplink).tmaReturnUrl: For Telegram Mini Wallet, specifies post-signing behavior ('back'to close wallet,'none', or a custom deeplink).
- uiPreferences: Customize UI themes (
THEME.DARK,THEME.LIGHT, or'SYSTEM'). - language: Supports multiple locales (e.g.,
'en_US','zh_CN'; defaults to'en_US').
Returns: An OKXUniversalConnectUI instance for subsequent operations.
Connecting to a Wallet
Invoke the modal to connect a wallet and retrieve address details and signing parameters:
okxUniversalConnectUI.openModal(connectParams);Parameters:
connectParams: Includes:
namespaces: Required chain namespaces (use'sui'for Sui blockchain). If unsupported, connection is rejected.chains: Array of chain IDs.optionalNamespaces: Optional namespaces (e.g.,'eip155'for EVM,'sui'for Sui). Unsupported chains don’t block connection.sessionConfig: Configures post-connection redirects (e.g., Telegram deeplink'tg://resolve').
Returns: A promise containing session details like topic, namespaces, accounts, methods, and default chain.
Connecting and Signing in One Step
Combine wallet connection and data signing, with results handled via the 'connect_signResponse' event:
// Method for simultaneous connect and sign
okxUniversalConnectUI.connectAndSign(connectParams, signRequest);Parameters:
- connectParams: As above.
signRequest: Array of request params for signing (supports one method at a time):
method: Signing method (e.g.,'sui_signMessage','sui_signPersonalMessage').chainId: Chain ID for the method (must match namespaces).params: Method-specific parameters.
Returns: A promise with session data and signing results.
👉 Explore advanced signing methods
Checking Wallet Connection Status
Determine if a wallet is currently connected:
const isConnected = okxUniversalConnectUI.isConnected();Returns: true or false.
Disconnecting a Wallet
Terminate the current session and clear wallet data:
okxUniversalConnectUI.disconnect();Note: Disconnect before switching wallets to ensure clean reinitialization.
Preparing Transactions
To send transactions or messages requiring wallet confirmation, first create an OKXSuiProvider object:
const suiProvider = new OKXSuiProvider(okxUniversalConnectUI);This provider enables methods for account queries, signing, and transaction broadcasting.
Retrieving Account Information
Fetch basic account details:
const accountInfo = suiProvider.getAccount();Returns: An object with address (wallet address) and publicKey (requires App v6.92.0+).
Signing Messages
Sign a message using the Sui protocol:
const signResult = await suiProvider.signMessage({
message: new Uint8Array([...]) // Message as Uint8Array
});Returns: A promise with messageBytes and signature.
Signing Personal Messages
Sign a personal message (similar to Ethereum’s personal_sign):
const personalSignResult = await suiProvider.signPersonalMessage({
message: new Uint8Array([...])
});Returns: A promise with bytes and signature.
Signing Transactions
Sign a transaction without broadcasting:
const signTxResult = await suiProvider.signTransaction({
transactionBlock: ... // Transaction data
});Returns: A promise with signature and transactionBlockBytes.
Signing and Broadcasting Transactions
Sign a transaction and broadcast it to the chain:
const broadcastResult = await suiProvider.signAndExecuteTransaction({
transactionBlock: ... // Transaction data
});Returns: A promise with digest (transaction hash), txBytes, and confirmedLocalExecution (boolean).
👉 Get real-time transaction tools
Handling Events and Errors
Event handling and error codes for Sui mirror those of EVM-compatible chains. Refer to the EVM UI events documentation and EVM SDK error codes for details.
Frequently Asked Questions
How do I handle unsupported chains in namespaces?
If a chain in namespaces is unsupported, the connection is rejected. Use optionalNamespaces for non-critical chains to allow partial connections.
Can I customize the UI language dynamically?
Yes, initialize OKXUniversalConnectUI with a language parameter (e.g., 'es_ES' for Spanish). The UI will reflect this locale.
What happens if a user rejects a signing request?
The promise rejects with an error code. Handle this gracefully in your DApp, such as by prompting the user to retry.
Is SVG icon support planned?
Currently, only PNG and ICO icons are supported. SVG icons are not compatible due to rendering constraints.
How do I switch between connected wallets?
Always call disconnect() first to clear the current session. Then re-invoke openModal() for a fresh connection.
Are there rate limits for transaction broadcasting?
No inherent limits exist, but network congestion on Sui may cause delays. Monitor chain status for optimal performance.
This guide ensures seamless integration of OKX Connect UI for Sui DApps, balancing flexibility with robust functionality. For further details, consult the official documentation.