支持 BTC 支付

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

通过 REST API 接受 BTC 支付。生成存款地址,跟踪确认数,无需运行完整的 Bitcoin 节点即可发送提现。

7 天免费试用 — 无需信用卡,无需 KYC 即可开始 非托管 — 私钥始终由你掌控 套餐起价 49 欧元/月(490 欧元/年)— 查看套餐和速率限制

Chaingateway 的 Bitcoin API 是一个 REST API,开发者无需运行全节点,就能接收和发送 BTC。它通过 HTTPS 创建密码加密的钱包和存款地址,用一次 POST 请求广播付款。付款到账时,它会发送带 HMAC 签名的 Webhook。7 天免费试用无需 KYC 即可开始。

搜索 Bitcoin API,第一个结果通常是 Bitcoin Core 的 RPC 参考文档。它是这条网络的规范接口,并且假定你在运行一个完整节点。

你要安装 bitcoind,同步数百 GB 的链数据,让机器保持在线,并在每次发布时重复升级周期。对某些项目来说,这是正确的路径。但如果你只是想在应用中接受 BTC 付款,这就绕了远路。

Chaingateway 的 Bitcoin API 是 REST 版的替代方案:进去是 HTTPS,出来是 JSON。认证方式是 Bearer 令牌。无需运行节点,开始时也无需 KYC。

一笔 Bitcoin 付款如何到达我的应用?

付款以带签名的 Webhook 形式到达你的应用。你先通过 REST API 创建存款地址。API 监视 Bitcoin 网络,再把存款事件发送到你的服务器。

流程图:你的应用向 Chaingateway API 发送 REST 请求,API 从 Bitcoin 网络读取数据并发送交易。存款到账时,API 会向你的服务器发送带签名的 Webhook。 你的应用 REST 请求 通过 HTTPS Chaingateway API Bearer 令牌, JSON 响应 Bitcoin 网络 主网或测试网 (X-Network 头) REST 读取并发送 Webhook 你的服务器 存款时接收 带签名的 Webhook
请求发往 API。存款事件以带签名的 Webhook 返回。

通过 REST 使用 Bitcoin,而不是 JSON-RPC

Bitcoin Core 的 JSON-RPC 需要一个已同步的节点,才能给出第一个有用的响应。REST API 需要的是一个 API 密钥。这个区别会体现在你的日程表上。在典型硬件上,初始区块下载需要数天。

之后节点还会持续占用磁盘和带宽,并在产品存续期间一直需要监控。我们关于 blockchain API 与 blockchain node 对比的文章详细比较了这两种方式。当你需要对网络视图拥有策略层面的控制权时,运行自己的节点。当支付才是目标时,使用 API。

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

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

使用 bitcoin-core RPC 需要做什么,并排对比

一旦把实际工作列出来,这个对比就变得具体了。假设任务是「为每个客户提供一个存款地址,并在 BTC 到账时为其账户入账」。

任务使用 Bitcoin Core(JSON-RPC)使用 REST API
前提条件一个已同步的完整节点:bitcoind 加上几百 GB 的链数据一个 API 密钥
新的存款地址每个客户调用一次 getnewaddress,外加你自己写脚本实现的钱包备份机制POST /api/v2/bitcoin/wallets/{wallet}/addresses
检测传入 BTC配置 walletnotify,或者定时轮询 listsinceblock / gettransaction签名的 Webhook POST 发送到你的服务器
发送 BTCsendtoaddress,外加节点中的热钱包、你自己掌控的手续费设置和钱包文件备份POST /api/v2/bitcoin/transactions
追踪确认数反复轮询 gettransaction,直到确认数满足你的策略轮询 GET /api/v2/bitcoin/transactions/{txid}/decoded,其中携带确认数
审计追踪解析 listtransactions 的输出并在自己的代码中去重GET /api/v2/bitcoin/webhooks/notifications
持续成本磁盘、带宽、升级、监控提供商的问题

出账付款值得更仔细地看一看。sendtoaddress 看起来只是一次调用。但它假定节点内有一个热钱包、手续费设置由你掌控,并且钱包文件有经过测试的备份。即便是 getbalance 也比看起来更窄。它报告的是节点钱包的余额,而不是任意地址的余额,因此交易所式的记账工作仍然落在你的代码里。

