Sui Wallet Integration with OKX Connect: SDK Guide for DApps and Mini Wallets

Integrating a crypto wallet into your decentralized application (DApp) is a crucial step in delivering seamless user experiences on blockchain platforms. For developers building on the Sui network, leveraging the OKX Connect SDK enables secure, efficient, and scalable wallet connectivity—especially for apps targeting mobile users or mini-wallet integrations within ecosystems like Telegram.

This guide walks you through the complete process of integrating OKX Connect into your DApp for the Sui blockchain, covering initialization, connection flow, transaction handling, signing methods, and error management—all while ensuring compatibility with modern Web3 standards.

Installation and Initialization

To begin integrating OKX Connect into your DApp, ensure that users have the OKX App version 6.90.1 or higher installed. This version supports the universal provider interface required for Sui-based interactions.

You can install the necessary dependencies via npm:

npm install @okxweb3/connect

Before initiating any wallet operations, initialize the OKXUniversalProvider to prepare your app for interaction:

OKXUniversalProvider.init({
  dappMetaData: {
    name: "Your DApp Name",
    icon: "https://yourdapp.com/icon.png" // Must be a PNG or ICO file (180x180px recommended)
  }
});

👉 Get started with secure Sui wallet integration using OKX Connect today.

Parameters

• dappMetaData – Object containing metadata about your application.

  • name: (string) The display name of your DApp. Not used as a unique identifier.
  • icon: (string) Public URL pointing to your app’s icon in PNG or ICO format. SVG is not supported.

Returns

• OKXUniversalProvider: An initialized provider instance used for all subsequent wallet interactions.

Connecting to a Wallet

Establishing a connection allows your DApp to access the user's wallet address and obtain permission to request transaction signatures.

Use the connect() method with appropriate namespace configurations:

const connection = await okxUniversalProvider.connect({
  namespaces: {
    sui: {
      chains: ["sui:devnet", "sui:testnet", "sui:mainnet"],
      methods: ["sui_signTransaction", "sui_signMessage"]
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ["eip155:1", "eip155:3"],
      methods: ["eth_signTransaction", "eth_sign"]
    }
  },
  sessionConfig: {
    redirect: "tg://resolve" // Useful for Telegram Mini Apps
  }
});

Request Parameters

• namespaces: Required chain-specific configuration. For Sui, use the key 'sui'.

  • chains: Array of chain IDs (e.g., sui:devnet). If any are unsupported, the wallet rejects the connection.
• optionalNamespaces: Optional chains (like EVM). Connection proceeds even if these aren't supported.
• sessionConfig.redirect: Optional deep link for post-connection redirection (ideal for mini apps).

Return Value

A Promise resolving to an object containing:

• topic: Unique session identifier.
• namespaces: Active namespaces after connection.
• chains: Connected chain IDs.
• accounts: User account addresses.
• methods: Supported signing methods.
• defaultChain: Default active chain.
• dappInfo: Your app’s metadata (name, icon, redirect).

Check Wallet Connection Status

Determine whether a wallet is currently connected before attempting sensitive operations:

const isConnected = okxUniversalProvider.isConnected();

Return Value

• boolean: true if connected; otherwise false.

This check is essential for UI state rendering and preventing unauthorized actions.

Disconnecting the Wallet

To end a session securely, disconnect the wallet and clear session data:

await okxUniversalProvider.disconnect();

Note: Always disconnect the current wallet before attempting to switch accounts or reconnect.

Preparing Transactions on Sui

To send transactions, first instantiate the OKXSuiProvider using the universal provider:

const suiProvider = new OKXSuiProvider(okxUniversalProvider);

This provider exposes Sui-specific methods for signing and broadcasting transactions.

Retrieve User Account Information

Fetch the connected user’s wallet details:

const account = await suiProvider.getAccount();

Return Value

• address: (string) The user’s Sui wallet address.
• publicKey: (string) Public key in hex format — requires OKX App v6.92.0 or later.

👉 Unlock advanced Sui transaction capabilities with OKX Connect’s robust API.

Sign a Message

Request the user to sign arbitrary data without broadcasting it on-chain:

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

Parameters

• message: Uint8Array containing the message bytes.

Return Value

• messageBytes: Base64-encoded original message.
• signature: Base64-encoded cryptographic signature.

Useful for authentication flows or proving wallet ownership.

Sign Personal Message

Similar to signMessage, but follows personal signing conventions (often prefixed):

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

Returns:

• bytes: Encoded message.
• signature: Signed output.

Ideal for login systems where message formatting matters.

Sign a Transaction (Without Broadcasting)

Prepare and sign a transaction block without submitting it to the network:

const { signature, transactionBlockBytes } = await suiProvider.signTransaction({
  transactionBlock: serializedTx
});

Return Value

• signature: Signed payload.
• transactionBlockBytes: Serialized transaction in bytes.

Use this when you need backend verification or multi-party signing.

Sign and Broadcast Transaction On-Chain

Combine signing and submission in one step:

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

Return Value

• confirmedLocalExecution: Boolean indicating if execution was confirmed locally.
• digest: Transaction digest (used for on-chain lookup).
• txBytes: Raw transaction bytes.

Perfect for simple swap, transfer, or NFT minting operations in DEXs or gaming apps.

Event Handling

The OKX Connect provider emits events such as:

• 'connect'
• 'disconnect'
• 'accountsChanged'
• 'chainChanged'

Subscribe using standard event listeners:

okxUniversalProvider.on('accountsChanged', (accounts) => {
  console.log('Account switched:', accounts);
});

Real-time updates enhance responsiveness and UX in dynamic interfaces.

Error Codes and Troubleshooting

Common exceptions during integration are standardized for easier debugging:

Handle these gracefully with user-friendly prompts.

Frequently Asked Questions (FAQ)

Q: What minimum OKX App version is required?
A: Version 6.90.1 or later is required for full Sui integration support.

Q: Can I connect to multiple chains simultaneously?
A: Yes. Use both required (namespaces) and optional (optionalNamespaces) chain declarations to support multi-chain DApps.

Q: Is SVG icon supported during initialization?
A: No. Only PNG or ICO formats are accepted. Use a 180x180px image for best results.

Q: How do I handle user rejection of a transaction?
A: Catch the USER_REJECTS_ERROR code and prompt users to retry without resubmitting automatically.

Q: Can I use this SDK in Telegram Mini Apps?
A: Yes. Set the redirect parameter in sessionConfig to 'tg://resolve' for smooth return after connection.

Q: Does OKX Connect support offline signing?
A: Yes. Use signTransaction() to generate signatures without broadcasting—ideal for cold storage or multisig setups.

👉 Start building powerful Sui-integrated DApps with OKX Connect—fast, secure, and developer-friendly.