The Injected Provider API is a powerful JavaScript-based interface that enables seamless interaction between decentralized applications (DApps) and Bitcoin wallets. When integrated into a website, it allows DApps to request user account information, read data from connected blockchains, and facilitate message and transaction signing. This functionality is essential for creating a smooth user experience in the Web3 ecosystem.
Core Concepts of the Provider API
An Injected Provider API acts as a bridge between a DApp and a user's cryptocurrency wallet. It is typically embedded by wallet providers into websites, allowing for direct communication without requiring users to expose their private keys. This model supports critical operations such as authentication, data querying, and transaction authorization.
For developers, understanding this API is key to building applications that can interact with the Bitcoin blockchain. It provides a standardized set of methods that abstract away the complexities of direct blockchain interaction, making it easier to focus on application logic.
Essential API Methods for Wallet Connection
Establishing a Connection
The connect() method initiates the connection between the DApp and the user's wallet. It returns a promise that resolves to an object containing the user's address and public key. This is often the first step in the user interaction flow.
const accountInfo = await okxwallet.bitcoin.connect();Requesting and Retrieving Accounts
The requestAccounts() method prompts the user to connect their current account to the DApp. This method requires user consent and is part of the permission system that protects user privacy.
For simply retrieving already-connected accounts without prompting the user, getAccounts() returns the currently connected account addresses.
Network and Account Information Methods
Checking Network Status
The getNetwork() method returns information about which Bitcoin network the wallet is currently connected to. Note that this feature is only available in certain versions of wallet implementations and may not support test networks.
Accessing Public Keys and Balances
The getPublicKey() method retrieves the public key of the currently connected account, which is essential for various cryptographic operations.
For checking token balances, getBalance() returns an object containing confirmed, unconfirmed, and total satoshi amounts. This method requires specific minimum wallet versions to function properly.
Transaction Methods
Sending Bitcoin
The API provides multiple methods for sending Bitcoin, each with different capabilities:
sendBitcoin(toAddress, satoshis, options)for basic Bitcoin transferssend({from, to, value, satBytes, memo, memoPos})for transfers with additional memo support
The latter method allows including OP_RETURN data, which can be used for adding arbitrary information to transactions, such as payment references or simple messages.
Handling Inscriptions and NFTs
For the growing ecosystem of Bitcoin-based digital artifacts, the API offers:
getInscriptions()to retrieve a list of inscriptions associated with an accountsendInscription(address, inscriptionId, options)for transferring individual inscriptionstransferNft({from, to, data})for batch transfers of multiple NFTs
These methods support popular protocols including Ordinals and Atomicals, though protocol support may vary between mobile and extension versions.
Advanced Transaction Features
Message Signing
The signMessage(signStr[, type]) method allows users to cryptographically sign messages using their private keys. This functionality supports both "ecdsa" and "bip322-simple" signature types, with version requirements for the latter.
PSBT (Partially Signed Bitcoin Transactions) Handling
For more complex transaction scenarios, the API provides comprehensive PSBT support:
signPsbt(psbtHex[, options])for signing individual PSBTssignPsbts(psbtHexs[, options])for batch signing multiple PSBTspushPsbt(psbtHex)andsendPsbt(txs, from)for broadcasting signed transactions
These methods include advanced options for customizing signing behavior, with different default settings across wallet versions.
UTXO Management and Inscription Creation
UTXO Splitting
The splitUtxo({from, amount}) method helps users manage their Unspent Transaction Outputs (UTXOs), which is particularly important for certain signing algorithms that require specific UTXO structures.
Creating Inscriptions
For users looking to create their own inscriptions, the API offers:
inscribe({type, from, tick, tid})for creating transferable BRC-20 tokensmint({type, from, inscriptions})for general ordinal inscriptions including images and text
These advanced features enable the creation of various digital artifacts on the Bitcoin blockchain, with detailed information returned about commit and reveal transactions.
Event Handling
The API supports event listeners for account changes:
accountChangedevents notify when users switch between accountsaccountsChangedevents trigger when exposed account addresses change
These events allow DApps to dynamically update their interface in response to user actions.
👉 Explore advanced integration techniques
Frequently Asked Questions
What is the difference between requestAccounts and getAccounts?
RequestAccounts prompts the user for connection permission, while getAccounts simply retrieves already-connected accounts without user interaction. Use requestAccounts when initially connecting a wallet and getAccounts for subsequent interactions.
Which Bitcoin protocols does the API support?
The API currently supports Ordinals and Atomicals protocols for NFT and inscription operations. However, protocol support may vary between mobile and extension versions, so developers should check version requirements.
How does PSBT signing work with different wallet versions?
Older wallet versions have different default behaviors for PSBT signing, particularly regarding autoFinalization. Newer versions support more options and default to auto-finalizing transactions after signing.
What are the version requirements for balance checking?
The getBalance method requires mobile version 6.51.0 or higher and extension version 2.77.1 or higher. Earlier versions may not support this functionality.
Can I add memos to Bitcoin transactions?
Yes, the send method supports adding memos through the memo parameter, which creates OP_RETURN outputs. You must also specify the output position using memoPos for the memo to be included.
How do I handle account change events?
Listen for accountChanged or accountsChanged events to detect when users switch accounts. This allows your DApp to update its state accordingly and ensure it's interacting with the currently active account.