这些都不是在批评 Bitcoin Core。它是运营这条网络的参考软件,并且在这项工作上表现出色。它从来就不是为 Web 应用的支付后端而设计的。这也是为什么围绕它会积累这么多胶水代码。

通过 REST 发送 BTC

发送路径的 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 会从金额中扣除网络手续费,而不是额外叠加。这在客户提取全部余额时很有用。

这就是完整的发送调用——创建账户,用你自己的钱包在测试网上运行它。

接受 BTC 所需的一切

Webhook(IPN)

面向传入交易的即时支付通知,在匹配的交易在链上结算后立即发送。在你的个人资料中设置一个私密密钥。

之后每条通知就会携带一个可供你的服务器验证的 X-Signature 请求头。投递失败的记录列在 GET /api/v2/bitcoin/webhooks/notifications/failed。一次调用即可重新发送。

可预测的 REST 接口

用简洁、一致的 API 创建地址并追踪付款。请求和响应的风格与 Chaingateway 平台的其他部分一致。因此已经对接过一条链的开发者无需说明书就能读懂 Bitcoin 的响应。

安全的地址处理

从设计上就是非托管的,并内置地址校验。格式错误或拼写错误的地址会在触碰链之前就被拒绝。

解码后的查询

交易数据以结构化 JSON 返回,而不是原始十六进制。其中包含你后端需要据以行动的金额和确认状态。

在 Bitcoin 上应等待多少次确认?

小额付款等待 1 次确认(约 10 分钟)。中等金额等待 3 次,大额等待 6 次(约 1 小时)。

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

付款金额建议等待的确认数
小额,约 1,000 美元以内1(约 10 分钟)
中等,约 10,000 美元以内3(约 30 分钟)
大额6(约 1 小时)
超大额,超过 100 万美元10 次或更多

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

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

难度调整会让它在长期内保持稳定。但单次间隔围绕这个平均值大幅波动:一分钟内出两个区块会发生,四十分钟没有区块的情况也会发生。

支付体验设计必须尊重这一点。「大约十分钟」是一个平均值,不是一个承诺。因此你的结账页面应该写「通常在一小时内」,而不是运行一个它无法遵守的倒计时。

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

因为在交易被打包进区块之前,它停留在内存池(mempool)中,在那里可能被替换或双花。即使是最新的区块,也可能在链重组中被移出主链。API 把这项工作拆成两部分。Webhook 会在交易于链上结算的那一刻触发,payload 携带金额、地址、txid 和区块号。

因此你的界面可以立即做出反应。之后,GET /api/v2/bitcoin/transactions/{txid}/decoded 返回当前的确认数。这让你的账本只为达到你设定阈值的资金入账。及早展示进度,延后完成结算。

为什么 Bitcoin 的存款不同于 EVM 链?

比特币没有账户余额。链上存储的是未花费的交易输出(UTXO),所以一次存款是一个新的输出,而不是某个账户余额上的增量。每个 UTXO 都是锁定在某个地址上的一小笔独立价值。一个钱包的「余额」是你的软件通过汇总其地址控制的每一个 UTXO 计算出来的数字。

协议本身从不在任何地方存储这个总和。花费会消耗整个 UTXO 并创建新的 UTXO,包括返还给自己的找零输出。就像用一张十欧元纸币支付一笔七欧元账单会找回零钱一样。

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

对存款处理而言,UTXO 模型有一个实际的优势。它天然引导你为每位客户或每张发票使用一个地址,而这本来就是更干净的设计。每一笔传入付款都是发往你所监控地址的一个新输出,因此归属是明确无歧义的。无需解析备注,无需按金额匹配。

这也意味着「某个地址的余额」是一个由索引器而不是链本身回答的问题。这正是你通过使用带 Webhook 的 API、而不是自己搭建这套机制所外包出去的记账工作。通知会告诉你:这笔金额、这个地址、这笔交易、这个区块。剩下的交给你的账本。

存款流程,逐步说明

