Docs: Docs HomeSupported NetworksUnified APICovalent NetworkIncrementAPI Reference
APIs used:
  • Get token balances for address  
  • Bitcoin: Get transactions by wallet address  

Perhaps you’re building Bitcoin payment processing solutions, accounting tools, or a custom wallet. Maybe you’re simply looking to do some market research and analytics. Whatever your use case, you find that you are in need of a tool -preferably easy-to-use- that lets you get Bitcoin balance and transaction data. Look no further!

Covalent provides custom endpoints for Bitcoin data under the Class C category, which is required because the Bitcoin blockchain has a very different architecture than Ethereum and other EVMs that Covalent supports through its unified API.

With this data, you can answer questions like:

  • How much BTC was sent in a transaction?

  • Where can I see a record of all Bitcoin transactions for a wallet, including historical prices?

  • What is a user’s Bitcoin wallet balance?

Get token balances for address

GET/v1/{chainName}/address/{address}/balances_v2/

Get bitcoin transactions by wallet address

GET/v1/cq/covalent/app/bitcoin/transactions/?address={address}

Quick Start

Assuming you already have an API key, you can simply paste this into the browser to see transactions for a Bitcoin wallet:

https://api.covalenthq.com/v1/btc-mainnet/address/{address}/?key={ckey_sample}

Remember to replace {address} with a wallet to fetch and {ckey_sample}with your own API key.

Sample Bitcoin Balances Response

json
{
	"data": {
		"address": "3KGwnrNVSeAiDMjQaxixyCgS5c2Qj1jFrb",
		"updated_at": "2023-02-23T22:53:17.552748630Z",
		"next_update_at": "2023-02-23T22:58:17.552749066Z",
		"quote_currency": "USD",
		"chain_id": 20090103,
		"chain_name": "btc-mainnet",
		"items": [
			{
				"contract_decimals": 8,
				"contract_name": "Bitcoin",
				"contract_ticker_symbol": "BTC",
				"contract_address": "",
				"supports_erc": null,
				"logo_url": "https://www.datocms-assets.com/86369/1674516372-property-1-bitcoin-icon-white.svg",
				"last_transferred_at": "2023-02-23T15:07:00Z",
				"native_token": true,
				"type": "cryptocurrency",
				"balance": "14088745",
				"balance_24h": "5782902",
				"quote_rate": 23801.39,
				"quote_rate_24h": 24417.387,
				"quote": 3353.3171,
				"quote_24h": 1412.0336,
				"nft_data": null
			}
		],
		"pagination": null
	},
	"error": false,
	"error_message": null,
	"error_code": null
}

In the API response, you can see relevant information such as the wallet address, time of last update, quote currency and the value of the account owner’s Bitcoin balance.

In the case of the balance field of the Covalent response, it is important to note that the large number you see is denominated in wei.

"balance": "14088745"

To find the corresponding value in the standard unit of BTC, you must adjust for the contract decimals, which are also shown in the response. In this case, "contract_decimals": 8.

That means we can use the following calculation:

14088745/(10^18) = 0.14088745

Here is the account owner’s Bitcoin balance reflected on a block explorer.

Sample Bitcoin Transaction Response

