Integrating Web3 functionality into your decentralized application (DApp) has never been easier. This comprehensive guide walks you through the process of connecting your app or Telegram Mini App to Starknet using a universal provider SDK. Whether you're building a decentralized exchange (DEX), NFT marketplace, or blockchain game, this step-by-step documentation ensures seamless wallet connectivity and transaction handling.
Install and Initialize the SDK
Before integrating, ensure your environment supports the latest Web3 standards. While no direct npm installation commands are provided here, developers should reference official repositories for up-to-date package management instructions.
To begin, create an instance of the universal provider — this object will serve as the foundation for all subsequent interactions, including wallet connection, transaction signing, and account management.
Request Parameters
dappMetaData –
Objectname–string: The display name of your application. This is not used as a unique identifier.icon–string: A URL pointing to your app’s icon in PNG or ICO format. SVG is not supported. For optimal rendering, use a 180x180px PNG image.
Returns
OKXUniversalProvider: The main interface object used to interact with the user's wallet.
👉 Get started with secure, seamless Web3 integration today.
Connect Wallet to Your Application
Establishing a connection allows your DApp to access the user's wallet address — essential for identity verification and transaction authorization on Starknet.
Request Parameters
connectParams –
ConnectParamsnamespaces–{[namespace: string]: ConnectNamespace}
Required namespaces for connection. For Starknet, use"starknet"as the key. Currently onlystarknet:mainnetis supported. If any requested chain isn't supported by the wallet, the connection will be rejected.chains:string[]– List of chain IDs.defaultChain?:string– Optional default chain for the session.
optionalNamespaces–{[namespace: string]: ConnectNamespace}
Additional namespaces that can be connected even if some chains aren't supported.chains:string[]defaultChain?:string
sessionConfig–objectredirect:string– Redirect URL after successful connection. For Telegram Mini Apps, use deep links liketg://resolve.
Returns
A Promise resolving to:
topic:string– Unique session identifier.namespaces:Record<string, SessionNamespace>– Active namespace details.chains:string[]– Connected chain IDs.accounts:string[]– List of connected wallet addresses.methods:string[]– Supported methods in the current namespace.defaultChain?:string– Default chain for the session.sessionConfig?:SessionConfig– Session configuration data.dappInfo:objectname:stringicon:stringredirect?:string
✅ Pro Tip: Always validate the returned chains and methods to ensure compatibility before proceeding with transactions.
Prepare Transactions on Starknet
After establishing a connection, instantiate the Starknet-specific provider using the universal provider object:
const starknetProvider = new OKXStarknetProvider(universalProvider);This enables Starknet-native operations such as querying balances, estimating fees, and preparing contract calls.
Retrieve Account Information
Fetch critical user data such as wallet address and public key for authentication or UI personalization.
Request Parameters
chainId:string– Target blockchain, e.g.,starknet:mainnet.
Returns
Objectaddress:string– User’s wallet address.pubKey:string– Associated public key (if available).
👉 Unlock advanced Starknet capabilities with one integration.
Sign Messages Securely
Enable users to authenticate actions or prove ownership without initiating a transaction.
Request Parameters
signerAddress:string– The wallet address initiating the signature.typedData:object– Structured message following Starknet’s typed data format.chain?:string– Optional chain identifier where the action applies.
Returns
- Promise resolving to
[r: string, s: string]– Signature components in hexadecimal format.
🔐 Security Note: Never transmit private keys. Signing occurs securely within the user’s wallet environment.
Sign and Broadcast Transactions
Execute on-chain actions such as token transfers, swaps, or smart contract interactions.
Request Parameters
signerAddress:string– Wallet initiating the transaction.transaction:object– Formatted transaction payload compatible with Starknet.chainId?:string– Chain where the transaction should be executed.
Returns
- Promise resolving to
string– The resulting transaction hash (TxHash),可用于 tracking confirmation status.
✅ Once broadcasted, monitor the transaction via Starknet explorers using the returned hash.
Disconnect Wallet
Terminate the active session cleanly to support multi-wallet switching or logout functionality.
await provider.disconnect();🔄 Best Practice: Always disconnect before attempting to reconnect with a different wallet to avoid session conflicts.
Event Handling
The provider emits real-time events for key lifecycle changes:
'connect': Fired when wallet connects successfully.'disconnect': Triggered upon session termination.'accountsChanged': Notifies when user switches accounts.'chainChanged': Indicates a change in the active network.
Subscribe using standard event listeners:
provider.on('accountsChanged', (accounts) => {
console.log('New accounts:', accounts);
});Error Codes and Troubleshooting
Common exceptions during connection, signing, or disconnection:
| Code | Description |
|---|---|
| OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR | An unforeseen error occurred |
| OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR | Attempted duplicate connection |
| OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR | Operation requires active connection |
| OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR | User denied request |
| OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED | Requested method not available |
| OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED | Chain not supported by wallet |
| OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED | Incompatible wallet type |
| OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR | Network or handshake failure |
Handle these gracefully in your UI to improve user experience.
Frequently Asked Questions (FAQ)
Q: What chains does this SDK support?
A: Currently, only Starknet Mainnet (starknet:mainnet) is supported. Testnet support may vary — check documentation updates regularly.
Q: Can I integrate this into a Telegram Mini App?
A: Yes! Use the redirect parameter in sessionConfig with Telegram deep links like tg://resolve for smooth post-connection navigation.
Q: Is SVG icon supported for dappMetaData?
A: No. Only PNG and ICO formats are accepted. Use a 180x180px PNG for best results.
Q: How do I handle user rejection during connection?
A: Catch the USER_REJECTS_ERROR code and prompt users with clear instructions on how to retry.
Q: Can I switch networks after connecting?
A: Yes, listen for the 'chainChanged' event and update your app state accordingly. Ensure your DApp supports dynamic chain switching.
Q: Where can I find full API references and examples?
A: While external links are removed per guidelines, refer to official SDK repositories and developer portals for sample projects and detailed specs.
Core Keywords
- Starknet integration
- Web3 wallet connection
- DApp SDK
- Connect Wallet API
- Transaction signing
- Message signing
- Decentralized app development
- OKX Connect
With robust error handling, real-time event support, and straightforward initialization, this SDK streamlines Web3 adoption for developers building on Starknet. Whether you're launching a DEX or embedding wallet features into a Mini App, the tools are now at your fingertips.