Chaingateway 上大多数比特币集成都围绕存款展开。每个客户一个地址,每笔付款一个 Webhook。

  1. 从你的钱包为每位客户分配一个存款地址(POST /api/v2/bitcoin/wallets/{wallet}/addresses)。
  2. 客户发送 BTC。
  3. 一旦交易在链上结算,Chaingateway 会向你的服务器 POST 一条签名通知。通知携带金额、地址、txid 和区块号。
  4. 你的后端验证签名。确认数从 GET /api/v2/bitcoin/transactions/{txid}/decoded 读取,达到你的阈值后,再为账户入账。

有两点实现细节需要注意。投递并非严格恰好一次:你通过 API 重新发送的一条失败通知会完整地再次到达。

因此要让你的处理程序具备幂等性,并以交易 ID 而不是回调次数作为入账的键。同时确认数的存在是有原因的:最新的区块仍可能在重组中被孤立。这也是为什么入账决策应该基于确认数,而不能仅凭 Webhook。

把每一笔存款建模为一个小型状态机,而不是一个布尔值会很有帮助。一个订单从 awaiting_payment 开始。Webhook 触发时进入 detected。

在你的轮询器监视确认数期间经过 confirming。达到阈值后落到 settled。underpaid 和 expired 是明确的旁路出口。有些客户会针对 0.001 BTC 的发票只发送 0.00095 BTC,通常是因为他们的钱包从输入金额中扣除了网络手续费。

请提前决定你的容忍度:是吸收这个差额,还是让订单等待补足差价。并为发票设置有效期。汇率在变动,因此周一与发票金额匹配的地址,不应该在下一周按过时的价格结算。

为便于审计和对账,你的账户收到的每一条通知都可以通过 API 列出:

cURL
curl https://app.chaingateway.io/api/v2/bitcoin/webhooks/notifications \
  -H "Authorization: Bearer YOUR_API_KEY"

先用 Testnet

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

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

Bitcoin API 调用失败时该怎么办?

任何 4xx 响应(包括 401)都要先修正请求。5xx 响应和超时则用退避策略重试。支付后端的价值恰恰体现在糟糕的日子里,所以要明确规划失败路径。

在 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。

需要在 BTC 之外支持稳定币?

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

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

为什么开发者选择在 Bitcoin 上构建

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

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

为真实支付场景而生

最明显的场景是收银台:客户选择比特币,你的应用分配一个地址;Webhook 确认付款。同样的构建模块也能承载更重的负载。

交易所和游戏平台为每位用户运行一个存款地址,在确认后为余额入账。付款和汇款流程无需中间的代理银行即可推动跨境转账。订阅业务在每个周期生成一个全新的发票地址,让 Webhook 完成收尾。

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

三步完成集成

Step 1

获取你的 API 密钥。注册免费,试用期开始时无需 KYC。

Step 2

发出你的第一个请求。用 GET /api/account 确认密钥有效,然后创建一个钱包和你的存款地址。

Step 3

设置 Webhook 并上线。把通知指向你的接口,验证 HMAC 签名,然后移除 X-Network: testnet 请求头。同样的代码就能运行在主网上。

各条链支持哪些功能

Bitcoin 是唯一没有代币转账列的一行。这条链没有代币标准,因此原生 BTC 通过自己的钱包模型运行,而不是通过类似 ERC-20 的调用。以下是它与其他六条链的对比。

链地址代币转账存款 Webhook
BitcoinPOST /api/v2/bitcoin/wallets/{wallet}/addresses—(无代币标准)GET /api/v2/bitcoin/webhooks/notifications
EthereumPOST /api/v2/ethereum/addresses/importERC-20:POST /api/v2/ethereum/transactions/erc20GET /api/v2/ethereum/webhooks/notifications
TRONPOST /api/v2/tron/addresses/importTRC-20 和 TRC-10:POST /api/v2/tron/transactions/trc20 和 .../trc10GET /api/v2/tron/webhooks/notifications
SolanaPOST /api/v2/solana/addressesSPL:POST /api/v2/solana/transactions/SPL—
BNB Smart ChainPOST /api/v2/bsc/addresses/importBEP-20:POST /api/v2/bsc/transactions/bep20GET /api/v2/bsc/webhooks/notifications
PolygonPOST /api/v2/polygon/addresses/importERC-20:POST /api/v2/polygon/transactions/erc20GET /api/v2/polygon/webhooks/notifications
ArbitrumPOST /api/v2/arbitrum/addresses/importERC-20:POST /api/v2/arbitrum/transactions/erc20GET /api/v2/arbitrum/webhooks/notifications

