The OKX Injected Provider API for Bitcoin Testnet provides a powerful JavaScript interface that allows decentralized applications (DApps) to interact seamlessly with the OKX Wallet browser extension. It enables developers to request user account information, read on-chain data, and facilitate the signing of messages and transactions, all within a secure, testnet environment.
This guide offers a comprehensive overview of the key methods available in the API, complete with parameter descriptions, return values, and practical usage notes to help you integrate Bitcoin-based functionality into your DApps.
Core API Methods
The API is accessed via the global okxwallet.bitcoinTestnet object once a user has the OKX Wallet extension installed. The following methods are available.
Connecting to a Wallet
Before you can read any data or request signatures, your DApp must establish a connection to the user's wallet.
Method: okxwallet.bitcoinTestnet.connect()
Description:
This asynchronous method prompts the user to connect their OKX Wallet to your DApp. It must be called from a user interaction, such as a button click, to comply with modern browser security policies.
Parameters:
None.
Return Value:
A Promise that resolves to an object containing the user's public address and key.
address: (string) The Bitcoin testnet address of the currently connected account.publicKey: (string) The public key associated with the connected account.
Example Usage:
// Example within an async function
const connectWallet = async () => {
try {
const account = await okxwallet.bitcoinTestnet.connect();
console.log('Connected Address:', account.address);
console.log('Public Key:', account.publicKey);
} catch (error) {
console.error('Connection failed:', error);
}
};
// Call this function from a button click eventSigning a Message
Message signing is a fundamental operation for verifying ownership of an address without conducting a transaction.
Method: okxwallet.bitcoinTestnet.signMessage(signStr[, type])
Description:
This method requests the user's signature for an arbitrary string of data using their private key.
Parameters:
signStr: (string) The plain text or hexadecimal string that requires a signature.type: (string, optional) The signing algorithm to use. The default is"ecdsa". The alternative is"bip322-simple", which implements a newer standard for Bitcoin message signing.
Return Value:
A Promise that resolves to a string, which is the cryptographic signature of the provided message.
Example Usage:
const message = "Hello, Bitcoin Testnet!";
const signature = await okxwallet.bitcoinTestnet.signMessage(message, "bip322-simple");
// The signature can now be verified off-chainSigning a PSBT (Partially Signed Bitcoin Transaction)
PSBTs are a standard format for collaboratively creating and signing Bitcoin transactions. This method allows your DApp to request signatures for inputs that belong to the connected wallet.
Method: okxwallet.bitcoinTestnet.signPsbt(psbtHex[, options])
Description:
This method signs a PSBT. By default, it will automatically find and sign all inputs within the transaction that correspond to the current connected address. For more granular control, you can specify exactly which inputs to sign using the options parameter.
Parameters:
psbtHex: (string) The hexadecimal string representation of the PSBT that needs to be signed.options: (object, optional) An object for advanced signing configuration.autoFinalized: (boolean) Whether to finalize the PSBT after signing. Finalization scripts the input and prepares it for broadcast. Default istrue.toSignInputs: (array) An array of objects specifying which inputs to sign, useful for complex transactions with multiple participants.index: (number) The index number of the input to sign.addressorpublicKey: (string) Specify either the address or the public key that corresponds to the private key needed for signing. You must provide at least one.sighashTypes: (number[], optional) An array of Sighash flags to use.disableTweakSigner: (boolean, optional) For Taproot addresses, the signer is "tweaked" by default. Set this totrueto sign with the original private key.
Important Note for Taproot:
If any input in your PSBT uses a Taproot address, you must include the corresponding public key for every input in the PSBT data structure before passing it to this method.
Return Value:
A Promise that resolves to a string, which is the hex of the fully or partially signed PSBT (depending on the autoFinalized option).
Example Usage:
const psbtHex = "70736274ff01009a..."; // Your PSBT hex
const options = {
autoFinalized: true,
toSignInputs: [
{ index: 0, address: "tb1q...abc", sighashTypes: [1] }
]
};
const signedPsbtHex = await okxwallet.bitcoinTestnet.signPsbt(psbtHex, options);
// The signed PSBT is ready to be broadcast to the network
👉 [Explore advanced PSBT signing strategies](https://www.okx.com/join/BLOCKSTAR)Signing Multiple PSBTs
For applications that require batching, such as processing multiple orders in a decentralized exchange, you can sign several PSBTs at once.
Method: okxwallet.bitcoinTestnet.signPsbts(psbtHexs[, options])
Description:
This method functions identically to signPsbt, but operates on an array of PSBT hex strings. This is more efficient than making multiple individual calls.
Parameters:
psbtHexs: (string[]) An array of PSBT hex strings.options: (object[], optional) An array of option objects. Each object in the array corresponds to the PSBT at the same index inpsbtHexsand uses the same properties as the options forsignPsbt.
Return Value:
A Promise that resolves to an array of strings, where each string is the hex of a signed PSBT.
Example Usage:
const psbtArray = [psbtHex1, psbtHex2, psbtHex3];
const signedPsbtArray = await okxwallet.bitcoinTestnet.signPsbts(psbtArray);
// signedPsbtArray now contains three signed PSBTsFrequently Asked Questions
What is the difference between the mainnet and testnet provider?
The testnet provider (okxwallet.bitcoinTestnet) connects to Bitcoin test networks (like testnet3), which use valueless coins for development and testing. The mainnet provider (typically okxwallet.bitcoin) interacts with the real Bitcoin blockchain. Always use the testnet API during development to avoid losing real funds.
Why is my connect() call being rejected?
Modern browsers require calls that prompt the user (like wallet connection) to be triggered directly by a user gesture, such as a click. Ensure your connect() function is called from a onClick event handler and not automatically on page load.
How do I handle errors from the API?
All API methods return a Promise. Always use try/catch blocks when calling them. Common errors include the user rejecting the connection/signing request, being on the wrong network, or providing invalid parameters (like a malformed PSBT).
What is the practical use of message signing?
Signing a message cryptographically proves that the holder of a specific private key (and therefore the owner of an address) approved a message. This is used for authentication, verifying ownership without a transaction, and signing off-chain data for layer-2 protocols.
When should I use the toSignInputs option?
Use toSignInputs when you need explicit control over the signing process. This is crucial if the PSBT contains inputs from multiple parties, and you only want the user to sign specific inputs that belong to them, rather than having the wallet auto-sign every eligible input.
Can I use this API for other Bitcoin-compatible chains?
The OKX Injected Provider API is designed specifically for the Bitcoin blockchain and its testnets. For other Bitcoin-derived chains (e.g., Litecoin, Bitcoin Cash), you would need to check if OKX provides a separate dedicated provider API for those networks.
👉 Get detailed guidance on wallet integration