Integrating BTC Connect within a web application.
@particle-network/btc-connectkit
) acts as the sole library for integrating BTC Connect, facilitating wallet connection (through the aforementioned unified modal), smart account assignment and interaction, native Bitcoin transactions, etc.
In this page, you’ll find a complete rundown of what you need to know when using @particle-network/btc-connectkit
.
@particle-network/btc-connectkit
, and can be installed through either of the two following commands:
projectId
, clientKey
, and appId
.
These are used primarily to authenticate API requests and tie your project to the Particle dashboard, allowing you to track users, spin up RPC endpoints, fund your Paymaster for gasless transactions, and so on.
@particle-network/btc-connectkit
, you’ll need to configure and initialize it through the ConnectProvider
object. ConnectProvider
should, like AuthCoreContextProvider
from Particle Auth Core, wrap your primary App
either directly within its JSX or through your index
file. Essentially, ConnectProvider
controls the EVM chains you’d like to support, the wallets available through the connection modal, and other core configurations required to initialize BTC Connect. ConnectProvider
takes the following within its options
parameter:
projectId
, previously retrieved from the Particle dashboard.clientKey
, previously retrieved from the Particle dashboard.appId
, previously retrieved from the Particle dashboard.aaOptions
, an object containing:
accountContracts
, which should be another object with:
BTC
, an array of objects that take:
chainIds
, an array of chain IDs representing the blockchains you intend to use within your application (these chains are also supported within @particle-network/chains
, in which you can export dedicated objects containing the chain ID, such as PolygonMumbai.id
).version
, which dictates the smart account version you’d like to use. Currently, both 1.0.0
and 2.0.0
are supported, depending on the chain (chainIds
) you define. 2.0.0
is a newer implementation with better gas optimizations.walletOptions
, an optional object containing:
visible
, a Boolean determining whether or not the Particle Wallet modal is shown after connection. In this case, the wallet modal can be used to control the smart account, although if you intend to implement equivalent functionality within your application, such as user-defined transactions, you may not need this.options
parameter (which expects the above values), you’ll also need to define connectors
, an object containing an array of wallet connector instances imported from @particle-network/btc-connectkit
, such as:
UnisatConnector
OKXConnector
BitgetConnector
TokenPocketConnector
BybitConnector
WizzConnector
XverseConnector
ConnectProvider
within a standard index
file setup, following the structure covered above:
@particle-network/btc-connectkit
) for functions such as facilitating wallet connection, using the smart account, sending BTC, etc. Below, we’ll review the four primary hooks within BTC Connect.
useConnectModal
(for wallet connection)connectors
parameter within ConnectProvider
. useConnectModal
exposes two functions for this:
openConnectModal
. This will open the aforementioned modal immediately upon being called.disconnect
. Similarly, disconnect
will reset the wallet/account state (log a user out). See the snippet below for an example of defining and using these functions from useConnectModal
:openConnectModal
, the user will be presented with a menu that looks like the following (deviating depending only on connectors
from ConnectProvider
).
useAccounts
(and associated address retrieval methods)useAccounts
or useBTCProvider
, and:useETHProvider
with account
.useAccounts
and useBTCProvider
both expose accounts
, an array of connected Bitcoin addresses (which will change based on whether a user is connected to the Livenet or Testnet). Additionally, useETHProvider
has account
, a string representing the associated smart account address.
Below is an example of defining each of these variables:
useBTCProvider
(for native Bitcoin functions)useBTCProvider
acts as the primary hook allowing to sign messages, send transactions, and retrieve additional wallet information (such as the network, public key, etc.) with the user’s native Bitcoin account. Confirmations will be routed through the same wallet as useETHProvider
, but these transactions will be executed on either the Bitcoin Livenet or Testnet. useBTCProvider
has the following functions:
getNetwork
, for retrieving the current network of the wallet (Livenet or Testnet).switchNetwork
, to forcibly switch the network. Takes a string, either ‘livenet’ or ‘testnet’.signMessage
, to request that a user signs a message. Takes any string (the message to be signed).getPublicKey
, for retrieving the public key of the wallet.sendBitcoin
, for sending a standard Bitcoin transaction. This function takes the following:
toAddress
, the recipient of the transaction.satoshis
, the value of the transaction in satoshis.options
, an optional object containing:
feeRate
, for adjusting transaction fees.useBTCProvider
has been included below:
useETHProvider
(for controlling the associated smart account)useETHProvider
acts as the single mechanism for driving interaction through the associated EVM smart account. Interaction is driven through one of two ways:
buildUserOp
and sendUserOp
, which will mimic similar functions found within Particle Network’s AA SDK for managing transactions.provider
object, enabling utilization of the smart account through a standard Web3 library such as Ethers, Web3.js, viem, etc.useETHProvider
:
chainId
, the ID for the currently connected chain.
account
, the smart account address (automatically populated upon login).getSmartAccountInfo
, get smart account info(version, isDeployed, etc.).switchChain
, for forcibly changing the EVM chain used through the smart account. This takes a specific chainId
(should be one of the aforementioned supported chains).provider
, the EIP-1193 provider object associated with the smart account.getFeeQuotes
, for retrieving fee quotes (a collection of UserOperation structures based upon different fee payment mechanisms); this is equivalent to getFeeQuotes.buildUserOp
, to build a execution-ready UserOperation with a standard transaction object.sendUserOp
, for sending UserOperations (either objects derived from getFeeQuotes
/buildUserOp
, or standard transaction objects).publicClient
, the viem PublicClient
object for making standard JSON-RPC requests.useAccount
, useETHProvider
, useBTCProvider
, and useConnectModal
, below is a table containing every relevant one alongside specific parameters and a short description. For methods listed that weren’t covered in the above examples, live implementation often mimics the common structure covered throughout this document.
Hook | Function | Parameters (* indicates optional) |
---|---|---|
useConnectModal | openConnectModal | N/A |
useConnectModal | disconnect | N/A |
useAccounts | accounts | N/A |
useBTCProvider | provider | N/A |
useBTCProvider | accounts | N/A |
useBTCProvider | getPublicKey | N/A |
useBTCProvider | signMessage | message: string |
useBTCProvider | getNetwork | N/A |
useBTCProvider | switchNetwork | network: ‘livenet’ | ‘testnet’ |
useBTCProvider | sendBitcoin | toAddress: string, satoshis: number, options*: {feeRate: number} |
useETHProvider | account | N/A |
useETHProvider | getSmartAccountInfo | N/A |
useETHProvider | provider | N/A |
useETHProvider | switchChain | chainId: number |
useETHProvider | chainId | N/A |
useETHProvider | getFeeQuotes | tx: Transaction | Transaction[] |
useETHProvider | buildUserOp | { tx: Transaction | Transaction\[], feeQuote: FeeQuote, tokenPaymasterAddress: string } |
useETHProvider | sendUserOp | params: SendTransactionParams, forceHideConfirmModal?: boolean |
useETHProvider | publicClient | N/A |