正确理解此表需要两点说明。第一:TRON 是平台上集成最深的链。

除上述路由外,参考文档还记录了质押(POST /api/v2/tron/freeze 和 /delegate)和链参数。另有一对自签名接口:/transactions/trc20/build 用于构建交易,/transactions/broadcast 用于提交本地签名后的交易。如果你的合规团队坚持要求私钥永远不离开你的服务器,就用这种 build-and-broadcast 模式。

第二:表格中的破折号表示当前参考文档尚未记录该单元格对应的 v2 路由。这并不意味着该网络是二等公民。Bitcoin 没有代币标准,因此代币列为空。原生 BTC 通过自己的钱包模型运行:使用 POST /api/v2/bitcoin/wallets 创建密码加密的钱包,在其下派生存款地址。

再通过 POST /api/v2/bitcoin/transactions 发送。Solana 的参考文档涵盖地址创建、SOL 和 SPL 转账,以及余额和区块查询。它尚无 Webhook。此处未列出的内容,请参阅 API 参考文档 获取当前状态。

来源与延伸阅读

以下一手资料记录了本页所述的标准和链上行为:

常见问题

可以。这可以作为一个 Bitcoin payment API 使用:为每位客户生成一个存款地址,注册一个 Webhook,在传入 BTC 确认后为订单入账。无需运行完整节点,也无需托管方。付款通过 POST /api/v2/bitcoin/transactions 发出。整个收款和结算循环都通过 REST 完成。

钱包受密码保护并加密存储,架构是非托管的:没有你的凭据,资金就无法被转移。

不需要。Chaingateway 负责运营基础设施;你的应用只需说 HTTPS。如果你正在权衡自建节点与使用 API,我们的节点对比文章诚实地介绍了运维方面的成本。

支持。在任意请求中添加 X-Network: testnet,它就会运行在测试网络上。接口和响应格式相同,只是代币没有价值。

这取决于你的风险承受度。Webhook 告诉你付款已结算。当前确认数来自 GET /api/v2/bitcoin/transactions/{txid}/decoded。因此你可以按金额设定阈值:小额订单可能在第一次确认后就发货,大额提现则在多次确认之后。上面的出块时间部分列出了大多数平台使用的阈值。

区块平均大约每十分钟到达一次,但波动范围很大。手续费充足的交易平均十分钟后获得第一次确认;经典的六次确认标准大约需要一小时。手续费水平也很重要。在网络繁忙期间手续费不足的交易,等待第一个区块的时间会更长,有时长达数小时。

重组是用一条竞争链取代最新的一个或多个区块。任何仅存在于被替换区块中的交易都会回到待处理状态。单区块重组很少见,更深的重组则更加罕见,但这正是确认数阈值存在的原因。只有在达到你的阈值后才入账,重组就只是一个统计数字,而不是一次事故。

归属问题。在共用地址上,你必须按金额或时间将付款与客户匹配。而当两张发票金额恰好相同时,这种匹配方式就会失效。专属地址让每一笔传入输出都能自我标识。由于创建地址不花任何成本,没有理由在这上面精打细算。

处理商通常会托管资金、延后结算,并在付款前要求 KYC。Chaingateway 是构建在链本身之上的 API。存款落在与你自己钱包绑定的地址上,接下来发生什么由你的代码决定。你得到的是原始的构建模块,而不是一套带主观倾向的收银方案。

可以。同一个 API 覆盖 Ethereum、TRON、Solana、BNB Smart Chain、Polygon 和 Arbitrum。路由之间只有链名段不同。

套餐及其限额列在定价页面上。每个套餐都以免费的 7 天试用开始。评估的最快方式是在测试网上跑一遍:创建账户,把 Webhook 指向一个 request bin,给自己发送测试 BTC。如果流程合适,只需一个请求头就能切换到主网。

准备好接受比特币支付了吗?

在 app.chaingateway.io/register 创建账户。创建一个钱包,并在测试网上发送一笔 BTC 转账。完整接口参考见 文档,套餐和速率限制在单独的页面上。

审核: Maurice Sobiera 我们如何撰写这些页面