验签总是不过
把收到的原始回调体贴进在线验签,它会列出每一步的中间结果并标出第一处不同。把这个差异原样告诉 AI。
不会写代码也没关系。选好你的网站和 AI 工具,把生成的提示词交给它,它会照着文档接好收款,再按验收清单逐项自查。
一键通用提示词 · 不用选任何东西
请帮我在我的网站上接入 blockwallets 加密货币收款(客户用 USDT、USDC、BTC 等付款,按美元入账)。 1. 先读文档,不要凭记忆猜接口:https://blockwallets.io/llms-full.txt(完整文档)和 https://blockwallets.io/agents.md(接入规则、常见坑、验收清单)。打不开就告诉我。 2. 看看我的项目是用什么做的,告诉我你打算怎么接,等我确认再动手。 3. 默认用“下单跳转付款页 + 回调通知”的方式。回调一定要验签;同一条回调可能重复到达,要去重。 4. merchant 和 API key 放环境变量,先用 Test 凭据在测试网跑通。 5. 做完按 agents.md 里的验收清单逐项自查,每一项告诉我结果。 我不太懂编程,每一步请告诉我改了什么、需要我做什么。
打开时会把完整提示词复制到剪贴板,链接里只带一句开场白;打开后粘贴即可。
第 1 步
选不准就选“其他 / 不知道”,AI 会先看你的项目再说。
收款链接本身不用写代码:商户后台 →「收款 › 收款链接」→ 填金额 → 创建,把链接发给客户就能收。AI 只帮你把按钮放到网站上。
去商户后台第 2 步
不同工具读文档的方式不一样,照着对应的做。
在网站项目的根目录打开终端,运行下面这行,把接入规则存成 AGENTS.md:
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdCodex 会自动读 AGENTS.md。用 Claude Code 的话,再运行一行:
echo '@AGENTS.md' >> CLAUDE.md然后把第 3 步生成的提示词贴给它。
也可以装 blockwallets MCP,AI 能直接查文档、建测试单。看 MCP 安装说明 →
同样把 AGENTS.md 放到项目根目录(Cursor 会自动读取):
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md切到 Agent 模式,把提示词贴进去。
也可以装 blockwallets MCP,AI 能直接查文档、建测试单。看 MCP 安装说明 →
把提示词贴进一个新对话,或者用下面的“在 ChatGPT 中打开 / 在 Claude 中打开”。
如果它说打不开链接:打开 https://blockwallets.io/llms-full.txt,全选复制,一起贴给它。
它会给出完整代码和放的位置,照着一步步做。换成能直接改代码的工具(Claude Code、Codex、Cursor)会省掉很多复制粘贴。
把提示词贴进去。它打不开网页的话,把 llms-full.txt 的内容一起贴给它。
第 3 步
提示词会随上面的选择实时变化,里面带着文档地址、最容易出错的几处和一份验收清单。
你是我的开发助手。请帮我在我的网站上接入 blockwallets 加密货币收款(客户用 USDT、USDC、BTC 等 17 种币付款,按美元入账)。 ## 我的情况 - 网站技术栈:我不确定。请你先看一下我的项目,告诉我它是用什么做的,再动手。 - 收款方式:下单时创建账单,把客户跳转到 blockwallets 的付款页;钱到账后 blockwallets 回调我的服务器,我把订单标记为已付并发货。 - 我不太懂编程。每一步请告诉我你改了哪些文件、需要我做什么(比如环境变量填在哪里),不要一次改太多。 - 项目根目录的 AGENTS.md 是 blockwallets 的接入规则,请先读它;要查细节时读 https://blockwallets.io/llms-full.txt。 ## 先读文档,不要凭记忆猜接口 - 完整接入文档(Markdown):https://blockwallets.io/llms-full.txt - 接入规则与常见坑:https://blockwallets.io/agents.md - 网站原来接的是 Cryptomus、NOWPayments 或 Coinbase Commerce 的话,改用对应的兼容接口,不要重写:https://blockwallets.io/docs/migrate.md?lang=en - 打不开链接就告诉我,我把内容贴给你。 ## 要点(最容易出错的地方) 1. 所有接口都是 POST + JSON,基础地址 https://blockwallets.io。请求头 merchant = 商户 UUID,sign = md5(base64(请求体) + API key)。签名用的必须是实际发出去的那串 JSON,不要签完再重新序列化。 2. 建单:POST /v1/payment,必填 amount(字符串,最多两位小数,如 "42.00")、currency("USD")、order_id(我的订单号,字母、数字、- 和 _,最长 100 字符);同时传 url_callback(回调地址)和 url_success(付完回到哪里)。把客户跳转到返回的 result.url。 3. 同一个 order_id 再调用会返回同一张账单,可以放心重试,不会重复建单。 4. 回调验签必须做:取回调 JSON,去掉 sign 字段,按 PHP json_encode 的方式重新编码(紧凑、不转义中文、/ 转成 \/),再算 md5(base64(编码结果) + API key),必须等于 sign。/ 没转义是最常见的坑。 5. 只在 status 是 paid 或 paid_over 时,按 payment_amount_usd 把订单标记为已付。同一条回调可能重复到达,按 uuid + status 去重;处理完返回 2xx。 6. merchant 和 API key 放环境变量(比如 BW_MERCHANT、BW_API_KEY),不要写进代码,也不要提交到仓库。回调地址的域名要先在商户后台「开发者 › 接入与密钥」的网站域名里填上。 7. 先用 Test 凭据跑通(走测试网,不涉及真钱),我确认后再换 Live。 ## 做完后逐项自查,每一项告诉我结果 - [ ] 用 Test 凭据建一张测试账单,拿到付款页链接(result.url) - [ ] 打开付款页,点「模拟付款」→ 付全款 - [ ] 我的服务器收到 status 为 paid 的回调,验签通过 - [ ] 对应订单被标记为已付 - [ ] 同一条回调再到一次(在商户后台「开发者 › 回调日志」里重发,或调 POST /v1/payment/resend),不会重复发货 有任何一项没通过,先告诉我卡在哪一步、报错原文是什么,再动手改。
每一项都让 AI 告诉你结果,全部通过再换 Live。
卡住了
大多数问题出在签名上。把原文交给 AI,比描述现象有用得多。
把收到的原始回调体贴进在线验签,它会列出每一步的中间结果并标出第一处不同。把这个差异原样告诉 AI。
把请求和应答原文(包括 message)贴回给 AI。签名不对时,401 应答里的 debug.body_base64 是我们算签名用的原文,让 AI 和它自己的对比。
让 AI 按验收清单从第一项开始,一项一项做,每项做完告诉你结果。商户后台「开发者 › 回调日志」里能看到每次回调的请求和你服务器的应答。
安全提醒
Test 的 merchant 和 API key 跑在测试网上,泄露了也动不了钱。
Live 的 API key 自己填进服务器的环境变量,不要贴进任何聊天框或提交到代码仓库。
让 AI 动手之前先提交一次(git commit)或复制一份网站文件,改坏了能退回去。
换成 Live 后,从商户后台首页的「试一笔」付一小笔真币,确认订单变成已付、余额到账,再对外开放。
规则文件
AGENTS.md 里是接入要点、常见坑和验收清单。放进项目根目录,Codex、Cursor 会自动读,Claude Code 用 @AGENTS.md 引入。
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdecho '@AGENTS.md' >> CLAUDE.md给 AI 读的文件
常见问题
大多数网站可以。AI 照着文档写建单和验签代码,你负责把凭据填进环境变量,再按验收清单在测试模式里点一遍。完全不想碰代码的话,用收款链接就行。
能直接改项目代码、能跑命令的工具最省事,比如 Claude Code、Codex、Cursor。网页版 ChatGPT 或 Claude 也能用,只是代码要你自己放进网站。
只给 Test 凭据,而且放进环境变量文件,不要贴进聊天。Live 的 API key 由你自己填到服务器上。
回调验签要先去掉 sign,再按 PHP json_encode 的方式重新编码,/ 要转成 \/。把原始回调体贴进 /docs/sign 对比每一步,再把差异告诉 AI。
按验收清单走一遍:建测试单、点模拟付款、回调验签通过、订单变成已付、重发同一条回调不会重复发货。上线前再用 Live 付一小笔。