APIs used:
  • Get token balances for address  
  • Bitcoin: Get transactions by wallet address  

Whether you’re developing Bitcoin payment processing solutions, accounting tools, or a custom wallet, or simply conducting market research and analytics, you need an easy-to-use tool to access Bitcoin balance and transaction data. GoldRush provides custom endpoints for Bitcoin data under the Class C category, which is required due to Bitcoin's unique blockchain architecture compared to Ethereum and other EVMs supported by GoldRush's unified API.

Key Questions Answered:

  • 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?

Quick Start Guide

Get Bitcoin Wallet Balances

To fetch the native Bitcoin balance for a wallet address, use the following endpoint:

Bash
/v1/{chainName}/address/{walletAddress}/balances_v2/

This endpoint is commonly used to fetch the native, fungible (ERC20), and non-fungible (ERC721 & ERC1155) tokens held by an address. The response includes spot prices and other metadata.

Example:

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

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

Replace {address} with the Bitcoin wallet address you want to check and {ckey_sample} with your own API key.

Sample Bitcoin Balances Response:

json
{
  "address": "bc1q5gzu4sty6vtpv045d59w4quj46wrjnenlee9sv",
  "updated_at": "2024-05-14T21:57:35.596513839Z",
  "next_update_at": "2024-05-14T22:02:35.596514209Z",
  "quote_currency": "USD",
  "chain_id": 20090103,
  "chain_name": "btc-mainnet",
  "items": [
    {
      "contract_decimals": 8,
      "contract_name": "Bitcoin",
      "contract_ticker_symbol": "BTC",
      "contract_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "supports_erc": null,
      "logo_url": "https://www.covalenthq.com/static/images/icons/display-icons/bitcoin-logo.svg",
      "contract_display_name": "Bitcoin",
      "logo_urls": null,
      "last_transferred_at": "2024-05-14T11:45:45Z",
      "native_token": true,
      "type": "cryptocurrency",
      "is_spam": false,
      "balance": "2017356",
      "balance_24h": "0",
      "quote_rate": 61660.36,
      "quote_rate_24h": 62893.566,
      "quote": 1243.9089,
      "pretty_quote": "$1,243.91",
      "quote_24h": 0,
      "pretty_quote_24h": "$0.00",
      "protocol_metadata": null,
      "nft_data": null
    }
  ],
  "pagination": null
}

In this response, you can see information such as the wallet address, the time of the last update, the quote currency, and the value of the account owner’s Bitcoin balance. The balance field is denominated in satoshis (the smallest unit of Bitcoin, where 1 BTC = 100,000,000 satoshis).

Calculating Bitcoin Balance

To convert the balance into BTC:

scss
balance (satoshis) / (10^8) = balance (BTC)

For example:

scss
2017356 satoshis / (10^8) = 0.02017356 BTC

Sample Bitcoin Transaction Response

To fetch Bitcoin transactions by wallet address, use the following endpoint:

Bash
/v1/{chainName}/address/{walletAddress}/transactions_v2/

Example Response:

json
{
  "updated_at": "2024-05-14T21:41:37.284082994Z",
  "items": [
    {
      "chain_id": "20090103",
      "chain_name": "btc-mainnet",
      "contract_decimals": 8,
      "block_hash": "0000000000000000000696E50D16ABF93731132C0A1402F3575AAD699963C8AF",
      "block_signed_at": "2021-09-15T18:52:30Z",
      "block_height": "700692",
      "tx_hash": "BD08D72860C1F19FF4CB14F453B644681782E98CF9620C3009DF45869CDCDEF9",
      "tx_idx": "0",
      "type": "input",
      "address": "3Qo3YUNkXmos5sKsPdrPX5NtT5GTi7ngLY",
      "value": "980000",
      "quote_rate": 48182.7061026188,
      "quote": 472.190519805664,
      "fees_paid": "76549",
      "gas_quote": 36.8833796944937,
      "gas_quote_rate": 48182.7061026188,
      "coinbase": false,
      "locktime": "700691",
      "weight": "27801"
    },
    {
      "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": 48089.8349864272,
      "quote": 471.280382866987,
      "fees_paid": "11200",
      "gas_quote": 5.38606151847985,
      "gas_quote_rate": 48089.8349864272,
      "coinbase": true,
      "locktime": "0",
      "weight": "892"
    }
  ],

This response provides transaction data such as the tx hash, transaction type, address, value of BTC sent, fees paid, and more. As with the balance data response, all values are denominated in satoshis.

Understanding Bitcoin Transactions

Bitcoin transactions consist of inputs and outputs. An input transaction records the Bitcoin being spent from a previous transaction, while an output transaction records the Bitcoin being received in the current transaction.

Example Calculation: To convert the value fields into BTC:

scss
value (satoshis) / (10^8) = value (BTC)

For example:

scss
980000 satoshis / (10^8) = 0.0098 BTC

Common Use Cases

  1. Bitcoin Wallet Lookup: Allows users to check the balance and transactions of a Bitcoin wallet.

  2. Bitcoin Transaction Tracker: Enables tracking of Bitcoin transactions for a wallet address, including historical prices.

  3. Bitcoin Balance Checker: Provides real-time balance information for Bitcoin wallets.

  4. Check BTC Wallet Balance: Simplifies the process of checking the balance of a Bitcoin wallet.

Conclusion

Integrating Bitcoin balance and transaction data into your applications can provide many benefits, including increased functionality and interoperability. With GoldRush’s API endpoints, you can easily build wallet applications, analytics tools, taxation software, payment processors, and more. As Bitcoin adoption continues to grow, the possibilities for innovative applications built on the Bitcoin blockchain are endless.

For more detailed information, visit GoldRush's Documentation.