This guide provides a comprehensive overview of integrating OKX Connect into your Cosmos-based decentralized applications (DApps). Learn how to connect wallets, sign transactions, and manage user sessions effectively.
Getting Started with OKX Connect
OKX Connect enables seamless integration between your DApp and OKX wallets, providing users with a smooth experience for connecting their wallets and signing transactions.
Before you begin, ensure you have updated the OKX App to version 6.94.0 or later. Integration can be easily accomplished using npm or other standard package managers.
Initialization and Setup
Proper initialization is crucial for establishing communication between your DApp and wallet interface.
Request Parameters
dappMetaData - object
- name - string: Your application's name (not used as a unique identifier)
- icon - string: URL to your application icon (must be PNG or ICO format; SVG is not supported). Recommended size is 180x180 pixels.
actionsConfiguration - object
- modals - ('before' | 'success' | 'error')[] | 'all': Controls alert displays during transactions (defaults to 'before')
- returnStrategy - string: For app wallet, specifies deep link return behavior after user signs/rejects requests
- tmaReturnUrl - string: For Telegram Mini Wallet, specifies deep link return policy
uiPreferences - object
- theme - Options: THEME.DARK, THEME.LIGHT, or 'SYSTEM'
- language - Supported languages include en_US, zh_CN, and many others (defaults to en_US)
Return Value
- OKXUniversalConnectUI object
👉 Explore more setup strategies
Establishing Wallet Connections
Connecting to a wallet retrieves the wallet address and necessary parameters for signing transactions.
Request Parameters
connectParams - ConnectParams
- namespaces - Required connection information with 'cosmos' as the key for Cosmos chains
- chains: string[]: Chain ID information
- defaultChain?: string: Optional default chain
- optionalNamespaces - Optional connection information
sessionConfig: object
- redirect: string: Redirect parameter after successful connection
Return Value
- Promise containing session identifier, namespace information, chain data, accounts, supported methods, and default chain information
Connection with Signature Requests
This method connects to the wallet and simultaneously requests data signing, with results returned via the 'connect_signResponse' event.
Request Parameters
- connectParams - ConnectParams (as above)
signRequest - RequestParams[]: Method to request connection and signing (supports one method at a time)
- method: string: Requested method name (Cosmos supports 'cosmos_signArbitrary')
- chainId: string: Chain ID where method executes
- params: Parameters corresponding to the requested method
Return Value
- Promise containing session information and connection data
Connection Status Checking
Determine whether a wallet is currently connected to your DApp.
Return Value
- boolean indicating connection status
Transaction Preparation
Before executing transactions, create an OKXCosmosProvider object by passing OKXUniversalConnectUI to the constructor.
Retrieving Account Information
Obtain detailed information about connected wallet accounts.
Request Parameters
- chainId: string: Requested chain (e.g., cosmos:cosmoshub-4, cosmos:osmosis-1)
Return Value
Object containing:
- algo: 'secp256k1'
- address: string wallet address
- bech32Address: string wallet address
- pubKey: Uint8Array public key
Message Signing
Request signature of specific messages from the connected wallet.
Request Parameters
- chain - string: Execution chain
- signerAddress - string: Signature wallet address
- message - string: Message to be signed
Return Value
Promise - object containing:
- pub_key: object with type and value
- signature: string signature result
SignAmino Method
Sign transactions using the Amino format, similar to cosmjs OfflineSigner's signAmino method.
Request Parameters
- chainId - string: Chain for signature execution (required)
- signerAddress - string: Wallet address
- signDoc - object: Transaction information in fixed format
Return Value
Promise - Object containing:
- signed: object with transaction information
- signature: object with signature result
SignDirect Method
Sign transactions using the Direct protocol buffer format.
Request Parameters
- chainId - string: Chain for signature execution (required)
- signerAddress - string: Wallet address
signDoc - object: Transaction data containing:
- bodyBytes, Uint8Array
- authInfoBytes, Uint8Array
- chainId, string
- accountNumber, string
Return Value
Promise - Object containing:
- signed: object with transaction information
- signature: object with signature result
Managing Wallet Connections
Disconnect the current wallet and delete the active session. Always disconnect the current wallet before attempting to switch to a different wallet connection.
👉 Get advanced connection methods
Event Handling
The integration includes various events that help manage the connection lifecycle, transaction status, and error handling.
Error Code Reference
Understanding potential exceptions helps in building robust error handling for your DApp.
Common Error Codes
| Error Code | Description |
|---|---|
| UNKNOWN_ERROR | Unknown or unexpected error |
| ALREADY_CONNECTED_ERROR | Wallet connection already established |
| NOT_CONNECTED_ERROR | No active wallet connection |
| USER_REJECTS_ERROR | User rejected the request |
| METHOD_NOT_SUPPORTED | Requested method not supported |
| CHAIN_NOT_SUPPORTED | Specified chain not supported |
| WALLET_NOT_SUPPORTED | Wallet type not supported |
| CONNECTION_ERROR | General connection error |
Frequently Asked Questions
What are the minimum requirements for integrating OKX Connect?
You need to update the OKX App to version 6.94.0 or later. The integration can be implemented using standard package managers like npm, and your DApp should support standard web3 protocols for Cosmos blockchain interactions.
How do I handle different blockchain networks within Cosmos?
Specify the chain IDs in your connection parameters (e.g., cosmos:cosmoshub-4 for Cosmos Hub or cosmos:osmosis-1 for Osmosis). The wallet will validate whether the requested chains are supported before establishing connection.
What should I do if users reject connection requests?
Implement proper error handling for the USER_REJECTS_ERROR code. Provide clear messaging explaining why wallet connection is necessary and guide users through the process if they change their mind.
Can I customize the UI theme and language preferences?
Yes, OKX Connect allows you to set UI preferences including theme (dark, light, or system default) and language support for multiple regions including en_US, zh_CN, and many others.
How do I switch between different wallet connections?
Always disconnect the current wallet session first using the disconnect method before attempting to establish a new connection. This ensures clean session management and prevents connection conflicts.
What's the difference between SignAmino and SignDirect methods?
SignAmino uses the Amino encoding format which is more human-readable, while SignDirect uses protocol buffer format which is more efficient. Choose based on your specific use case and compatibility requirements with your Cosmos DApp.