getreceivedbyaddress为何不是余额？

商户看板最危险的一类指标，是把getreceivedbyaddress的结果标成“地址余额”。这个RPC更像累计水表：它统计达到确认门槛的历史流入；当前UTXO更像水库余量：已经花出的输出不再存在。两者服务不同问题，数字相同只能是某一时点的巧合。

接口回答的是累计收到多少

getreceivedbyaddress返回指定地址接收的BTC总额，可用minconf设置最低确认数且默认1。

被查询地址必须属于当前钱包。

查询地址必须属于当前钱包，minconf决定哪些收款被纳入。默认1会排除零确认付款；将minconf设为0会改变口径，但不意味着未确认交易安全或最终。采集记录必须保存minconf、钱包、节点和区块高度。

累计收到的币即使后来已经花出仍属于历史收款，因此该返回值不能当作当前可花余额。

假设某地址先收到2 BTC，随后把其中1.5 BTC作为输入花出并产生找零。累计收款仍描述过去收到的2 BTC；剩余价值分散在哪些UTXO、找零是否回到另一个地址，则由具体交易决定。不能用“received减发送交易金额”简单重建余额，因为交易输入输出和手续费不按账户流水工作。

同一交易可能花费多个输入并生成多个输出。某个地址“发送了多少”也不是协议原生字段。要做当前状态核对，应从未花费outpoint集合出发，而不是把区块浏览器的地址聚合数字当作账本账户。

listunspent返回当前未花费交易输出，可按地址和确认数过滤，更适合解释地址相关的剩余UTXO。

listunspent返回txid、vout、amount、confirmations、safe等字段，并可按地址过滤。把符合业务确认数、安全性和冻结规则的输出相加，才能接近该业务语境下的可用集合。若启用avoid_reuse，还要决定reused输出是否被策略排除。

钱包级展示用getbalances更合适，因为它区分trusted、untrusted_pending、immature以及可能的used。但钱包余额也不等于平台可提现额，内部审批、保留金和费用仍在RPC之外。

商户收入可用累计已确认收款或逐交易流水；资金调度用当前UTXO和钱包余额；风险观察另列未确认金额。三种指标分别标明确认门槛和统计时点，避免一个大数字同时承担营收、资产和可提现余额。

若累计收款突然下降，先检查minconf、钱包扫描、链重组和调用地址，不要立即推断历史被篡改。若当前UTXO下降，回查具体花费交易、找零和业务审批。两类报警使用不同的证据链。

选一个已知地址，保存getreceivedbyaddress结果，再用钱包交易记录列出相关收款txid，最后用listunspent确认仍存的outpoint。只要其中部分收款已被花费，累计值就会高于当前地址相关UTXO，这正是预期而非bug。

账户模型差异见UTXO与账户模型，单输出检查见确认UTXO未花费，钱包汇总见getbalances余额桶。本文是RPC数据定义，不构成余额证明、审计意见或资产归属结论。

资料访问时间为2026-08-13。仍需保留的边界：地址级余额不是Bitcoin协议的原生账户状态；看板口径必须说明是否包含未确认、锁定或不安全输出。