UI | Cosmos | Connect to App or Mini Wallet | Wallet Integration | DEX API Guide

Integrating a secure and seamless wallet connection into your decentralized application (DApp) is essential for delivering a superior user experience. With the OKX Connect SDK, developers can easily implement wallet connectivity for both standalone apps and Telegram Mini Wallets, supporting multiple blockchain ecosystems including Cosmos and EVM-compatible chains.

This comprehensive guide walks you through the complete integration process—from initialization to transaction signing—with clear examples, best practices, and critical error handling insights.

Installation and Initialization

To begin integrating OKX Connect, ensure the OKX App is updated to version 6.94.0 or later. Integration can be performed using npm:

npm install okx-connect

Before establishing a wallet connection, initialize the OKXUniversalConnectUI object. This object enables UI rendering for key actions such as connecting wallets and signing transactions.

Request Parameters

• dappMetaData – Object

  • name: Application name (non-unique identifier).
  • icon: URL of the app icon in PNG or ICO format. SVG is not supported. Recommended size: 180x180px.

• actionsConfiguration – Object

  • modals: Display behavior for transaction alerts. Options: 'before', 'success', 'error', or 'all'. Default: 'before'.
  • returnStrategy: Deep link return strategy after user signs/rejects. For Telegram apps: tg://resolve.
  • tmaReturnUrl: Return policy for Telegram Mini Wallet. Options: 'back', 'none', or custom deep link. Default: 'back'.

• uiPreferences – Object

  • theme: UI theme. Options: THEME.DARK, THEME.LIGHT, or 'SYSTEM'.
• language: Supported languages include 'en_US', 'zh_CN', 'es_ES', 'fr_FR', 'de_DE', 'ja_JP', 'ru_RU', 'ar_AE', and more. Default: 'en_US'.

👉 Discover how to seamlessly embed wallet connectivity into your DApp today.

Return Value

• OKXUniversalConnectUI: The core interface object used for all subsequent wallet interactions.

Connect to a Wallet

Establish a secure connection to retrieve the user’s wallet address and enable transaction signing capabilities.

Request Parameters

