Check Bitcoin Address Balance

Overview

Query the balance of any Bitcoin address using the mempool.space API. This is a read-only operation that requires no authentication.

The Code

"""
Bitcoin Address Balance Checker
Query any address balance via mempool.space API

Requirements: requests (pip install requests)
"""

import requests
from typing import Optional

MEMPOOL_API = "https://mempool.space/api"

def get_address_balance(address: str, testnet: bool = False) -> dict:
    """
    Get the balance of a Bitcoin address.

    Args:
        address: Bitcoin address (any format)
        testnet: Use testnet API if True

    Returns:
        dict with confirmed and unconfirmed balances in satoshis
    """
    base_url = "https://mempool.space/testnet/api" if testnet else MEMPOOL_API

    response = requests.get(
        f"{base_url}/address/{address}",
        timeout=10
    )
    response.raise_for_status()

    data = response.json()

    # Chain stats = confirmed, mempool stats = unconfirmed
    chain = data.get("chain_stats", {})
    mempool = data.get("mempool_stats", {})

    confirmed = chain.get("funded_txo_sum", 0) - chain.get("spent_txo_sum", 0)
    unconfirmed = mempool.get("funded_txo_sum", 0) - mempool.get("spent_txo_sum", 0)

    return {
        "address": address,
        "confirmed_sats": confirmed,
        "unconfirmed_sats": unconfirmed,
        "total_sats": confirmed + unconfirmed,
        "confirmed_btc": confirmed / 100_000_000,
        "total_btc": (confirmed + unconfirmed) / 100_000_000,
        "tx_count": chain.get("tx_count", 0)
    }


def get_utxos(address: str, testnet: bool = False) -> list:
    """
    Get unspent transaction outputs for an address.

    Args:
        address: Bitcoin address
        testnet: Use testnet API if True

    Returns:
        List of UTXOs with txid, vout, value
    """
    base_url = "https://mempool.space/testnet/api" if testnet else MEMPOOL_API

    response = requests.get(
        f"{base_url}/address/{address}/utxo",
        timeout=10
    )
    response.raise_for_status()

    utxos = response.json()

    return [{
        "txid": utxo["txid"],
        "vout": utxo["vout"],
        "value_sats": utxo["value"],
        "value_btc": utxo["value"] / 100_000_000,
        "confirmed": utxo["status"]["confirmed"]
    } for utxo in utxos]


# Example usage
if __name__ == "__main__":
    # Satoshi's genesis address (for demonstration)
    address = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"

    try:
        balance = get_address_balance(address)
        print(f"Address: {balance['address']}")
        print(f"Confirmed: {balance['confirmed_sats']:,} sats ({balance['confirmed_btc']:.8f} BTC)")
        print(f"Unconfirmed: {balance['unconfirmed_sats']:,} sats")
        print(f"Transactions: {balance['tx_count']}")

        utxos = get_utxos(address)
        print(f"\nUTXOs: {len(utxos)}")
        for utxo in utxos[:3]:  # Show first 3
            print(f"  {utxo['txid'][:16]}... : {utxo['value_sats']:,} sats")

    except requests.RequestException as e:
        print(f"API error: {e}")

Usage

# Install dependency
pip install requests

# Run the script
python check_balance.py

Example Output

Address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
Confirmed: 7,259,433,859 sats (72.59433859 BTC)
Unconfirmed: 0 sats
Transactions: 3,542

UTXOs: 3542
  4a5e1e4baab89f3a... : 5,000,000,000 sats
  ...

Agent Notes

Rate limits: mempool.space has no strict rate limits but be respectful. For high-volume queries, run your own mempool instance.

Address formats supported:

• P2PKH (legacy): 1...
• P2SH (SegWit wrapped): 3...
• P2WPKH (native SegWit): bc1q...
• P2TR (Taproot): bc1p...

Error handling: Always wrap API calls in try/except. Network errors and invalid addresses will raise exceptions.