SDK | Starknet | Connect to App or Mini Wallet | DEX API Wallet Integration Guide

Integrating a crypto wallet into your decentralized application (DApp) is a critical step in delivering a seamless Web3 experience. With growing adoption of the Starknet ecosystem, developers are increasingly looking for reliable, secure, and user-friendly ways to connect wallets—especially within mini-app environments like Telegram. This guide walks you through the complete integration process using the OKX Connect SDK, focusing on Starknet compatibility, secure transaction handling, and smooth user onboarding.

Whether you're building a decentralized exchange (DEX), NFT marketplace, or blockchain gaming platform, this documentation ensures your app supports essential wallet functions such as connection, signing, transaction submission, and session management—all while maintaining optimal performance and security.

Installation and Initialization

Before integrating wallet connectivity into your DApp, ensure your development environment supports OKX Connect SDK version 6.98.0 or later. You can install it via npm:

npm install okx-connect

Once installed, initialize the SDK by creating an OKXUniversalProvider instance. This object serves as the foundation for all subsequent interactions, including wallet connection, transaction signing, and account management.

Request Parameters

• dappMetaData – Object

  • name: String – The display name of your application. This does not need to be unique.
  • icon: String – A URL pointing to your app’s icon in PNG or ICO format. SVG files are not supported. For best results, use a 180x180px PNG image.

Returns

• OKXUniversalProvider – The core provider object used for all wallet operations.

👉 Get started with seamless wallet integration for your Starknet DApp today.

Connecting to a Wallet

To interact with a user’s wallet, you must first establish a secure connection. This process retrieves essential data such as the wallet address, supported methods, and chain information.

Request Parameters

• connectParams – ConnectParams

  • namespaces – [namespace: string]: ConnectNamespace
    Required namespace information. For Starknet, use 'starknet'. Currently, only starknet:mainnet is supported. If the requested chain isn’t supported by the wallet, the connection will be rejected.

    • chains: string[] – List of chain IDs (e.g., ["starknet:mainnet"])
    • defaultChain?: string – Optional default chain ID

  • optionalNamespaces – [namespace: string]: ConnectNamespace
    Additional namespaces that are not mandatory. If the wallet doesn’t support them, the connection still proceeds.

    • chains: string[]
    • defaultChain?: string

  • sessionConfig: Object

    • redirect: string – Redirect URL after successful connection. For Telegram mini apps, use 'tg://resolve'.

Return Value

• Promise resolving to:

  • topic: string – Unique session identifier
  • namespaces: Record<string, any> – Connected namespace details
  • chains: string[] – Active chain IDs
  • accounts: string[] – Connected wallet addresses
  • methods: string[] – Supported RPC methods (e.g., starknet_signTransaction)
  • defaultChain?: string – Default chain for the session
  • sessionConfig?: SessionConfig – Session-specific settings

  • dappInfo: Object

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

Prepare the Transaction

Before sending any transaction, instantiate the OKXStarknetProvider using the previously created OKXUniversalProvider. This prepares your app to handle Starknet-specific operations such as contract calls and token transfers.

This provider enables interaction with Starknet's JSON-RPC endpoints and ensures proper formatting of transaction payloads according to Cairo standards.

Get Account Information

Retrieve the connected user’s wallet details for display or verification purposes.

Request Parameters

• chainId: string – Target chain (e.g., starknet:mainnet)

Return Value

• Object

  • address: string – User’s wallet address
  • pubKey: string – Public key associated with the wallet

This data is crucial for personalizing user experiences and validating ownership before sensitive operations.

Sign the Message

Securely authenticate users by requesting a digital signature on a structured message. This is commonly used for login systems or proof-of-ownership checks.

Request Parameters

• signerAddress: string – Wallet address initiating the signature
• typedData: object – Message in a predefined format (e.g., JSON structure compliant with Starknet standards)
• chain?: string – Optional chain context for the operation

Return Value

• Promise resolving to [r: string, s: string] – Signature components in hexadecimal format

Message signing enhances security without requiring gas fees, making it ideal for lightweight authentication flows.

Send Transaction

Submit a signed transaction to the Starknet network, such as token swaps, NFT mints, or contract interactions.

Request Parameters

• signerAddress: string – Address sending the transaction
• transaction: object – Formatted transaction payload (includes contract address, entry point, calldata, etc.)
• chainId?: string – Chain identifier (defaults to current session chain)

Return Value

• Promise resolving to string – Transaction hash (tx_hash)

After submission, monitor the transaction status using Starknet explorers or built-in event listeners.

👉 Unlock advanced wallet features and boost DApp engagement now.

Disconnect Wallet

Terminate the active session and disconnect the wallet. This clears local session data and prepares the interface for reconnection—essential when allowing users to switch accounts.

Note: Always disconnect the current wallet before attempting to connect a new one to avoid conflicts.

Event Handling

The SDK emits real-time events during key actions:

• session_update – Triggered when session data changes (e.g., chain switch)
• chain_changed – Fired when the active chain is updated
• accounts_changed – Emitted when the connected account list changes
• disconnect – Sent when the user manually disconnects or session expires

Listening to these events ensures your UI stays synchronized with the wallet state.

Error Codes

Handle exceptions gracefully by referencing standardized error codes returned by the SDK.

Common Error Codes

• OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR – An unexpected error occurred
• OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR – Wallet is already connected
• OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR – No active wallet session
• OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR – User denied the request
• OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED – Requested method is unavailable
• OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED – Chain not supported by wallet
• OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED – Wallet type incompatible
• OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR – Failed to establish connection

Implementing proper error handling improves user trust and reduces friction during onboarding.

👉 Simplify Web3 integration with powerful tools built for developers.

Frequently Asked Questions (FAQ)

Q: Which chains are currently supported by OKX Connect for Starknet?
A: As of now, only starknet:mainnet is officially supported. Testnet environments may be added in future updates.

Q: Can I integrate this SDK into a Telegram mini app?
A: Yes. Use the redirect: 'tg://resolve' parameter in sessionConfig to enable smooth post-connection redirection within Telegram.

Q: Is SVG icon format supported during initialization?
A: No. Only PNG and ICO formats are accepted. Use a 180x180px PNG for optimal display.

Q: What happens if a user rejects a transaction request?
A: The SDK returns the USER_REJECTS_ERROR code. Your app should catch this and prompt the user accordingly without retrying automatically.

Q: How do I handle chain switching after connection?
A: Listen for the chain_changed event and update your app’s context accordingly. Ensure requested chains are included in optionalNamespaces.

Q: Can multiple wallets be connected simultaneously?
A: No. Only one wallet session can be active at a time. Always disconnect before initiating a new connection.

By following this guide, developers can efficiently integrate secure, high-performance wallet connectivity into their Starknet-based applications. From initialization to transaction execution and error handling, every step is designed to enhance usability and reliability in modern Web3 environments.

Core Keywords: Starknet, wallet integration, DEX API, OKX Connect SDK, connect wallet, send transaction, sign message, Web3 development