Sui SDK Integration Guide | Connect Web3 Apps and Mini Wallets

Sui, also known as Sui Network, is the first Layer 1 blockchain designed from the ground up to empower developers to build next-generation experiences for over a billion new Web3 users. With its scalable architecture, Sui delivers high-speed transaction processing at minimal cost, making it ideal for diverse decentralized applications (DApps). As a pioneer in general-purpose blockchain innovation, Sui offers exceptional throughput, near-instant finality, rich on-chain assets, and an intuitive user experience—marking a transformative leap in blockchain technology engineered to meet the needs of all stakeholders in the crypto ecosystem.

Whether you're building a decentralized exchange (DEX), NFT marketplace, or Telegram Mini App, integrating with Sui via secure and efficient wallet connectivity is essential. This guide walks you through the full integration process using OKX Connect, enabling seamless interaction between your DApp and users' wallets.

👉 Get started with secure, seamless Web3 integration today.

Installation and Initialization

To begin integrating OKX Connect into your DApp, ensure your OKX App is updated to version 6.90.1 or later. You can install the required SDK via npm:

npm install @okxconnect/sdk

Before connecting a wallet, initialize the OKXUniversalProvider object. This instance will manage all subsequent operations such as wallet connection, transaction signing, and account management.

Request Parameters

• dappMetaData – Object

  • name (string): The name of your application. Not used as a unique identifier.
  • icon (string): URL of your app’s icon. Must be in PNG or ICO format (SVG not supported). A 180x180px PNG is recommended.

Returns

• OKXUniversalProvider – The core interface for wallet interactions.

Example

import { OKXUniversalProvider } from '@okxconnect/sdk';

const provider = new OKXUniversalProvider();
await provider.init({
  dappMetaData: {
    name: 'My Sui DApp',
    icon: 'https://example.com/icon.png'
  }
});

Connecting a Wallet

Use the connect method to establish a session and retrieve the user's wallet address—essential for identification and transaction signing.

okxUniversalProvider.connect(connectParams: ConnectParams);

Request Parameters

• connectParams – ConnectParams

  • namespaces – { [namespace: string]: ConnectNamespace }: Required chain information. Use "sui" for Sui Network.

    • chains – string[]: Array of chain IDs (e.g., ["sui:mainnet"]).

  • optionalNamespaces – { [namespace: string]: ConnectNamespace }: Optional chains. Connection proceeds even if unsupported.

    • chains – string[]: e.g., ["eip155:1", "sui:testnet"].

  • sessionConfig – Object

    • redirect – string: Post-connection redirect URL. For Telegram Mini Apps, use "tg://resolve".

Returns (Promise)

• topic: Session identifier.
• namespaces: Confirmed namespace details.
• chains: Active chain IDs.
• accounts: Connected wallet addresses.
• methods: Supported wallet methods.
• defaultChain?: Default chain for the session.
• sessionConfig?: Session configuration.
• dappInfo: Application metadata (name, icon, redirect).

👉 Enable one-click wallet access for your users now.

Check Wallet Connection Status

Verify whether a wallet is currently connected.

Returns

• boolean: true if connected; otherwise, false.

Example

const isConnected = provider.isConnected();
console.log('Wallet connected:', isConnected);

Disconnecting the Wallet

Terminate the current session and disconnect the wallet. Required before switching accounts or reconnecting.

Example

await provider.disconnect();
console.log('Wallet disconnected');

Preparing Transactions

To send transactions or sign messages, first create an OKXSuiProvider instance using the initialized OKXUniversalProvider.

const suiProvider = new OKXSuiProvider(okxUniversalProvider);

This provider enables Sui-specific operations like signing and broadcasting transactions.

Retrieving Account Information

Fetch the user’s wallet details after successful connection.

Returns

• Object

  • address (string): User’s Sui wallet address.
  • publicKey (string): Public key (requires OKX App version 6.92.0 or higher).

Example

const account = await suiProvider.getAccount();
console.log('Address:', account.address);

Signing Messages

Sign arbitrary data securely using the user’s private key.

Request Parameters

• SuiSignMessageInput – Object

  • message (Uint8Array): The message to sign.

Returns (Promise)

• Object

  • messageBytes (string): Serialized message.
  • signature (string): Cryptographic signature.

Signing Personal Messages

Used for authenticating users with human-readable messages.

Request Parameters

• Same as SuiSignMessageInput.

Returns (Promise)

• Object

  • bytes (string): Encoded message.
  • signature (string): Digital signature.

Example

const result = await suiProvider.signPersonalMessage({
  message: new TextEncoder().encode('Login to My DApp')
});

Signing Transactions

Sign a transaction without broadcasting it—ideal for multi-step workflows.

Returns (Promise)

• Object

  • signature (string)
  • transactionBlockBytes (string)

Sign and Broadcast Transaction

Sign and immediately submit the transaction to the Sui network.

Returns (Promise)

• Object

  • confirmedLocalExecution (boolean): Whether execution was confirmed locally.
  • digest (string): Transaction ID.
  • txBytes (string): Serialized transaction.

Example

const result = await suiProvider.signAndExecuteTransactionBlock({
  transactionBlock: Uint8Array.from([...])
});
console.log('Transaction digest:', result.digest);

Event Handling

Listen to real-time events such as:

• 'connect': Triggered upon successful connection.
• 'disconnect': Fired when session ends.
• 'accountsChanged': Notifies account updates.

Example:

provider.on('accountsChanged', (accounts) => {
  console.log('Account switched:', accounts[0]);
});

Error Codes

Common exceptions during connection, signing, or disconnection:

• OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR: Unexpected internal error.
• OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR: Attempt to reconnect without disconnecting.
• OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR: Operation requires active session.
• OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR: User denied request.
• OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED: Method not available on wallet.
• OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED: Chain not supported by wallet.
• OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED: Wallet incompatible.
• OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR: Network or handshake failure.

Handle these gracefully to improve user experience.

Frequently Asked Questions (FAQ)

Q: What blockchain networks does this SDK support?
A: The SDK supports Sui Network (sui) as a primary namespace and optionally EVM-compatible chains via eip155.

Q: Can I integrate this into a Telegram Mini App?
A: Yes. Set the redirect parameter to "tg://resolve" in session config for smooth in-app redirection.

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 user rejection of a transaction?
A: Catch the USER_REJECTS_ERROR code and prompt the user again with clearer context.

Q: Do users need the latest OKX App version?
A: Yes. Version 6.90.1+ is required for core features; some functions (like public key access) require 6.92.0+.

Q: Can I reconnect automatically after disconnection?
A: No. Always prompt the user explicitly before re-initiating a connection for security compliance.

👉 Unlock full Web3 potential with seamless Sui integration.