The Injected Provider API is a powerful JavaScript interface that enables decentralized applications (DApps) to interact seamlessly with browser extension wallets. When a user visits your website with a compatible wallet installed, this API is injected into the page, allowing your application to request user accounts, read on-chain data, and facilitate the signing of messages and transactions.
This guide provides a comprehensive overview of utilizing this API for Solana-based development, covering connection management, transaction handling, message signing, and event listening.
Core Concepts and Initial Setup
Before integrating, ensure your development environment is prepared. You will need a basic understanding of JavaScript and the Solana blockchain. The API is accessed through the window.okxwallet.solana object, which becomes available when a user has the wallet extension installed and active.
The primary purpose of the API is to act as a bridge between your web application and the user's wallet, enabling secure and permissioned interactions without exposing private keys.
Establishing a Connection to a Wallet
The first step in integration is establishing a connection between your DApp and the user's wallet.
How to Initiate a Connection
You can request a connection by calling window.okxwallet.solana.connect(). This method returns a Promise, which is a fundamental JavaScript object used for handling asynchronous operations.
This Promise will resolve if the user approves the connection request. Upon resolution, your application gains the ability to read the public key of the connected account. If the user rejects the request or closes the prompt, the Promise will be rejected, and your application should handle this gracefully.
// Example connection handler
async function connectWallet() {
try {
const response = await window.okxwallet.solana.connect();
console.log('Connected with Public Key:', response.publicKey.toString());
} catch (err) {
console.error('Connection failed:', err);
}
}Once connected, the wallet will also emit a connect event, which you can listen for to update your application's UI state. A convenient isConnected method is also exposed for checking the current connection status.
Handling Transactions: Signing and Sending
Interacting with the blockchain often requires creating and sending transactions. The Provider API offers methods for both signing and sending transactions directly, or just signing them for later submission.
Signing and Sending a Transaction
For transactions you wish to immediately send to the network, use the signAndSendTransaction method. When called, the wallet will prompt the user to approve the transaction. If accepted, the wallet uses the user's private key to sign it and subsequently submits it to the Solana network via a JSON RPC connection.
This method returns a Promise that resolves with the signature of the submitted transaction.
Signing a Transaction Without Sending
Some applications require a signed transaction without immediately broadcasting it. The signTransaction method fulfills this need. It prompts the user for approval and returns a Promise that resolves with the signed transaction object.
Your application can then submit this signed transaction at a later time using the sendRawTransaction method from @solana/web3.js.
Processing Multiple Transactions
For complex operations requiring multiple transactions, you can use the signAllTransactions method. This allows users to sign several transactions in a single batch, improving the user experience for multi-step processes.
👉 Explore more strategies for batch transaction handling
Message Signing for Authentication
Beyond transactions, the API allows DApps to request message signatures. This is a cost-free operation (no gas fees) and is commonly used for off-chain authentication and to verify that a user controls a specific address.
To request a signature, your application must provide the message encoded as a Uint8Array, which can be derived from either a UTF-8 string or a hexadecimal string. The wallet will display this message to the user for approval before signing.
// Example: Requesting a message signature
const message = new TextEncoder().encode('Your application-specific authentication message');
const signedMessage = await window.okxwallet.solana.signMessage(message);Listening for Wallet Events
A robust DApp responds to changes in the wallet's state. The Provider API emits events that your application can listen for, ensuring a dynamic user experience.
The Connect Event
This event is emitted when the wallet becomes connected to your site, typically after a user approves a connection request. You can listen for this event to update your UI accordingly.
The Disconnect Event
This event is emitted when the wallet disconnects from your DApp. Disconnection can be initiated either by your application or by the user directly within their wallet. Your application should listen for this event to reset its state.
The AccountChanged Event
Users often manage multiple accounts. When a user switches their active account within their wallet, an accountChanged event is emitted. The event may include the public key of the new account if it has already whitelisted your application.
If the new account is not whitelisted, your application may need to request a new connection. It is crucial to handle this event to ensure the UI always reflects the currently active account.
// Example: Listening for account changes
window.okxwallet.solana.on('accountChanged', (publicKey) => {
if (publicKey) {
// Update the UI to reflect the new active account
console.log('Switched to account:', publicKey.toString());
} else {
// The user switched to an account that hasn't been connected
connectWallet(); // Attempt to reconnect
}
});Frequently Asked Questions
What is the Injected Provider API?
The Injected Provider API is a JavaScript interface made available by browser extension wallets. It allows web applications to securely request blockchain operations—like reading data or signing transactions—directly from the user's wallet, facilitating a seamless DApp experience without compromising private key security.
How do I check if a user has a compatible wallet installed?
You can check for the existence of the window.okxwallet and window.okxwallet.solana objects. If they are undefined, it indicates the wallet extension is not installed, and you should guide the user to install it.
What is the difference between signTransaction and signAndSendTransaction?
The signTransaction method only requests a user's signature and returns the signed transaction for your application to handle. Conversely, signAndSendTransaction handles the entire process: it requests the signature and immediately sends the signed transaction to the Solana network on your behalf.
Why would my application need to sign a message?
Message signing is a fundamental tool for authentication. By signing a unique message, a user cryptographically proves ownership of their wallet address without incurring any transaction fees. This is commonly used for logging into services or verifying identity off-chain.
How should my DApp handle a user switching accounts?
Your application should listen for the accountChanged event. When triggered, update your UI to reflect the new active account's public key. If the event returns a null value, it may mean the new account hasn't connected to your DApp, prompting you to request a new connection.
What are some common errors during connection?
Common errors include the user rejecting the connection request, the wallet not being installed, or the pop-up window being closed before confirmation. Your code should use try/catch blocks around API calls to gracefully handle these rejections and inform the user.