Integrating a secure and seamless wallet connection into your decentralized application (DApp) is essential for delivering a smooth user experience. With the OKX Connect SDK, developers can easily enable wallet connectivity for both EVM and Aptos-based blockchains. This guide walks you through the full integration process—from initialization to transaction signing—while ensuring compatibility with mini wallets and web3 apps.
Whether you're building a decentralized exchange (DEX), a gaming platform, or a DeFi tool, this documentation provides the technical foundation you need to support Aptos and EVM chains using standardized protocols.
Installation and Initialization
To begin integrating OKX Connect into your DApp, ensure your environment supports version 6.92.0 or later of the SDK. You can install it via npm:
npm install okx-connectBefore establishing a wallet connection, initialize the OKXUniversalProvider. This core object enables communication with the wallet, transaction handling, and chain-specific operations.
Request Parameters
dappMetaData – Object containing your app’s details:
name(string): The display name of your DApp. Not used as a unique identifier.icon(string): URL pointing to your app’s icon. Supported formats include PNG and ICO. SVG icons are not supported. For optimal display, use a 180x180px PNG image.
Return Value
OKXUniversalProvider: The primary interface for all subsequent wallet interactions.
👉 Get started with seamless wallet integration today using OKX Connect.
Connecting to a Wallet
Establishing a secure session with a user's wallet allows your DApp to access account information and request transaction signatures. Use the connect method with proper namespace declarations.
Request Parameters
connectParams
namespaces– Required connection info:- Key:
'eip155'for EVM chains,'aptos'for Aptos. chains: Array of chain IDs (e.g.,"aptos:mainnet").defaultChain?: Optional default chain ID.
- Key:
optionalNamespaces– Additional chains that won’t block connection if unsupported.- Same structure as
namespaces.
- Same structure as
sessionConfigredirect: Post-connection redirect URL. For Telegram mini apps, use deep links liketg://resolve.
⚠️ If any required chain in namespaces isn’t supported by the wallet, the connection will be rejected.Return Value
A Promise resolving to an object containing:
topic: Unique session identifier.namespaces: Confirmed namespace details (e.g., EVM or Aptos).chains: Active connected chains.accounts: Array of connected wallet addresses.methods: Supported methods (e.g., signTransaction, signMessage).defaultChain?: Default chain for the session.sessionConfig?: Redirect and other config settings.dappInfo: Your app’s metadata (name,icon,redirect).
Determine if the Wallet is Connected
Check the current connection status before attempting transactions or data retrieval.
Return Value
boolean: Returnstrueif a wallet is currently connected; otherwise,false.
This check helps prevent errors during user interactions and improves UX by conditionally rendering UI elements.
Prepare the Transaction
Before signing, instantiate the OKXAptosProvider using the initialized OKXUniversalProvider. This prepares your app for Aptos-specific operations.
Get Wallet Address and Public Key
Retrieve essential identity data from the connected wallet.
Request Parameters
chain(string): Chain ID to query. If omitted, returns the first connected Aptos address.
Return Value
An object containing:
address(string): The wallet’s public address.publicKey(string): The associated public key for cryptographic verification.
This data is crucial for constructing personalized transactions and verifying ownership.
Sign a Message
Signing messages allows users to authenticate themselves without transferring assets.
Request Parameters
message– Object with:address?: Include wallet address in the message.application?: Include DApp domain.chainId?: Include current chain ID.message: The actual text to sign.nonce: A randomly generated string to prevent replay attacks.
chain(string): Target chain for signing—required when managing multiple chains.
Return Value
A Promise resolving to:
address,application,chainIdfullMessage: Final formatted message sent for signing.message: Original input message.nonceprefix: Always"APTOS"for Aptos chains.signature: Hex-encoded signature string.
👉 Enable secure message signing in your DApp with OKX Connect.
Sign a Single Transaction
Use this method to locally sign a transaction without broadcasting it immediately—ideal for audit workflows or multi-step processes.
Request Parameters
transaction: Transaction object or instance ofSimpleTransaction.chain: Specifies the target blockchain—recommended; mandatory with multi-chain setups.
Return Value
- Promise resolving to a signed transaction buffer (
Buffer).
This output can be passed to another service or stored securely before broadcast.
Sign and Broadcast Transaction On-Chain
For immediate execution, combine signing and broadcasting in one step.
Request Parameters
Same as above:
transactionchain
Return Value
- Promise resolving to the transaction hash (
string) upon successful on-chain submission.
This is ideal for swap executions, NFT mints, or token approvals where instant feedback is expected.
Disconnect Wallet
Terminate the active session cleanly by calling disconnect. This removes session data from both client and wallet sides.
🔁 To switch accounts or wallets, always disconnect first to avoid conflicts.
No parameters required. Simply invoke:
await provider.disconnect();Event Handling
The SDK emits real-time events such as:
'connect''disconnect''accountsChanged''chainChanged'
Subscribe to these events to keep your UI synchronized with wallet state changes.
Example:
provider.on('accountsChanged', (accounts) => {
console.log('Connected accounts:', accounts);
});Error Codes
Handle common exceptions gracefully using standardized error codes.
| Error Code | Description |
|---|---|
| OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR | Unexpected internal error |
| OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR | Attempted duplicate connection |
| OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR | Action requires active session |
| OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR | User denied request |
| OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED | Unsupported operation |
| OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED | Chain not available in wallet |
| OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED | Incompatible wallet type |
| OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR | Network or handshake failure |
Implement error handling middleware to display friendly messages based on these codes.
Frequently Asked Questions
Q: Can I integrate OKX Connect with Telegram mini apps?
A: Yes. Set the redirect field in sessionConfig to a Telegram deep link like tg://resolve for seamless return after connection.
Q: Is SVG icon support available for DApp metadata?
A: No. Only PNG and ICO formats are supported. Use a 180x180px PNG for best results.
Q: What happens if a user rejects a transaction request?
A: The SDK throws USER_REJECTS_ERROR. Catch this in your code to inform users without breaking the app flow.
Q: How do I support multiple chains like Aptos and EVM simultaneously?
A: Define both 'aptos' and 'eip155' in namespaces. Always specify the chain parameter during signing to avoid ambiguity.
Q: Can I reconnect automatically after disconnection?
A: Not automatically. You must re-initiate the connection flow, but you can cache previous settings for faster reconnection.
Q: Are nonce values required when signing messages?
A: Yes. Including a unique nonce prevents replay attacks and is considered a security best practice.
Core Keywords
aptos wallet integration, DEX API documentation, OKX Connect SDK, web3 wallet connection, decentralized app integration, EVM and Aptos support, sign transaction broadcast, wallet connect protocol
👉 Unlock full wallet connectivity for Aptos and EVM apps now.