🥷 Try it live — no local setup. ICP Ninja is a web-based IDE that builds and deploys this project to the mainnet for free, right in your browser. Click the badge above, or hit Deploy if you're already in Ninja. To build and run it locally instead, follow the steps below.
This example demonstrates how a canister can send and receive Bitcoin on the Internet Computer using threshold ECDSA and Schnorr signatures. It covers three address types (P2PKH, P2TR key-path, P2TR script-path), querying balances and UTXOs, reading chain state, and sending transactions.
For a deeper understanding of the ICP ↔ Bitcoin integration, see the Bitcoin integration concepts.
The canister uses three ICP management canister APIs:
- Threshold ECDSA (
ecdsa_public_key,sign_with_ecdsa) — derives P2PKH addresses and signs transactions spending from them - Threshold Schnorr (
schnorr_public_key,sign_with_schnorr) — derives P2TR addresses (BIP340/341) and signs Taproot transactions - Bitcoin canister — queries balances, UTXOs, fee percentiles, and block data; submits signed transactions to the Bitcoin network
The example covers three Bitcoin address types, each backed by a different signing key:
- P2PKH — Pay-to-Public-Key-Hash. Derived from a threshold ECDSA key. The classic Bitcoin address format.
- P2TR key-only — Pay-to-Taproot, key-path spend only. Derived from a threshold Schnorr key with an unspendable script tree. Simpler Taproot: only the internal key can spend.
- P2TR (key + script path) — Pay-to-Taproot with a Merkleized Alternative Script Tree (MAST). Funds can be spent either via the internal key (key path) or via a script that authorizes a second Schnorr public key (script path). Demonstrates BIP341 script-path spending.
- Node.js v18+
- icp-cli:
npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm - ic-mops:
npm install -g ic-mops - Docker (required for local testing — bundles the IC network launcher +
bitcoind)
git clone https://github.com/dfinity/examples
cd examples/motoko/basic_bitcoinThe local environment uses a self-contained Docker image (icp-cli-network-launcher-bitcoin) that runs bitcoind in regtest mode alongside the IC network. Build it once:
./build-image.shThen deploy and run tests:
icp network start -d
icp deploy --cycles 30t
make test
icp network stopIf tests fail with an out-of-cycles error, top up the canister and retry:
icp canister top-up --amount 30t backend
The ic environment deploys to IC mainnet connected to Bitcoin testnet4, using test_key_1:
icp deploy -e ic --cycles 30tTo deploy to Bitcoin mainnet, change the
init_argsfor theicenvironment inicp.yamlfromtestnettomainnet. The canister automatically selectskey_1(the production threshold signing key) when initialized with themainnetvariant.
| Environment | IC network | Bitcoin network | Key |
|---|---|---|---|
local |
local (PocketIC) | regtest | test_key_1 |
ic |
IC mainnet | testnet4 | test_key_1 |
icp canister call backend get_p2pkh_address '()'
icp canister call backend get_p2tr_key_only_address '()'
icp canister call backend get_p2tr_address '()'icp canister call backend get_balance '("YOUR_ADDRESS")'
icp canister call backend get_utxos '("YOUR_ADDRESS")'
icp canister call backend get_current_fee_percentiles '()'
icp canister call backend get_block_headers '(0 : nat32, null)'
icp canister call backend get_blockchain_info '()'icp canister call backend send_from_p2pkh_address \
'(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'
icp canister call backend send_from_p2tr_key_only_address \
'(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'
icp canister call backend send_from_p2tr_address_key_path \
'(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'
icp canister call backend send_from_p2tr_address_script_path \
'(record { destination_address = "DEST"; amount_in_satoshi = 4321 })'# Get a P2PKH address
ADDR=$(icp canister call backend get_p2pkh_address '()' | grep -o '"[^"]*"' | tr -d '"')
# Mine 101 blocks to that address via the bundled bitcoind
CONTAINER=$(docker ps --filter "ancestor=icp-cli-network-launcher-bitcoin" --format "{{.ID}}" | head -1)
docker exec "$CONTAINER" bitcoin-cli -regtest \
-rpcuser=ic-btc-integration -rpcpassword=ic-btc-integration \
generatetoaddress 101 "$ADDR"
# Wait for the IC to sync, then check balance
sleep 5
icp canister call backend get_balance "(\"$ADDR\")"Refer to the security best practices for information on security and best practices for your ICP app.