Skip to main content

ICP BTC developer workflow

Advanced
Bitcoin

Developers on ICP can create canisters and dapps that interact directly with the Bitcoin mainnet and testnet networks through ICP's direct integration with Bitcoin. To use this integration, developers must implement a specific workflow to prepare transactions and submit them to the Bitcoin network. Developers can also integrate and interact with chain-key Bitcoin (ckBTC) from within a canister, which uses the ICRC-1 token implementation.

Using the Bitcoin integration​

To interact with the Bitcoin testnet or mainnet networks, a developer needs to use both the management canister and Bitcoin integration API to complete the following steps:

  1. Generate a Bitcoin address: To receive BTC, your canister must generate a Bitcoin address using the ecdsa_public_key API endpoint of the management canister.

The Bitcoin Testnet API is currently disabled and the ckTestBTC minter canister has been stopped. This is temporary and they will be re-enabled in the future.

Learn more.

  1. Create a Bitcoin transaction: If the canister controls BTC, it can create a transaction to spend them.

  2. Sign a transaction: Next, the transaction must be signed with tECDSA using the sign_with_ecdsa API endpoint of the management canister. Transactions cannot be sent to the Bitcoin network until they are signed.

  3. Submit a transaction: Once a transaction has been signed, it can be submitted to the Bitcoin network to be executed using the Bitcoin API's bitcoin_send_transaction endpoint, which must specify a blob of a Bitcoin transaction and a Bitcoin network (mainnet or testnet).

  4. Read information from the Bitcoin network: Lastly, you can query and return information from the Bitcoin network, such as unspent transaction outputs (UTXOs) of a Bitcoin address, the balance of a Bitcoin address, and the percentiles of the fees for the last 10_000 transactions. The endpoints for each query can be found in the Bitcoin API specification.

Each of these API endpoints can be executed programmatically within a smart contract that is deployed on ICP. View the documentation for each workflow step to see code examples for interacting with each API endpoint.

Working with Bitcoin data structures like addresses, UTXOs and transactions can be cumbersome. The good news is that popular libraries like rust-bitcoin and bitcoinjs-lib can be used within canisters.

Using a local instance of the Bitcoin testnet​

You can also develop and test your canister against a local instance of the Bitcoin testnet running in your developer environment. Learn more in the Bitcoin developing locally documentation.

Using ckBTC​

Chain-key Bitcoin (ckBTC) is a digital twin token of Bitcoin that is backed 1:1 with Bitcoin held within an ICP smart contract. ckBTC tokens comply with the ICRC token standard.

ckBTC and other chain-key tokens can be interacted with in the same manner as other ICRC tokens. There aren't any special workflow steps, parameters, or smart contract types that must be used to integrate with chain-key tokens such as ckBTC.

Learn more about ckBTC.

Next steps​