This guide walks you through the fundamental steps of interacting with the Bitcoin blockchain using a REST API. You will learn how to create a wallet, generate addresses and private keys, check balances, and transfer funds. All examples are based on the Bitcoin Testnet, a safe environment for development and testing.
Understanding Bitcoin Wallets and Keys
A Bitcoin wallet is built upon a mnemonic phrase—a 24-word sequence that acts as a master key. From this mnemonic, you can generate all your wallet addresses and their corresponding private keys. It is crucial to keep this mnemonic and any derived private keys secure, as they control access to your funds.
👉 Explore secure wallet management strategies
Generating a Mnemonic and XPUB
The first step is to generate a mnemonic and an extended public key (XPUB). The XPUB allows you to generate a virtually unlimited number of public addresses without exposing the private keys.
Here is an example API request to generate them:
curl --location 'https://api.tatum.io/v3/bitcoin/wallet' \
--header 'x-api-key: {YOUR_API_KEY}'A successful response will return both the mnemonic and the XPUB.
{
"mnemonic": "pull leader deputy custom invest hat panel behind reward fancy tribe valley elite wish mistake letter bounce sing anchor electric #### #### #### ####",
"xpub": "tpubDFRDRgtnYJcXdhC4eE1HktF86nLwLodEopxvmAePWyZPXR6zGnu5XtQ2S4TBjHgF6rPnxGdJ8MinjYKAGqoumF4L9TL8wMJJoAGW1XR####"
}Deriving a Private Key
With a mnemonic and a specific derivation index, you can generate the private key for a particular address. The index is a number that specifies which key in the sequence you want.
Example Request:
curl --location 'https://api.tatum.io/v3/bitcoin/wallet/priv' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
"index": 1,
"mnemonic": "pull leader deputy custom invest hat panel behind reward fancy tribe valley elite wish mistake letter bounce sing anchor electric #### #### #### ####"
}'The response will contain the private key for the address at index 1.
Generating a Public Address
Similarly, you can generate a public Bitcoin address from the XPUB by specifying an index. This address is what you share to receive funds.
Example Request:
curl --location 'https://api.tatum.io/v3/bitcoin/address/tpubDFRDRgtnYJcXdhC4eE1HktF86nLwLodEopxvmAePWyZPXR6zGnu5XtQ2S4TBjHgF6rPnxGdJ8MinjYKAGqoumF4L9TL8wMJJoAGW1XR####/1' \
--header 'x-api-key: {YOUR_API_KEY}'The response provides the public address.
{
"address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma"
}Funding Your Testnet Address
To perform transactions, you need Bitcoin. On the testnet, you can acquire free test coins from a faucet. Use the address generated in the previous step to receive these funds.
Checking Your Address Balance
Before making a transaction, it's wise to check your balance, which is calculated from Unspent Transaction Outputs (UTXOs). UTXOs are chunks of bitcoin that have been sent to your address but not yet spent.
Example Request:
curl --location 'https://api.tatum.io/v3/bitcoin/address/balance/tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma' \
--header 'x-api-key: {YOUR_API_KEY}'The response shows the incoming, outgoing, and pending balances.
{
"incoming": "0.00828",
"outgoing": "0",
"incomingPending": "0.00008",
"outgoingPending": "0"
}Preparing a Transaction: Fetching UTXOs
To build a transaction, you need to specify which UTXOs you will use as inputs. It is critical to validate that these UTXOs are still unspent.
Example Request:
This request fetches UTXOs from a specific address that sum to at least the value you want to send.
curl --location 'https://api.tatum.io/v4/data/utxos?chain=bitcoin-testnet&address=tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma&totalValue=0.002' \
--header 'x-api-key: {YOUR_API_KEY}'The response is an array of available UTXOs.
Estimating the Transaction Fee
Bitcoin transactions require a fee paid to miners. This fee fluctuates based on network congestion and the size of your transaction in bytes. It's essential to get an estimate to ensure your transaction is processed.
Example Request:
curl --location 'https://api.tatum.io/v3/blockchain/estimate' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
"chain": "BTC",
"type": "TRANSFER",
"fromUTXO": [
{
"txHash": "b041ef2fa3f39a095784ca0e37d2ee9c6fe08c1026702bebd57eadd3cfc88c5e",
"index": 0
},
{
"txHash": "71c8c90c87e6e268741b4989c497adbccb1a24c405603fdf396dbba503252304",
"index": 0
},
{
"txHash": "8159a453cb2914479b2ae8bf13d9109798581301194ccf69b51fae2814580c3b",
"index": 0
}
],
"to": [
{
"address": "tb1qguyupqrsd36c0fta99rf6prxe2lfr73ahxkvpf",
"value": 0.00042
}
]
}'The response provides fee estimates for slow, medium, and fast processing times.
Broadcasting the Transaction
Once you have your UTXOs and a fee estimate, you can construct and broadcast the transaction. You must provide the private keys for each UTXO you are spending.
Transaction Variant 1: Explicit Fee
This method explicitly states the fee and a change address where any leftover bitcoin from the UTXOs will be sent.
Example Request:
curl --location 'https://api.tatum.io/v3/bitcoin/transaction' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
"fromUTXO": [
{
"txHash": "b041ef2fa3f39a095784ca0e37d2ee9c6fe08c1026702bebd57eadd3cfc88c5e",
"index": 0,
"privateKey": "####"
},
{
"txHash": "71c8c90c87e6e268741b4989c497adbccb1a24c405603fdf396dbba503252304",
"index": 0,
"privateKey": "####"
},
{
"txHash": "8159a453cb2914479b2ae8bf13d9109798581301194ccf69b51fae2814580c3b",
"index": 0,
"privateKey": "####"
}
],
"to": [
{
"value": 0.00042,
"address": "tb1qguyupqrsd36c0fta99rf6prxe2lfr73ahxkvpf"
}
],
"fee": "0.0009945",
"changeAddress": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma"
}'The response is a transaction ID (txId) confirming the broadcast.
Transaction Variant 2: Implicit Fee
This method involves specifying two outputs: one for the recipient and one for your change. The fee is implicitly calculated as the total input value minus the total output value.
Example Request:
curl --location 'https://api.tatum.io/v3/bitcoin/transaction' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
"fromUTXO": [
{
"txHash": "63b02f60968800202ee211ac14520e51b4b2e25335cf0523fee38beb1b154395",
"index": 1,
"privateKey": "####"
}
],
"to": [
{
"value": 0.0001,
"address": "tb1qguyupqrsd36c0fta99rf6prxe2lfr73ahxkvpf"
},
{
"value": 0.0065,
"address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma"
}
]
}'Checking Transaction Status
After broadcasting, you can check the status of your transaction by querying its hash.
Example Request:
curl --location 'https://api.tatum.io/v3/bitcoin/transaction/63b02f60968800202ee211ac14520e51b4b2e25335cf0523fee38beb1b154395' \
--header 'x-api-key: {YOUR_API_KEY}'A response containing block information confirms the transaction is mined. If it's still in the mempool, it may not return data or show a block number.
Important Considerations for Bitcoin Transactions
- Transaction Fees: Fees on the testnet can be highly volatile and unreliable because testnet coins have no real value. On the mainnet, fees are more predictable.
- Stuck Transactions: A transaction with too low a fee can get stuck in the mempool for up to two weeks. Techniques like Child-Pays-For-Parent (CPFP) can help speed up confirmation.
- Security: Always use the correct derivation path consistent with your wallet setup. Never share your API key, mnemonic, or private keys.
👉 Learn advanced techniques for transaction management
Frequently Asked Questions
What is a Bitcoin Testnet?
The Bitcoin Testnet is a parallel blockchain to Bitcoin Mainnet. It is used by developers for testing applications without using real, valuable bitcoin. The coins on testnet are free and have no monetary value.
What is a UTXO?
An Unspent Transaction Output (UTXO) is a technical term for a discrete piece of bitcoin that has been sent to an address and can be spent as an input in a new transaction. Think of them as digital coins and notes that make up your wallet's balance.
Why is my transaction not confirming?
A transaction may not confirm if the network fee attached to it is too low relative to current network demand. Miners prioritize transactions with higher fees. If stuck, you may need to wait or use a method like CPFP to increase the fee.
How do I keep my keys secure?
Your mnemonic and private keys are the keys to your funds. Store them offline in a secure location, such as a hardware wallet or a written paper stored in a safe. Never digitally store them in plaintext on an internet-connected device.
What is the difference between an XPUB and an address?
An extended public key (XPUB) can generate a sequence of many public addresses. While you share individual addresses to receive funds, you can share an XPUB to allow someone to see all incoming transactions to your wallet without granting spending privileges.
Can I use these API calls on the Bitcoin Mainnet?
Yes, the same API endpoints work for the Bitcoin Mainnet. However, you must use a mainnet-enabled API key and remember that transactions on mainnet involve real bitcoin with monetary value. Always test thoroughly on testnet first.