SDK | Cosmos | Connect App or Mini Wallet | Web3 Wallet Integration | DEX API Guide

Integrating Web3 functionality into your decentralized application (DApp) has never been easier. With the OKX Connect SDK, developers can seamlessly connect their apps or mini-wallets to the Cosmos ecosystem, enabling smooth wallet connectivity, transaction signing, and real-time account interactions. This comprehensive guide walks you through every step of integrating and utilizing the SDK for Cosmos-based applications.

Whether you're building a DEX, a cross-chain bridge, or a Web3-powered social platform, understanding how to properly initialize, connect, and manage user wallets is essential. Below, we break down each key function with clear explanations, request parameters, return values, and practical examples.

Installation and Initialization

Before diving into wallet connectivity, ensure your environment is set up correctly. To begin integration, update your project to version 6.94.0 or later and install the OKX Connect SDK via npm:

npm install okx-connect

Once installed, create an instance of OKXUniversalProvider—this object will serve as the foundation for all subsequent operations such as connecting wallets, sending transactions, and handling events.

Request Parameters

• dappMetaData – Object
  Metadata about your DApp:

  • name: string – The name of your application (not used as a unique identifier).
  • icon: string – URL to your app’s icon in PNG or ICO format (SVG not supported). Ideally, use a 180x180px image for optimal display.

Return Value

• OKXUniversalProvider – A provider instance used throughout the connection lifecycle.

👉 Get started with seamless Web3 integration today

Connect Wallet

Establishing a secure connection with a user's wallet is the first step toward enabling blockchain interactions. This method retrieves the wallet address—essential for identification and transaction signing.

Request Parameters

• connectParams – ConnectParams

  • namespaces – [string: ConnectNamespace]
    Required namespace(s) to connect. For Cosmos chains, use "cosmos". If any requested chain isn't supported by the wallet, the connection will be rejected.

    • chains: string[] – Array of chain IDs (e.g., ["cosmos:cosmoshub-4", "cosmos:osmosis-1"])
    • defaultChain?: string – Optional default chain ID
  • optionalNamespaces – [string: ConnectNamespace]
    Additional namespaces that are not mandatory. Connection proceeds even if these aren't fully supported.

  • sessionConfig – object

    • redirect: string – Redirect URL after successful connection. For Telegram Mini Apps, use deep links like tg://resolve.

Return Value

A Promise resolving to an object containing:

• topic: string – Session identifier
• namespaces: Record<string, Namespace> – Connected namespace details
• chains: string[] – List of connected chains
• accounts: string[] – Connected wallet addresses
• methods: string[] – Supported methods in the current namespace
• defaultChain?: string – Default chain for the session
• sessionConfig?: SessionConfig – Session configuration

• dappInfo: object

  • name: string
  • icon: string
  • redirect?: string – Post-connection redirect parameter

👉 Unlock full Web3 capabilities in your app now

Check Wallet Connection Status

Determine whether a wallet is currently connected to your DApp. This helps manage UI states and prevent unauthorized actions.

Return Value

• boolean – Returns true if connected; otherwise false.

Prepare Transaction

To interact with Cosmos chains, instantiate an OKXCosmosProvider using the previously created OKXUniversalProvider. This prepares your app for signing and broadcasting transactions on supported networks.

Get Account Information

Retrieve detailed account data from the connected wallet for a specific chain.

Request Parameter

• chainId: string – Chain identifier (e.g., cosmos:cosmoshub-4, cosmos:osmosis-1)

Return Value

An object containing:

• algo: "secp256k1" – Signing algorithm
• address: string – Wallet address
• bech32Address: string – Bech32-encoded address
• pubKey: Uint8Array – Public key bytes

Sign Message

Allow users to sign arbitrary messages—useful for authentication or off-chain verification.

Request Parameters

• chain: string – Target chain for signing
• signerAddress: string – Address of the signing wallet
• message: string – Message to be signed

Return Value

A Promise resolving to:

• pub_key:

  • type: string – Public key type (e.g., "tendermint/PubKeySecp256k1")
  • value: string – Base64-encoded public key
• signature: string – Base64-encoded signature

Sign Transaction: signAmino

Sign transactions using the Amino encoding format, widely used across Cosmos SDK chains.

Request Parameters

• chainId: string – Target chain ID (required)
• signerAddress: string – Wallet address
• signDoc: object – Transaction payload structured per Cosmos Amino standards (matches OfflineSigner.signAmino format)

Return Value

A Promise resolving to:

• signed: object – Signed transaction data
• signature: object – Signature details

Sign Transaction: signDirect

Use Protobuf-based signing for improved efficiency and security on modern Cosmos chains.

Request Parameters

• chainId: string – Chain ID (required)
• signerAddress: string – Wallet address

• signDoc: object

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

Return Value

A Promise resolving to:

• signed: object – Signed transaction
• signature: object – Signature output

Disconnect Wallet

Terminate the active session and disconnect the connected wallet. Always call this before attempting to switch accounts or reconnect.

await provider.disconnect();

This removes all session data and ensures clean state management.

Event Handling

The SDK supports real-time event listening for improved user experience:

• connect: Triggered upon successful connection
• disconnect: Fired when the user disconnects
• chainChanged: Emitted when the active chain changes
• accountsChanged: Notifies when the connected account(s) change

Use these events to dynamically update your app interface.

Error Codes

Common exceptions during connection, signing, or disconnection processes:

• OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR – Unknown internal error
• OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR – Wallet already connected
• OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR – No active connection found
• OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR – User denied request
• OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED – Requested method not available
• OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED – Chain not supported by wallet
• OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED – Incompatible wallet detected
• OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR – General connection failure

Handle these gracefully to improve UX and reduce friction.

Frequently Asked Questions

Q: What Cosmos chains are supported?
A: The SDK supports major Cosmos chains including Cosmos Hub (cosmoshub-4) and Osmosis (osmosis-1). Always verify chain IDs before requesting connections.

Q: Can I integrate this into a Telegram Mini App?
A: Yes. Use the redirect parameter in sessionConfig with Telegram deep links like tg://resolve for seamless redirection post-connection.

Q: Is SVG icon support available for DApp metadata?
A: No. Only PNG and ICO formats are currently supported. Use a 180x180px PNG for best results.

Q: How do I handle user rejection during connection?
A: Catch the USER_REJECTS_ERROR code and prompt the user again with clearer instructions or retry options.

Q: What’s the difference between signAmino and signDirect?
A: signAmino uses JSON-based encoding and is compatible with older Cosmos SDK versions. signDirect uses Protobuf for faster, more secure signing on newer chains.

Q: Can multiple wallets be connected simultaneously?
A: No. Only one active session is allowed at a time. Disconnect the current wallet before initiating a new connection.

By following this guide, you can confidently integrate Web3 capabilities into your application using the OKX Connect SDK. From initialization to secure transaction signing, each step is designed to streamline development while maintaining robust security and user control.

👉 Start building powerful Web3 experiences now