Bitcoin API：无需运行节点即可接受 BTC 支付

Bitcoin Core 的 JSON-RPC 在给出第一个有用的响应之前，需要一个已同步的节点。REST API 需要的是一个 API 密钥。这个区别会体现在你的日程表上：在典型硬件上，初始区块下载需要数天，之后节点还会持续占用磁盘和带宽，并在产品存续期间一直需要监控。我们关于 blockchain API 与 blockchain node 对比的文章详细比较了这两种方式。当你需要对网络视图拥有策略层面的控制权时，运行自己的节点；当支付才是目标时，使用 API。

日常调用能干净地映射到 REST 模型上。节点集成需要包装 getnewaddress 和 listtransactions 并轮询变化，而 API 只需分配地址，让 Webhook 负责监视。轮询循环消失了，随之消失的还有那些在周末悄悄崩溃的 cron 任务。

还有第二个区别。原始的 RPC 方法返回原始数据。Chaingateway 返回带有可读字段的结构化 JSON，因此响应可以直接进入你的数据库，而不必经过一层解析。

发送路径的 REST 一侧只有三个接口。POST /api/v2/bitcoin/wallets 创建一个钱包，用 Chaingateway 不会存储的密码加密——丢失密码就没有人能恢复该钱包，这正是设计的目的。POST /api/v2/bitcoin/wallets/{wallet}/addresses 在其下派生出你需要数量的地址；一个钱包承载全部地址。而 POST /api/v2/bitcoin/transactions 负责发送：

curl -X POST https://app.chaingateway.io/api/v2/bitcoin/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "amount": 0.0015,
    "walletname": "treasury",
    "password": "wallet-password",
    "speed": "medium"
  }'

响应携带已广播交易的 txid。speed 可取 fast、medium 或 slow，用于设定手续费等级——即成本与首次确认时间之间的权衡。可选的 subtractfee: true 会从金额中扣除网络手续费，而不是额外叠加，这在客户提取全部余额时很有用。

比特币大约每十分钟出一个区块，尽管单次间隔差异很大。在包含你交易的区块之上每挖出一个新区块，就会增加一次确认，每一次确认都让回滚变得更困难。

六次确认——大约一小时——自早期交易所时代以来一直是「已结算」的事实标准，截至 2026 年年中依然成立。

十分钟是平均值，不是时间表

难度调整会让它在长期内保持稳定，但单次间隔围绕这个平均值大幅波动——一分钟内出两个区块会发生，四十分钟没有区块的情况也会发生。支付体验设计必须尊重这一点：「大约十分钟」是一个平均值，不是一个承诺，因此你的结账页面应该写「通常在一小时内」，而不是运行一个它无法遵守的倒计时。

为什么不在零确认时就入账？

因为在交易被打包进区块之前，它停留在内存池（mempool）中，在那里可能被替换或双花，即使是最新的区块，也可能在链重组中被移出主链。API 把这项工作拆成两部分。Webhook 会在交易于链上结算的那一刻触发——payload 携带金额、地址、txid 和区块号——因此你的界面可以立即做出反应。之后，GET /api/v2/bitcoin/transactions/{txid}/decoded 返回当前的确认数，让你的账本只为达到你设定阈值的资金入账。及早展示进度，延后完成结算。

比特币没有账户余额这一概念。链上存储的是未花费的交易输出——UTXO，每一个都是锁定在某个地址上的一小笔独立价值。一个钱包的「余额」是你的软件通过汇总其地址控制的每一个 UTXO 计算出来的数字；协议本身从不在任何地方存储这个总和。花费会消耗整个 UTXO 并创建新的 UTXO，包括返还给自己的找零输出——就像用一张十欧元纸币支付一笔七欧元账单会找回零钱一样。

以太坊采用相反的模型。一个账户对应一个余额，链直接存储它，一次存款就是一次递增。在 EVM 链上，给客户一个地址、让上百笔存款在多年间堆积在这个地址上，是很正常的做法。

