Skip to main content

Reading the Bitcoin state

Advanced
Bitcoin
Tutorial

To read information from the Bitcoin network's state, the Bitcoin integration API exposes the following methods:

  • bitcoin_get_utxos: Returns the unspent transaction outputs (UTXOs) of a Bitcoin address.

  • bitcoin_get_balance: Returns the balance of a Bitcoin address.

  • bitcoin_get_current_fee_percentiles: Returns the percentiles of the fees for the last 10_000 transactions. Returns the fee in millisatoshi per virtual byte.

  • bitcoin_get_block_headers: Returns the block headers within a provided range of start height and end height (optional) for the specified Bitcoin network (testnet or mainnet).

Standard Bitcoin addresses (P2PKH, P2SH, P2WPKH, etc.) are supported.

To test canisters locally that use the following code snippets, you will need to enable local Bitcoin development. To do this, you can either start the local replica with dfx start --enable-bitcoin or you can include the following configuration in the project's dfx.json file:

motoko/basic_bitcoin/dfx.json
loading...

Learn more about dfx.json configuration options.

Bitcoin networks​

Both the Bitcoin testnet and mainnet networks are supported. The network can be specified as a parameter in each function.

API costs​

Each call to the API has a cost of cycles; therefore, a sufficient amount of cycles must be sent with each call.

Cycles costs will vary between the Bitcoin testnet and mainnet. For a breakdown of the costs, see Bitcoin API costs.

Reading unspent transaction outputs​

To read unspent transaction outputs from the Bitcoin network, make a call to the bitcoin_get_utxos Bitcoin API method. You can create a function in your canister to call this method, such as:

motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinApi.mo
loading...

Then make a call to this canister's function with the command:

dfx canister --network ic call CANISTER_NAME get_utxos '("ADDRESS")'

Replace CANISTER_NAME with your canister's name and replace ADDRESS with your Bitcoin address. Learn more about Bitcoin addresses.

Reading current balance​

To read the current balance of a Bitcoin address, make a call to the bitcoin_get_balance Bitcoin API method. You can create a function in your canister to call this method, such as:

motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinApi.mo
loading...

Then make a call to this canister's function with the command:

dfx canister --network ic call CANISTER_NAME get_balance '("ADDRESS")'

Replace CANISTER_NAME with your canister's name and replace ADDRESS with your Bitcoin address. Learn more about Bitcoin addresses.

Reading the fee percentile​

The transaction fees in the Bitcoin network change dynamically based on the number of pending transactions. In order to get fee percentiles for the last few blocks (4 - 10), call bitcoin_get_current_fee_percentiles.

The function returns 101 numbers that are fees measured in millisatoshi per virtual byte. The i-th element of the result corresponds to the i-th percentile fee. For example, to get the median fee over the last few blocks, look at the 50-th element of the result.

motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinApi.mo
loading...

Then make a call to this canister's function with the command:

dfx canister --network ic call CANISTER_NAME get_current_fee_percentiles

Replace CANISTER_NAME with your canister's name.

Resources​