编程获取比特币钱包余额：NodeJs与Python实现指南

掌握两种主流API调用方式，快速集成比特币余额查询功能到你的应用中。

获取比特币钱包余额是区块链开发中的常见需求。无论是开发钱包应用、交易机器人还是资产监控工具，实时查询余额都是核心功能之一。本文将详细介绍两种通过第三方API服务实现这一功能的方法，并提供完整的NodeJs和Python代码示例。

比特币余额查询的两种途径

查询比特币钱包余额主要有两种方式：

直接查询全节点：通过运行比特币核心客户端（Bitcoin Core）获取数据。这种方式延迟低、数据最实时，但需要自行维护全节点，硬件成本和技术门槛较高。

调用第三方API：利用Mempool、BlockCypher等提供的API服务。这种方式简单快捷，无需维护基础设施，但可能存在轻微的数据延迟，因为数据需要经过服务商的中间处理层。

对于大多数开发者和项目而言，第三方API是更实际的选择。下面将重点介绍两种可靠的API解决方案。

使用Mempool Space API查询余额

Mempool.space 提供了简洁高效的比特币区块链数据API，包括地址余额查询服务。

NodeJs 实现代码

const axios = require('axios');

async function getBTCAddressBalance(btcAddress) {
  const url = `https://mempool.space/api/address/${btcAddress}`;
  
  try {
    const response = await axios.get(url);
    const { chain_stats, mempool_stats } = response.data;
    
    const confirmedBalance = chain_stats.funded_txo_sum - chain_stats.spent_txo_sum;
    const unconfirmedBalance = mempool_stats.funded_txo_sum - mempool_stats.spent_txo_sum;
    const totalBalance = confirmedBalance + unconfirmedBalance;
    
    console.log(`BTC钱包地址: ${btcAddress}`);
    console.log(`已经确认的余额: ${confirmedBalance} satoshis`);
    console.log(`未经确认的余额: ${unconfirmedBalance} satoshis`);
    console.log(`总余额: ${totalBalance} satoshis`);
    
    return {
      "total": totalBalance,
      "confirmedBalance": confirmedBalance,
      "unconfirmedBalance": unconfirmedBalance,
    };
  } catch (error) {
    console.error('错误:', error.message);
    return null;
  }
}

Python 实现代码

import requests

def get_btc_address_balance(btc_address):
    url = f'https://mempool.space/api/address/{btc_address}'
    
    try:
        response = requests.get(url)
        response.raise_for_status()
        data = response.json()
        
        chain_stats = data['chain_stats']
        mempool_stats = data['mempool_stats']
        
        confirmed_balance = chain_stats['funded_txo_sum'] - chain_stats['spent_txo_sum']
        unconfirmed_balance = mempool_stats['funded_txo_sum'] - mempool_stats['spent_txo_sum']
        total_balance = confirmed_balance + unconfirmed_balance
        
        print(f'BTC钱包地址: {btc_address}')
        print(f'已经确认的余额: {confirmed_balance} satoshis')
        print(f'未经确认的余额: {unconfirmed_balance} satoshis')
        print(f'总余额: {total_balance} satoshis')
        
        return {
            "totalBalance": total_balance,
            "confirmedBalance": confirmed_balance,
            "unconfirmedBalance": unconfirmed_balance,
        }
    except requests.RequestException as error:
        print('错误:', error)
        return None

该API返回的数据包含已确认余额（链上确认的交易）和未确认余额（内存池中的交易），帮助开发者全面掌握地址资产状态。

使用BlockCypher API查询余额

BlockCypher是另一个流行的区块链API服务商，提供多币种支持和完善的文档。

NodeJs 实现代码

const axios = require('axios');

async function getBTCBalance(address) {
  const url = `https://api.blockcypher.com/v1/btc/main/addrs/${address}/balance`;
  
  try {
    const response = await axios.get(url);
    const balance = response.data.balance;
    console.log('余额 Satoshis:', balance);
    console.log('余额 BTC:', balance / 1e8);
    return {
      "balance": balance,
      "balance_in_btc": balance / 1e8
    }
  } catch (error) {
    console.error('错误:', error.message);
  }
}

Python 实现代码

import requests

def get_btc_balance(address):
    url = f'https://api.blockcypher.com/v1/btc/main/addrs/{address}/balance'
    
    try:
        response = requests.get(url)
        response.raise_for_status()
        data = response.json()
        
        balance = data['balance']
        print('余额 Satoshis:', balance)
        print('余额 BTC:', balance / 1e8)
        
        return {
            "balance": balance,
            "balance_in_btc": balance / 1e8
        }
    except requests.RequestException as error:
        print('错误:', error)
        return None

BlockCypher API直接返回最终余额数据，无需额外计算，使用更加简便。👉 查看实时余额查询工具

比特币余额计算的特殊性

比特币的余额计算并非简单的加减法，而是基于UTXO（未花费交易输出）模型。每个比特币交易都由输入和输出组成，钱包余额实际上是该地址所有未花费输出的总和。

这种模型意味着：

• 余额不是存储在地址中，而是通过计算所有关联的UTXO得出
• 每次交易都可能产生找零输出，返回至新地址
• 需要区分已确认和未确认的交易余额

理解这一机制对于正确处理余额查询结果至关重要，特别是在处理大额或频繁交易时。

常见问题

如何选择适合的API服务？

选择API服务时考虑以下因素：请求频率限制、数据延迟要求、可靠性历史记录和成本。对于个人项目，免费层通常足够；商业应用则需评估付费方案。

为什么需要区分已确认和未确认余额？

已确认余额指经过区块链网络验证的交易，具有最终性。未确认余额来自内存池中的待处理交易，可能被取消或替换。区分两者可避免双重支付风险。

API调用频率有限制吗？

大多数服务商对免费API都有调用频率限制。Mempool.space和BlockCypher都提供详细的限流政策，建议仔细阅读文档以避免服务中断。

如何处理API返回的错误？

网络错误、无效地址或服务不可用都可能导致API调用失败。实现重试机制、错误日志记录和优雅降级策略可提升应用 robustness。

自行搭建节点与使用API有何区别？

自行搭建节点提供最高数据主权和实时性，但需要大量存储空间和带宽。API服务省去维护成本，适合大多数应用场景，但依赖第三方服务可用性。

如何将Satoshis转换为BTC？

1比特币等于100,000,000 Satoshis（1e8）。转换公式为：BTC = Satoshis / 100,000,000。所有代码示例都包含这种转换计算。

总结

通过第三方API查询比特币钱包余额是开发者集成区块链功能的便捷方式。本文介绍的Mempool.space和BlockCypher都是可靠的选择，分别提供详细交易数据和简洁余额信息。

选择哪种方案取决于具体需求：需要交易明细和未确认数据时选用Mempool API；只需最终余额时BlockCypher更加简单直接。两种服务都提供完善的文档和开发者支持，是构建比特币相关应用的优秀基础组件。👉 获取更多区块链开发资源