对存款处理而言，UTXO 模型有一个实际的优势：它天然引导你为每位客户或每张发票使用一个地址，而这本来就是更干净的设计。每一笔传入付款都是发往你所监控地址的一个新输出，因此归属是明确无歧义的——无需解析备注，无需按金额匹配。这也意味着「某个地址的余额」是一个由索引器而不是链本身回答的问题，而这正是你通过使用带 Webhook 的 API、而不是自己搭建这套机制所外包出去的记账工作。通知会告诉你：这笔金额、这个地址、这笔交易、这个区块。剩下的交给你的账本。

加上请求头 X-Network: testnet，本页每一次调用都会运行在比特币测试网络上：相同的路由，相同的响应结构，代币没有任何价值。水龙头免费发放测试用 BTC，因此整个存款流程——地址、付款、Webhook、确认——都可以从头到尾演练一遍，而不花一聪（satoshi）。

把这个请求头放在配置里，而不是散落在代码各处，并为你的预发布环境设置一个独立的回调 URL，这样测试存款就不会泄漏进生产账本。当演练顺利通过后，移除这个请求头。集成的其他部分不需要任何改动，这正是它的意义所在：第一笔主网存款应该是平淡无奇的。

支付后端的价值恰恰体现在糟糕的日子里，所以要明确规划失败路径。

在 HTTP 层面，规则是标准的 REST 规则。401 意味着 Bearer 令牌错误或缺失；修正密钥，而不是重试。其他 4xx 响应指向请求本身——记录响应体，它会说明问题所在，并把它当作一个 bug 来处理。5xx 范围的响应和超时是临时性的；用退避策略重试它们。

比特币特有的失败模式存在于 HTTP 之上。一笔始终无法确认的存款通常是手续费给得太低、卡在内存池中；它可能几小时后确认，也可能彻底消失，这也是为什么 detected 和 settled 在你的系统中必须是分开的状态。一条金额低于发票的通知是一项业务决策，而不是错误——用代码来处理它，而不是靠支持工单。如果你的 Webhook 接口曾经宕机，失败的投递会在那里等你：GET /api/v2/bitcoin/webhooks/notifications/failed 会列出它们，POST /api/v2/bitcoin/webhooks/notifications/{id}/retry 可以逐条重新发送，而 GET /api/v2/bitcoin/webhooks/notifications 上的完整列表能让你与账本比对差异并补上缺口。即使一切看起来正常，也要每晚执行一次这种比对。只有在出事之后才运行的对账机制，只会在生产环境中发现自己的 bug。

比特币本身没有 USDT 或 USDC——稳定币生活在其他链上。共享平台带来的是先发优势：你的比特币集成已经使用与我们的 Ethereum 和 TRON 接口相同的 API。今天接受 BTC，下个冲刺周期用同一个密钥、同一个 Webhook 处理程序在 TRON 上加上 USDT。blockchain API 总览列出了全部七条受支持的链。

对大多数团队来说，实用的顺序是：先上线 BTC 存款，因为这是客户会直接指名要求的功能，然后让支付数据告诉你接下来该加哪条稳定币通道。在 Chaingateway 上，这条第二通道会原样复用你的签名验证、对账任务和存款状态机。

• 它拥有所有区块链中最长的运行记录，自 2009 年运行至今，也拥有终端用户中最广泛的认可度。
• 网络全天候结算。没有银行营业时间，也没有地区截止时间。
• 确认遵循可预测的节奏，大约每十分钟一个新区块，这让支付流程易于推理。
• 其采用规模是所有加密网络中最大的，因此「你们接受比特币吗？」仍然是客户最先问的问题。

这些特性都不是来自某次路线图更新；它们与该网络最初发布时提供的保证完全相同。这种稳定性正是在长周期产品中选择 BTC 的理由：今年构建的集成不会因为明年的协议转向而被淘汰——这是大多数支付技术栈都无法承诺的。

最明显的场景是收银台：客户选择比特币，你的应用分配一个地址；Webhook 确认付款。同样的构建模块也能承载更重的负载。交易所和游戏平台为每位用户运行一个存款地址，在确认后为余额入账。付款和汇款流程无需中间的代理银行即可推动跨境转账。订阅业务在每个周期生成一个全新的发票地址，让 Webhook 完成收尾。

这些场景的共同点在于工作的形态。比特币负责结算；你的应用负责状态。API 位于两者之间，把链上事件转化为你的框架已经知道如何路由的 HTTP 调用——这也是为什么收银场景和交易所场景可以运行在同样几个接口上。