UI Integration Guide: Connecting to Cosmos App or Mini Wallet with API DEX Documentation

Installation and Initialization

Ensure your OKX App is updated to version 6.94.0 or later to integrate OKX Connect into your DApp. Use npm for seamless installation:

npm install okx-connect

Configuration Parameters

dappMetaData (object):
- name: Your application name (non-unique identifier).
- icon: URL to a 180x180px PNG icon (SVG unsupported).
actionsConfiguration (object):
- modals: Alert display modes during transactions ('before', 'success', 'error', or 'all').
- returnStrategy: Deep-link return strategy (e.g., 'none' or tg://resolve for Telegram Mini Wallet).
uiPreferences (object):
- theme: Choose THEME.DARK, THEME.LIGHT, or 'SYSTEM'.
language: Defaults to en_US; supports multiple locales like zh_CN, es_ES, etc.

Returns:
OKXUniversalConnectUI instance.

Example

const connectUI = new OKXUniversalConnectUI({
  dappMetaData: { name: "MyDApp", icon: "https://example.com/icon.png" },
  theme: THEME.DARK
});

Connecting to a Wallet

Establish a connection to fetch wallet addresses and transaction-signing parameters.

Request Parameters

connectParams (ConnectParams):
- namespaces: Chain namespace (e.g., 'cosmos' for Cosmos networks).
- chains: Array of supported chain IDs (e.g., cosmos:cosmoshub-4).
- sessionConfig.redirect: Post-connection redirect URL (e.g., tg://resolve for Telegram).

Returns:

topic: Session identifier.
accounts: Connected wallet addresses.
methods: Supported wallet methods (e.g., cosmos_signArbitrary).

Example

const session = await connectUI.connect({
  namespaces: { cosmos: { chains: ["cosmos:osmosis-1"] } },
  sessionConfig: { redirect: "tg://resolve" }
});

Wallet Connection and Data Signing

Connect and sign data in one step. Results are returned via the connect_signResponse event.

Request Parameters

signRequest (array):
- method: Supported method (e.g., cosmos_signArbitrary).
- chainId: Target chain ID.
- params: Method-specific parameters.

Returns:
Signed data with pub_key and signature.

Example

const result = await connectUI.connectAndSign({
  connectParams: { chains: ["cosmos:cosmoshub-4"] },
  signRequest: [{ method: "cosmos_signArbitrary", chainId: "cosmos:cosmoshub-4" }]
});

Key Wallet Actions

Check Connection Status

const isConnected = connectUI.isConnected(); // Returns boolean

Account Information

Parameters:

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

Returns:

address: Bech32 wallet address.
pubKey: Public key in Uint8Array format.

Signing Transactions

SignAmino: For Amino-encoded transactions.
SignDirect: For Protobuf-encoded transactions.

Parameters:

signerAddress: Wallet address.
signDoc: Transaction data (format varies by method).

Disconnecting the Wallet

await connectUI.disconnect(); // Clears active session

Error Handling

Error Code	Description
`ALREADY_CONNECTED_ERROR`	Wallet is already connected.
`METHOD_NOT_SUPPORTED`	Unsupported signing method.
`USER_REJECTS_ERROR`	User declined the request.

FAQ Section

How do I handle unsupported chains?

Ensure requested chains are listed in optionalNamespaces to allow partial connectivity.

Can I customize the connection UI?

Yes, configure uiPreferences.theme and dappMetaData.icon for branding.

What’s the difference between SignAmino and SignDirect?

SignAmino uses Amino encoding, while SignDirect uses Protobuf for finer control.

👉 Explore Advanced Wallet Integration
👉 Cosmos SDK Documentation

For further details, refer to the official OKX Connect API documentation.