Skip to main content

Bitcoin Address API

Bitcoin doesn't store account balances on-chain — there is no getBalance call. The reliable way to get an address balance is to sum every UTXO the address received (outputs) and subtract every UTXO it has spent (inputs). Bitquery indexes that UTXO data and pairs every value with the BTC/USD price at the time of the transaction, so you can pull current balances, historical balances at a specific block, or full activity timelines in a single request.

Endpoint

Bitcoin GraphQL queries are served at https://graphql.bitquery.io.

Returns total BTC sent (inputs) and received (outputs) for an address, along with USD-equivalent values and first / last activity dates. Subtract inputs.value from outputs.value to get the current balance.

{
  bitcoin(network: bitcoin) {
    inputs(
      inputAddress: {is: "bc1ppu6akjngyvpxwz0w38n4evcygwh08tjtmcc0dx6ft2zzgkxtd97stwehcq"}
    ) {
      count
      value
      value_usd: value(in: USD)
      min_date: minimum(of: date)
      max_date: maximum(of: date)
    }
    outputs(
      outputAddress: {is: "bc1ppu6akjngyvpxwz0w38n4evcygwh08tjtmcc0dx6ft2zzgkxtd97stwehcq"}
    ) {
      count
      value
      value_usd: value(in: USD)
      min_date: minimum(of: date)
      max_date: maximum(of: date)
    }
  }
}

Get a Bitcoin address balance via addressStats​

addressStats is a pre-aggregated view — fast, but it can lag the chain. Use it for quick lookups and dashboards; use the UTXO sum above when you need exact, up-to-the-block accuracy. Run query.

caution

addressStats is pre-aggregated and may occasionally be out of date. For precise balance math, use the inputs / outputs query above.

{
  bitcoin(network: bitcoin) {
    addressStats(address: {is: "bc1q6xra3s8c5c4vr8m5f9htkuc3neyn4zykv5seua"}) {
      address {
        balance
        inboundTransactions
        firstActive {
          time
        }
        address
        annotation
        outflows
        lastActive {
          time
        }
        uniqueSenders
        uniqueReceivers
      }
    }
  }
}

Get a Bitcoin balance at a specific block height​

Need to know what a wallet held at a particular point in time? The height filter caps inputs and outputs at a given block number, which is exactly what you need for audits, tax reporting, and point-in-time portfolio snapshots. Balance at that height equals outputs.value - inputs.value. Run query.

{
  bitcoin(network: bitcoin) {
    inputs(
      inputAddress: {is: "bc1ppu6akjngyvpxwz0w38n4evcygwh08tjtmcc0dx6ft2zzgkxtd97stwehcq"}
      height: {lteq: 944000}
    ) {
      count
      value
      value_usd: value(in: USD)
      min_date: minimum(of: date)
      max_date: maximum(of: date)
    }
    outputs(
      outputAddress: {is: "bc1ppu6akjngyvpxwz0w38n4evcygwh08tjtmcc0dx6ft2zzgkxtd97stwehcq"}
      height: {lteq: 944000}
    ) {
      count
      value
      value_usd: value(in: USD)
      min_date: minimum(of: date)
      max_date: maximum(of: date)
    }
  }
}

Aggregate balances for multiple Bitcoin addresses in one call​

Pass an array of addresses to inputAddress and outputAddress with {in: [...]} to get per-wallet totals in a single request. Useful for exchanges, custodians, and portfolio dashboards that monitor many wallets at once. Run query.

{
  bitcoin(network: bitcoin) {
    inputs(
      inputAddress: {in: ["bc1ppu6akjngyvpxwz0w38n4evcygwh08tjtmcc0dx6ft2zzgkxtd97stwehcq", "bc1p2gel5e7ny42epalps3vddqrwedqh8ca4v6fdjem3pa3930ltl90s2cfg6e"]}
    ) {
      count
      value
      value_usd: value(in: USD)
      min_date: minimum(of: date)
      max_date: maximum(of: date)
      inputAddress {
        address
      }
    }
    outputs(
      outputAddress: {in: ["bc1ppu6akjngyvpxwz0w38n4evcygwh08tjtmcc0dx6ft2zzgkxtd97stwehcq", "bc1p2gel5e7ny42epalps3vddqrwedqh8ca4v6fdjem3pa3930ltl90s2cfg6e"]}
    ) {
      count
      value
      value_usd: value(in: USD)
      min_date: minimum(of: date)
      max_date: maximum(of: date)
      outputAddress {
        address
      }
    }
  }
}

Get a Bitcoin address's first and last active timestamps​

Quick way to find when a wallet first appeared on-chain and the last time it transacted. Useful for wallet age analysis, dormant-address screening, and compliance checks.

caution

addressStats is pre-aggregated and may occasionally be inaccurate. For precise timestamps, query inputs and outputs directly with minimum(of: date) and maximum(of: date).

query ($network: BitcoinNetwork!) {
  bitcoin(network: $network) {
    addressStats(address: {is: "ADDRESS_HERE"}) {
      address {
        firstActive {
          year
          month
          dayOfMonth
        }
        lastActive {
          year
          month
          dayOfMonth
        }
      }
    }
  }
}

Replace ADDRESS_HERE with the Bitcoin address you want to inspect.

List inputs and outputs for an address over a date range​

Returns every UTXO an address spent or received inside a time window, with block height, timestamp, transaction hash, output index, BTC value, and USD-equivalent. Use it for transaction reports, payment reconciliation, and per-period wallet activity feeds. Run query.

{
  bitcoin(network: bitcoin) {
    outputs(
      date: {since: "2024-03-19", till: "2024-03-26"}
      outputAddress: {is: "bc1p2gel5e7ny42epalps3vddqrwedqh8ca4v6fdjem3pa3930ltl90s2cfg6e"}
      options: {desc: ["block.height", "outputIndex"], limit: 10, offset: 0}
    ) {
      block {
        height
        timestamp {
          time(format: "%Y-%m-%d %H:%M:%S")
        }
      }
      transaction {
        hash
      }
      outputIndex
      outputDirection
      value
      value_usd: value(in: USD)
    }
    inputs(
      date: {since: "2024-03-19", till: "2024-03-26"}
      inputAddress: {is: "bc1p2gel5e7ny42epalps3vddqrwedqh8ca4v6fdjem3pa3930ltl90s2cfg6e"}
      options: {desc: ["block.height", "transaction.index"], limit: 10, offset: 0}
    ) {
      block {
        height
        timestamp {
          time(format: "%Y-%m-%d %H:%M:%S")
        }
      }
      outputTransaction {
        hash
        index
      }
      transaction {
        hash
        index
      }
      inputIndex
      value
      value_usd: value(in: USD)
    }
  }
}