How to Get Bitcoin Balances and Transactions
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!
GoldRush 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 GoldRush 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
Commonly used to fetch the native, fungible (ERC20), and non-fungible (ERC721 & ERC1155) tokens held by an address. Response includes spot prices and other metadata.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
{
"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 GoldRush 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
Here is the endpoint for Bitcoin transactions by wallet address.
{
"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:
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:
Wallet applications: Wallets allow users to view and manage their assets as well as send and receive Bitcoin transactions.
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.
Taxation software: This software allows companies to create tax reports and comply with regulatory requirements.
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.