json
{
"updated_at": "2023-02-23T21:49:58.391086357Z",
	"items": [
		{
			"chain_id": "20090103",
			"chain_name": "btc-mainnet",
			"contract_decimals": 8,
			"block_hash": "0000000000000000000911ED93B4AFCADE06A139C9D6B1275C781D40E4CB173E",
			"block_signed_at": "2021-09-15T18:29:14Z",
			"block_height": "700687",
			"tx_hash": "1D61FE84A600E73D5E8E61004F884BECC7B536FA2C4236BAB4514A9E92984BCB",
			"tx_idx": "0",
			"type": "input",
			"address": "1EBxQfnF85CmA95fGHh6y2oP8u5o8qMYWp",
			"value": "8727218",
			"quote_rate": 48169.30245649678,
			"quote": 4203.840034457829,
			"fees_paid": "11200",
			"gas_quote": 5.394961875127638,
			"gas_quote_rate": 48169.30245649678,
			"coinbase": false,
			"locktime": "0",
			"weight": "892",
		},
		{
			"chain_id": "20090103",
			"chain_name": "btc-mainnet",
			"contract_decimals": 8,
			"block_hash": "0000000000000000000911ED93B4AFCADE06A139C9D6B1275C781D40E4CB173E",
			"block_signed_at": "2021-09-15T18:29:14Z",
			"block_height": "700687",
			"tx_hash": "1D61FE84A600E73D5E8E61004F884BECC7B536FA2C4236BAB4514A9E92984BCB",
			"tx_idx": "0",
			"type": "output",
			"address": "3Qo3YUNkXmos5sKsPdrPX5NtT5GTi7ngLY",
			"value": "980000",
			"quote_rate": 48169.30245649678,
			"quote": 472.05916407366846,
			"fees_paid": "11200",
			"gas_quote": 5.394961875127638,
			"gas_quote_rate": 48169.30245649678,
			"coinbase": true,
			"locktime": "0",
			"weight": "892"
		},
		{
			"chain_id": "20090103",
			"chain_name": "btc-mainnet",
			"contract_decimals": 8,
			"block_hash": "0000000000000000000911ED93B4AFCADE06A139C9D6B1275C781D40E4CB173E",
			"block_signed_at": "2021-09-15T18:29:14Z",
			"block_height": "700687",
			"tx_hash": "1D61FE84A600E73D5E8E61004F884BECC7B536FA2C4236BAB4514A9E92984BCB",
			"tx_idx": "1",
			"type": "output",
			"address": "15xsk7dh1ui95joEVtJYLHAgjkZLUXYVb4",
			"value": "7736018",
			"quote_rate": 48169.30245649678,
			"quote": 3726.385908509033,
			"fees_paid": "11200",
			"gas_quote": 5.394961875127638,
			"gas_quote_rate": 48169.30245649678,
			"coinbase": true,
			"locktime": "0",
			"weight": "892"
			}
		]
	]
]

In this transaction data, we can see the tx hash, type of transaction, address, the value of BTC sent, fees paid on the transaction and more. As with the balance data response, all values are denominated in wei.

The 3 items in the sample response above actually make up one transaction. To understand it, we’re going to look at the transaction type first and cross-reference the response with this transaction record in a Bitcoin block explorer.

As we can see, one input item and two output items exist.

In Bitcoin, an input transaction is a record of the Bitcoin being spent in a previous transaction. In contrast, an output transaction records the Bitcoin being received in the current transaction.

Here's a more detailed explanation:

info
When a Bitcoin user wants to send Bitcoin (BTC) to another user, they create a new transaction that includes one or more inputs and one or more outputs. Each input references an unspent output from a previous transaction, which is used to prove that the sender has the right to spend the BTC they are sending. Each output defines the amount of BTC sent and the recipient's address. The input transaction includes the digital signature(s) required to authorize the spending of that BTC. The sum of the inputs must be greater than or equal to the sum of the outputs, with any difference being paid as a transaction fee to the miner who includes the transaction in the next block. An output transaction defines where the BTC being sent in the current transaction will go. Each output has a specific BTC address representing the recipient of the BTC being sent. The amount of BTC being sent is also specified in the output. Once a transaction is included in a block, the outputs become unspent transaction outputs (UTXOs) that can be used as inputs in future transactions.

To review the transaction above, we can adjust all value fields by (value/(10^18)) to convert them into units of BTC.

From there, we know that 0.08727218 BTC was authorized to spend by 1EBxQfnF85CmA95fGHh6y2oP8u5o8qMYWp. Then, 0.00980000 BTC was received by one user 3Qo3YUNkXmos5sKsPdrPX5NtT5GTi7ngLY, and another user, 15xsk7dh1ui95joEVtJYLHAgjkZLUXYVb4 received 0.07736018 BTC.

We also know the fees_paid in gas for each part of the transaction and the quote, which is the value in USD (by default) of the BTC transferred at the time of the transaction. These quotes are extremely helpful when tracking cost basis to understand gains and losses and report taxes correctly.

Common Use Cases

Creating a Bitcoin application or integrating Bitcoin data into a multichain app can provide many benefits, including increased functionality and interoperability. This can help create a more powerful and flexible system that can meet the needs of a wide range of users and use cases.

So what can you build? With balance and transaction data, here are common use cases:

  1. Wallet applications: Wallets allow users to view and manage their assets as well as send and receive Bitcoin transactions.

  2. Analytics tools: These tools allow users to explore and analyze Bitcoin blockchain data, such as charts and graphs that show transaction volume, TVL and more.

  3. Taxation software: This software allows companies to create tax reports and comply with regulatory requirements.

  4. Payment processors: These are systems that allow merchants to accept Bitcoin payments, such as Bitcoin ATMs.

Overall, the possibilities for applications built with Bitcoin blockchain data are endless. As the adoption of Bitcoin continues to grow, we can expect to see many more innovative and useful applications built on top of the Bitcoin blockchain.

);