• connectParams – ConnectParams

  • namespaces: Required chain namespaces. Use 'eip155' for EVM chains and 'cosmos' for Cosmos-based chains. If any requested chain isn’t supported, the wallet will reject the connection.

    • chains: Array of chain IDs (e.g., ["cosmos:cosmoshub-4"]).
    • defaultChain: Optional default chain ID.

  • optionalNamespaces: Additional namespaces. Connection proceeds even if these aren’t supported.

    • Same structure as namespaces.

  • sessionConfig:

    • redirect: Deep link to redirect after successful connection (e.g., tg://resolve for Telegram Mini Apps).

Return Value

Returns a Promise resolving to:

• topic: Session identifier.
• namespaces: Active namespace mappings.
• chains: Connected chain IDs.
• accounts: User wallet addresses.
• methods: Supported methods (e.g., cosmos_signArbitrary).
• defaultChain: Default chain for the session.
• dappInfo: App metadata (name, icon, redirect).

Connect and Sign in One Step

Streamline user onboarding by connecting the wallet and requesting a signature simultaneously—ideal for authentication flows.

Request Parameters

Includes all parameters from Connect to Wallet, plus:

• signRequest – RequestParams[] (max one method at a time)

  • method: Signing method. For Cosmos: 'cosmos_signArbitrary'.
  • chainId: Chain where the method executes (must be in declared namespaces).
  • params: Method-specific parameters (object or array).

The result is delivered via the 'connect_signResponse' event.

Return Value

Same as standard connection, with added assurance that signing was initiated during handshake.

👉 Learn how one-click sign-in boosts user retention in Web3 apps.

Check Wallet Connection Status

Determine whether a wallet is currently connected.

Return Value

• boolean: true if connected; otherwise, false.

Use this to conditionally render UI elements like "Connect Wallet" buttons or balance displays.

Prepare Transactions with OKXCosmosProvider

Before sending transactions, instantiate the OKXCosmosProvider using the initialized OKXUniversalConnectUI:

const provider = new OKXCosmosProvider(okxConnectUI);

This provider enables interaction with Cosmos-based blockchains, including querying balances, building transactions, and submitting them.

Retrieve Account Information

Fetch public wallet details for a specific Cosmos chain.

Request Parameters

• chainId: Target chain (e.g., cosmos:cosmoshub-4, cosmos:osmosis-1).

Return Value

Returns an object containing:

• algo: Signature algorithm (secp256k1).
• address: Wallet address (Bech32 format).
• bech32Address: Redundant field—same as address.
• pubKey: Public key as a Uint8Array.

This data is essential for constructing signed transactions or verifying ownership.

Sign Arbitrary Messages

Authenticate users by signing plaintext messages—commonly used for login systems.

Request Parameters

• chain: Target blockchain (e.g., 'cosmos').
• signerAddress: User’s wallet address.
• message: String message to sign.

Return Value

Promise resolving to:

• pub_key:

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

Use this for secure off-chain authentication without exposing private keys.

Sign Using Amino Encoding

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

Request Parameters

• chainId: Chain ID (required).
• signerAddress: Wallet address.

• signDoc: Structured transaction data matching Cosmos SDK’s Amino format:

  {
    "chain_id": "cosmoshub-4",
    "account_number": "12345",
    "sequence": "0",
    "fee": { ... },
    "msgs": [ ... ],
    "memo": ""
  }

⚠️ Note: The signDoc must follow strict Amino formatting rules.

Return Value

• signed: Serialized transaction bytes.
• signature: Signature object containing signature and public key.

Ideal for compatibility with older Cosmos clients and exchanges.

Sign Using Direct Mode (Protobuf)

Leverage modern Protobuf-based signing for improved efficiency and security.

Request Parameters

• chainId: Target chain ID.
• signerAddress: User’s address.

• signDoc: Binary transaction data:

  • bodyBytes: Transaction body in protobuf format.
  • authInfoBytes: Authorization info (fees, signers).
  • chainId and accountNumber: As strings.

Return Value

Same as Amino: signed transaction and signature object.

Direct mode reduces parsing overhead and is recommended for new DApps.

Disconnect Wallet

Terminate the active session and disconnect the wallet.

await okxConnectUI.disconnect();

Always disconnect before attempting to reconnect or switch accounts—this ensures clean session management and avoids conflicts.

Event Handling

Monitor key events during the connection lifecycle:

• 'connect_signResponse': Returns signature result after connect-and-sign flow.
• 'session_update': Triggered when session data changes.
• 'disconnect': Emitted when user disconnects manually or session expires.

Proper event listening enhances UX by providing real-time feedback.

Error Codes and Troubleshooting

Handle exceptions gracefully using standardized error codes:

Log these errors for debugging and display user-friendly messages in your UI.

Frequently Asked Questions

How do I support multiple languages in my DApp?

Set the language field during initialization. Supported values include 'en_US', 'zh_CN', 'es_ES', and others. The SDK will render prompts in the selected language.

Can I use SVG icons for my app?

No. Only PNG and ICO formats are supported. Use a 180x180px PNG for optimal display quality.

What is the difference between Amino and Direct signing?

Amino uses JSON-based encoding and is widely compatible. Direct mode uses Protobuf for smaller payloads and better performance—preferred for modern apps.

Is Telegram Mini Wallet supported?

Yes. Use the tmaReturnUrl parameter to control navigation after signing. Set to 'back' to return to the chat, or 'none' to stay in place.

How do I handle unsupported chains?

Use optionalNamespaces for non-critical chains. If those aren’t supported, the connection still proceeds—unlike with required namespaces.

Can I connect to non-Cosmos chains?

Yes. Use 'eip155' namespace for Ethereum and EVM-compatible chains like BSC, Polygon, etc.

👉 Start building with full Cosmos and EVM support now—explore OKX Connect.