通过 RPC 获取任何比特币地址的余额

核心关键词：比特币地址余额、Bitcoin RPC、UTXO 查询、XPub 余额、bb_getAddress

本指南只需三分钟即可让你在 不创建钱包 的情况下，快速查到任一比特币地址的 实时余额、收款金额、支出金额以及最新交易 ID。

为什么选择 RPC 而不是 watch-only 钱包？

自建比特币全节点时，最常见的做法是给陌生地址创建 只读钱包 (watch-only)。但弊端随之而来：

每新增一个地址都得重复导入，操作繁琐。
在 非 SPV 轻客户端 环境下长期索引会占用大量内存，导致节点崩溃。
难以横向扩展，钱包一多就卡顿。

为了彻底解决可扩展性问题，QuickNode 推出了 BTC Blockbook JSON-RPC 插件。该插件把索引压力交由后端集群，自己无需再为每个地址建立本地关系表。插件提供 3 组核心方法：

方法	功能简述
`bb_getUTXOs`	拉取地址或 XPub 的未花费交易输出。
`bb_getXPUB`	一次返回 XPub 或描述符的余额与交易历史。
`bb_getAddress`	查询单一地址的余额与按区块高度降序排序的交易。

本文专注讲解最常用的 bb_getAddress。

👉 点击立即体验一键式比特币节点托管，告别自建繁琐

术语热身：XPub、UTXO、Satoshi

XPub：扩展公钥，直接决定一长串比特币收款地址的生成路径，常用于 HD 钱包。
UTXO：Unspent Transaction Output，即 链上真正还能花出去的钱。
Satoshi：比特币最小单位，1 BTC = 1 亿 Satoshi，查询接口返回数字均以 Satoshi 为单位。

创建你的比特币 RPC 端点

登录控制台 → 选择 Bitcoin Mainnet。
进入 Marketplace 搜索 Blockbook JSON-RPC Add-on 并勾选，需升级到付费套餐。
成功创建后复制 HTTPS RPC Endpoint URL。

👉 查看当前套餐对比并立刻领取优惠

动手实战：命令行调取 `bb_getAddress`

打开终端，将下方命令中的 YOUR_RPC_URL 替换为你的 HTTPS endpoint：

curl YOUR_RPC_URL \
  --header 'Content-Type: application/json' \
  --data '
    {
      "method": "bb_getAddress",
      "params": [
        "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        {
          "page": 1,
          "size": 10,
          "fromHeight": 0,
          "details": "txids"
        }
      ]
    }
  '

结果字段速读

balance：余额（Satoshi）
totalReceived：该地址累计接收（Satoshi）
totalSent：累计转出（Satoshi）
txids：按区块时间倒序的交易 ID 数组

示例输出（经过 jq 美化）：

{
  "balance": "7263430323",
  "totalReceived": "7263430323",
  "totalSent": "0",
  "txids": [
    "8b6d6…",
    "77acb…"
  ]
}

浅算一下：balance ÷ 1 亿 ≈ 72.63430323 BTC。

DEBUG 小贴士：实时日志

在 QuickNode 控制台的 Logs 页签，可看到每条 RPC 的耗时、返回大小及错误码，调试效率大幅提升。日志保留时长取决于所选套餐。

进阶玩法

分页遍历：让 page 自增 1 并配合 size 控制，就能完整抓取所有历史。
区块过滤：给 fromHeight 设具体高度，可跳过早期交易。
丰富详情：把 details 改成 "txs" 就能获得完整 JSON 交易体，方便离线分析。

常见问题与解答

Q1: 地址不存在会报错吗？
A：不会。接口会把余额、收款、转出均设为 0，并返回空交易列表。

Q2: 请求频率有什么限制？
A：采用 “按套餐 RPS” 限制；需扩容可直接升级套餐，秒级生效，不中断业务。

Q3: Satoshi 与 BTC 如何快速转换？
A：简易除法：Satoshi ÷ 100,000,000 = BTC；反之乘一亿。离线项目可用 sats-to-btc 库一键转换。

Q4: 我能用 JavaScript 吗？
A：当然可以。安装 axios 后，用同参数 POST 即可。Node.js 示例已放在官方文档。

Q5: 支持测试网 Testnet 吗？
A：支持。创建端点时选择 Bitcoin Testnet，其余调用完全一致。
（温馨提示：Testnet 币想多少就有多少，调试时用足“空转”啦）