Integrating OKX Connect for Cosmos DApps: A Developer's Guide

This guide provides a comprehensive overview for developers looking to integrate OKX Connect into their Cosmos-based decentralized applications (DApps). It covers everything from installation and initialization to handling transactions and managing wallet connections.

Installation and Initialization

To begin integrating OKX Connect into your DApp, ensure you have the OKX App updated to version 6.94.0 or later. You can install the necessary package using npm.

Before connecting to a wallet, you must create an object that provides a user interface for subsequent operations like wallet connection and transaction signing.

Request Parameters

• dappMetaData - object

  • name - string: Your application's name (not used as a unique identifier).
  • icon - string: A URL pointing to your application's icon. Must be in PNG or ICO format; SVG is not supported. A 180x180px PNG is recommended for optimal display.

• actionsConfiguration - object

  • modals - ('before' | 'success' | 'error')[] | 'all': Configures alert display modes during transactions. The default is 'before'.
  • returnStrategy - string 'none' | ${string}://${string}: For the app wallet, this defines the deep link return strategy after a user signs or rejects a request (e.g., tg://resolve for Telegram).
  • tmaReturnUrl - string 'back' | 'none' | ${string}://${string}: For the Telegram Mini Wallet, this specifies the deep link return policy. 'none' means no post-signing processing; the default is 'back'.

• uiPreferences - object

  • theme - Can be: THEME.DARK, THEME.LIGHT, or 'SYSTEM'.
• language - Supported locales include 'en_US', 'zh_CN', and many others. Defaults to 'en_US'.

Return Value

The function returns an OKXUniversalConnectUI object, which is your primary interface for managing wallet connections.

Example Code Snippet

Establishing a Wallet Connection

Connecting to a wallet is a fundamental step to obtain a wallet address for user identification and to gather necessary parameters for signing transactions.

Request Parameters

• connectParams - ConnectParams

  • namespaces - [namespace: string]: ConnectNamespace: Essential information for the connection request. Use 'cosmos' for the Cosmos namespace. If the wallet does not support any requested chain, it will reject the connection.

    • chains: string[]: An array of chain IDs.
    • defaultChain?: string: The default chain.

  • optionalNamespaces - [namespace: string]: ConnectNamespace: Optional connection information. If these chains are unsupported, the connection can still proceed.

    • chains: string[]: An array of chain IDs.
    • defaultChain?: string: The default chain.

  • sessionConfig: object

    • redirect: string: A parameter for redirection after a successful connection (e.g., a Telegram deep link like 'tg://resolve' for Mini Apps).

Return Value

• Promise <ConnectResult>

  • topic: string: The unique session identifier.
  • namespaces: Record<string, Namespace>: Information on the successfully connected namespaces.
  • chains: string[]: The chain information for the connection.
  • accounts: string[]: The account information for the connection.
  • methods: string[]: The methods supported by the wallet within the current namespace.
  • defaultChain?: string: The default chain for this session.
  • sessionConfig?: SessionConfig

  • dappInfo: object: Information about your DApp.

    • name: string
    • icon: string
    • redirect?: string: The redirect parameter used after a successful connection.

Example Implementation

👉 Explore more connection strategies

Connecting and Signing in a Single Request

This method allows you to connect to a wallet and request a signature in one action. The result is returned via the 'connect_signResponse' event.

Request Parameters

• connectParams - ConnectParams: (As defined in the previous section).

• signRequest - RequestParams[]: An array of signing requests (only one method is supported simultaneously).

  • method: string: The name of the requested method. For Cosmos, this is 'cosmos_signArbitrary'.
  • chainId: string: The ID of the chain where the method executes. Must be included in the namespaces parameter.
  • params: unknown[] | Record <string, unknown> | object | undefined: The parameters required by the requested method.

Return Value

• Promise <ConnectResult>: (As defined in the previous section).

Checking Wallet Connection Status

A simple function to determine if a wallet is currently connected to your DApp.

Return Value

• boolean: true if connected, false if not.

Usage Example

Preparing and Signing Transactions

After successful connection and initialization, you can create an OKXCosmosProvider object by passing your OKXUniversalConnectUI instance to its constructor. This provider is your gateway to interacting with the Cosmos blockchain.

Retrieving Account Information

Request Parameters

• chainId: string: The chain you are querying (e.g., 'cosmos:cosmoshub-4', 'cosmos:osmosis-1').

Return Value

• Object

  • algo: 'secp256k1'
  • address: string: The wallet address.
  • bech32Address: string: The wallet address in bech32 format.
  • pubKey: Uint8Array: The public key.

Signing a Message

Request Parameters

• chainId: string: The chain on which to execute the signature.
• signerAddress: string: The address of the signing wallet.
• message: string: The message to be signed.

Return Value

• Promise - object

  • pub_key: object

    • type: string: The type of public key.
    • value: string: The public key value.
  • signature: string: The resulting signature.

Using SignAmino

This method signs a transaction using the Amino JSON format.

Request Parameters

• chainId: string: The chain for the signature request (required).
• signerAddress: string: The wallet address.
• signDoc: object: The transaction information in a fixed format, similar to the cosmjs OfflineSigner's signAmino method.

Return Value

• Promise - Object

  • signed: object: The signed transaction information.
  • signature: object: The signature result.

Using SignDirect

This method signs a transaction using Protobuf (Direct).

Request Parameters

• chainId: string: The chain for the signature request (required).
• signerAddress: string: The wallet address.

• signDoc: object: The transaction data.

  • bodyBytes: Uint8Array
  • authInfoBytes: Uint8Array
  • chainId: string
  • accountNumber: string

Return Value

• Promise - Object

  • signed: object: The signed transaction information.
  • signature: object: The signature result.

Managing Wallet Sessions

Disconnecting a Wallet

This function disconnects the currently connected wallet and deletes the active session. If you need to switch wallets, you must disconnect the current one first.

Handling Events and Errors

The integration emits various events for connection, signing, and session management. It's crucial to handle these events to manage the user flow effectively.

Common Error Codes

The following exceptions may be thrown during connection, transaction, or disconnection processes.

👉 Get advanced error handling methods

Frequently Asked Questions

What is the minimum OKX App version required for integration?
You must ensure your OKX App is updated to version 6.94.0 or later to access all the functionalities required for a successful OKX Connect integration with your DApp.

What image formats are supported for the DApp icon?
The DApp icon must be provided as a PNG or ICO file. SVG format is not supported. For the best visual results, use a URL that points to a high-quality PNG image sized at 180x180 pixels.

How do I handle a user rejecting a connection request?
Your code should catch the OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR exception. This allows you to gracefully inform the user that the request was canceled and perhaps prompt them to try again without causing application errors.

What is the difference between namespaces and optionalNamespaces?
The namespaces parameter defines the essential chains required for your DApp to function. If the wallet doesn't support them, the connection will fail. optionalNamespaces specifies additional chains your DApp can use but doesn't require; the connection will succeed even if these are unsupported.

Can I request a connection and a signature simultaneously?
Yes, you can use the 'Connect to wallet and sign' method to combine these steps. This is efficient for workflows where user authentication immediately requires a signature, reducing the number of modal pop-ups a user sees.

How do I switch between connected wallets?
To switch wallets, you must first programmatically disconnect the current wallet session using the disconnect function. This clears the active session, allowing the user to initiate a new connection and choose a different wallet.