Sui Blockchain Integration with OKX Connect: Wallet Connection & Transaction Signing Guide

Integrating decentralized applications (DApps) with blockchain wallets is a critical step in delivering seamless Web3 experiences. For developers building on the Sui blockchain, leveraging OKX Connect offers a robust, user-friendly solution for wallet connectivity—especially within environments like Telegram Mini Apps. This guide walks you through the full integration process using the OKX Universal Connect UI SDK, focusing on connecting to wallets, managing user sessions, signing transactions, and handling events—all while maintaining optimal UX.

Whether your DApp runs natively or inside Telegram, users can choose between launching the OKX App wallet or using the lightweight OKX Telegram Mini Wallet, ensuring flexibility without compromising security.

Installation and Initialization

To begin integrating OKX Connect into your Sui-based DApp, ensure the OKX mobile app is updated to version 6.90.1 or later. You can install the SDK via npm:

npm install @okxweb3/connect

Before enabling wallet interactions, initialize the UI interface with configuration options that define how your DApp communicates with the wallet:

OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language);

Request Parameters

• dappMetaData – Application details:

  • name: DApp name (non-unique).
  • icon: Public URL to a 180x180px PNG icon (SVG not supported).

• actionsConfiguration – Controls modal behavior and return logic:

  • modals: Display alerts during 'before', 'success', 'error' stages, or 'all'.
  • returnStrategy: Deep link strategy after signing (e.g., tg://resolve for App wallet in Telegram).
  • tmaReturnUrl: For Telegram Mini Wallet; use 'back' to return to DApp post-signing (default), 'none', or a custom deep link.

• uiPreferences – Visual settings:

  • theme: Accepts THEME.DARK, THEME.LIGHT, or 'SYSTEM'.
• language – Supported locales include 'en_US', 'zh_CN', 'es_ES', 'fr_FR', and more. Defaults to 'en_US'.

👉 Discover how easy it is to integrate Sui wallet connections in minutes.

Connect to Wallet

Establish a secure session by requesting access to the user’s wallet address and signing capabilities.

Use the following method to open the connection modal:

okxUniversalConnectUI.openModal(connectParams);

Connection Parameters

• namespaces: Required chain-specific data. For Sui, use key 'sui'.
• chains: Array of chain IDs (e.g., ['sui:testnet', 'sui:mainnet']). Unsupported chains will reject the connection.
• optionalNamespaces: Optional chains (e.g., EVM via 'eip155'). Missing support won’t block connection.
• sessionConfig.redirect: Post-connection redirect URL. In Telegram Mini Apps, set to tg://resolve.

Return Value (Promise)

Upon successful connection, returns:

• topic: Unique session identifier.
• namespaces: Confirmed namespace details.
• chains: Connected chain IDs.
• accounts: User wallet addresses.
• methods: Supported operations (e.g., sui_signMessage).
• defaultChain: Default chain for session.
• dappInfo: Name and icon passed during initialization.

Connect and Sign in One Flow

Streamline user experience by combining wallet connection with an immediate signing request. The signed response is delivered via the 'connect_signResponse' event.

Parameters

In addition to standard connectParams, include:

• signRequest: Array of one signing method object:

  • method: e.g., 'sui_signMessage' or 'sui_signPersonalMessage'.
  • chainId: Must match one from namespaces.
  • params: Method-specific input (e.g., message bytes).

This flow reduces friction—ideal for authentication or message verification at login.

Check Wallet Connection Status

Verify whether an active session exists:

const isConnected = okxUniversalConnectUI.isConnected();

Returns a boolean value: true if connected, false otherwise.

Use this to conditionally render UI elements like “Connect Wallet” buttons or protected content.

Disconnect Wallet

Terminate the current session cleanly:

okxUniversalConnectUI.disconnect();

This removes all session data. Always disconnect before attempting to switch accounts or reconnect.

👉 Learn how to build secure, responsive DApps on Sui with integrated wallet management.

Prepare and Send Transactions

To interact with the Sui network, create a provider instance:

const suiProvider = new OKXSuiProvider(okxUniversalConnectUI);

This enables transaction preparation, signing, and broadcasting.

Get Account Information

Retrieve user wallet details:

const account = await suiProvider.getAccount();

Returns:

• address: User’s Sui wallet address.
• publicKey: Public key (requires OKX App v6.92.0+).

Ideal for displaying profile info or verifying ownership.

Sign Messages

Support secure authentication and off-chain verification with message signing.

Sign Generic Message

const result = await suiProvider.signMessage({ message: new TextEncoder().encode("Hello Sui") });

Returns:

• messageBytes: Encoded message.
• signature: Cryptographic signature.

Sign Personal Message

Uses personal signing standards (e.g., prefixed messages):

const result = await suiProvider.signPersonalMessage({ message: new TextEncoder().encode("Login to MyApp") });

Returns:

• bytes: Serialized message.
• signature: Signature string.

Both methods are essential for non-transactional proofs of ownership.

Sign and Broadcast Transactions

Execute on-chain actions securely.

Sign Transaction Only

const signedTx = await suiProvider.signTransaction({ transactionBlock });

Returns:

• signature
• transactionBlockBytes

Useful for multi-party approvals or offline signing scenarios.

Sign and Execute

const result = await suiProvider.signAndExecuteTransaction({ transactionBlock });

Returns:

• digest: Transaction ID.
• confirmedLocalExecution: Boolean indicating success.
• txBytes: Serialized transaction.

Perfect for minting NFTs, swapping tokens, or interacting with smart contracts.

Handle Events and Errors

Event Listening

OKX Connect supports real-time event emission—including 'connect', 'disconnect', 'signResponse', and custom chain events. Refer to EVM-compatible documentation for detailed patterns applicable to Sui integrations.

Example:

okxUniversalConnectUI.on('connect', (session) => {
  console.log('Connected:', session.accounts);
});

Error Handling

Common errors include rejected requests, unsupported chains, invalid parameters, and network timeouts. Error codes align with those used in EVM integrations—ensuring consistency across blockchains.

Handle rejections gracefully:

try {
  await okxUniversalConnectUI.openModal(connectParams);
} catch (error) {
  console.error("Connection failed:", error.message);
}

FAQ Section

Q: Can I integrate OKX Connect in a Telegram Mini App?
A: Yes. Configure tmaReturnUrl: 'back' so users return to your Mini App after signing. The OKX Telegram Mini Wallet allows seamless in-app interactions without leaving Telegram.

Q: What Sui networks are supported?
A: Both Sui testnet (sui:testnet) and mainnet (sui:mainnet) are supported. Ensure correct chain IDs are specified in the connection request.

Q: Is SVG icon support available for DApp metadata?
A: No. Only PNG or ICO format icons are accepted. Use a 180x180px PNG for best display quality.

Q: How do I handle multiple signing requests?
A: Only one signing method is allowed per request. Queue subsequent operations after the first completes.

Q: Can users switch wallets mid-session?
A: Not directly. You must call .disconnect() first before initiating a new connection flow.

Q: Is user data stored by OKX Connect?
A: No session or personal data is stored long-term. All information resides client-side unless explicitly cached by your DApp.

👉 Start building powerful Sui DApps with built-in wallet connectivity today.