Integrating UI Wallet Connections for Aptos DApps

For developers building decentralized applications (DApps) on the Aptos blockchain, providing a seamless user experience for wallet connections is crucial. Beyond Software Development Kits (SDKs), a User Interface (UI) connection option offers significant flexibility. This approach is particularly valuable for DApps operating within messaging platforms like Telegram, where users can choose between opening their native mobile wallet app or staying within the Telegram environment to use a lightweight Mini Wallet.

This guide details the process of integrating and utilizing a UI interface for wallet connectivity, signing transactions, and managing user sessions within your Aptos DApp.

Installation and Initialization

To begin integrating the UI connection functionality, ensure your development environment is properly set up. The first step involves creating a connection object that will manage the UI for subsequent operations, including wallet linking and transaction signing.

Key Request Parameters

• dappMetaData (object): This object contains essential information about your DApp.

  • name (string): The name of your application. Note that this is for display purposes and 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. For optimal display, provide a URL that points to a PNG icon sized at 180x180 pixels.

• actionsConfiguration (object): This object configures various behavioral aspects.

  • modals: Defines when alert modals are displayed during transactions. Options include 'before', 'success', 'error', an array of these values, or 'all'. The default is 'before'.

• uiPreferences (object): Allows for customization of the UI's appearance.

  • theme: Sets the visual theme. Options include THEME.DARK, THEME.LIGHT, or 'SYSTEM' to match the user's device settings.
  • language: Specifies the UI language using standard locale codes (e.g., 'en_US', 'zh_CN'). This defaults to 'en_US'.

Return Value
The initialization process returns an OKXUniversalConnectUI object, which serves as your primary interface for all subsequent wallet interactions.

Connecting to a Wallet

The connection process is fundamental, as it retrieves the user's wallet address—which acts as their identifier—and gathers necessary parameters for future transaction signing.

Understanding Request Parameters

The connectParams object is central to this process:

• namespaces: This required parameter specifies the essential blockchain information your DApp needs. For the Aptos ecosystem, the key is 'aptos'. The connection will be rejected if the user's wallet does not support any of the chains listed here.

  • chains: An array of chain IDs you wish to connect to.
  • defaultChain (optional): Specifies a default chain from the list.
• optionalNamespaces: This parameter defines optional blockchain information. If these chains are not supported by the wallet, the connection will still proceed.

• sessionConfig: Contains settings for the session.

  • redirect: A deeplink URL to navigate to after a successful connection. For Telegram Mini Apps, this can be set to 'tg://resolve'.

What to Expect Upon Return

The connection request returns a Promise that resolves with a session object containing:

• A unique topic (session identifier).
• namespaces detailing the successfully connected blockchain protocols.
• Arrays of connected chains and accounts.
• Supported wallet methods.
• Information about your DApp (dappInfo).

👉 Explore more strategies for seamless wallet integration

Connect to Wallet and Sign

This method combines the wallet connection and data signing into a single step. The response is handled via the 'connect_signResponse' event.

Request Parameters

This method requires both the connectParams (as described above) and a signRequest parameter:

• signRequest: An array (though typically containing one element) of signing requests.

  • method: The specific method to call. For Aptos, this is commonly 'aptos_signMessage'.
  • chainId: The ID of the chain where the method should be executed. This must be one of the chains specified in the namespaces.
  • params: The parameters required by the requested method.

The return value mirrors that of the standard connection process but occurs after the signing request is completed.

Checking Wallet Connection Status

It is often necessary to verify whether a user's wallet is currently connected to your DApp. A simple function is provided for this purpose.

Return Value
This function returns a boolean value: true if a wallet is connected, and false otherwise. This check is useful for conditional UI rendering or triggering a reconnection flow.

Preparing and Signing Transactions

After a successful connection, you can interact with the user's wallet to sign messages and transactions. This requires first creating an OKXAptosProvider object by passing your OKXUniversalProvider instance to its constructor.

Fetching Wallet Address and Public Key

• Request: You can optionally specify a chain ID to retrieve an address for. If omitted, the address from the first connected Aptos chain will be used.
• Return Value: An object containing the wallet's address and publicKey.

Signing a Message

• Request Parameters:

  • message (object): A complex object that defines the message to be signed and what metadata to include (e.g., address, application domain, chainId).
  • chain: The chain ID for the request. This is highly recommended and mandatory if multiple chains are connected.
• Return Value: A Promise that resolves with an object containing the original message, the generated fullMessage, the signature, and all included metadata.

Signing and Broadcasting a Transaction

The process for transactions involves two key methods:

1. Sign a Single Transaction: Pass a transaction object and the target chain ID. This returns a Promise that resolves to the signed transaction data (Buffer).
2. Sign and Submit a Transaction: This method both signs the transaction and immediately broadcasts it to the blockchain. It takes the same parameters and returns a Promise that resolves to the on-chain transaction hash.

Disconnecting a Wallet

To disconnect the current wallet and delete the active session, call the appropriate disconnect method. This is a necessary step if you wish to allow users to switch between different wallets, as you must disconnect the current session before initiating a new connection.

Handling Errors and Events

Robust error handling is critical. The integration throws specific exceptions for different failure scenarios, which you should catch and handle gracefully within your DApp.

Common Error Codes

👉 Get advanced methods for debugging wallet connections

Frequently Asked Questions

What is the main advantage of using a UI for wallet connection?
A UI connection provides a user-friendly interface for non-technical users, guiding them through the process of linking their wallet to your DApp. It is especially beneficial in environments like Telegram Mini Apps, where users can choose to stay within the app or switch to their native wallet application seamlessly.

How do I choose between the native app wallet and the mini wallet in Telegram?
The UI interface automatically detects the environment. If the DApp is running within Telegram, it will present the user with both options. The user can then make their choice based on personal preference, without any additional configuration required from the developer.

What should I do if a user encounters a "Chain Not Supported" error?
This error indicates that the user's wallet does not support the Aptos blockchain or the specific chain ID you requested. Your DApp should catch this error and inform the user that they need to use a compatible Aptos wallet, potentially providing guidance or links to suitable options.

Is it possible to customize the appearance of the connection UI?
Yes, the uiPreferences object allows for basic customization. You can set the color theme (DARK, LIGHT, or SYSTEM) and choose from a wide range of supported languages to match your DApp's branding and target audience.

How do I handle a user rejecting a connection or signature request?
Your code should always anticipate the USER_REJECTS_ERROR exception. Catch this error and use it to trigger a graceful failure state in your UI, such as displaying a helpful message to the user rather than allowing the application to crash.

Can I connect to multiple Aptos chains simultaneously?
Yes, the protocol supports connecting to multiple chains within the same namespace. You specify these chains in the chains array within your connectParams. Remember to always specify the chain parameter in subsequent requests if you have multiple connections.