# 用 AI 接入 · blockwallets

> 不会写代码也能接入 blockwallets 加密货币收款：选好网站类型和 AI 工具，复制生成的提示词交给 Claude Code、Codex、Cursor 或 ChatGPT，它会照文档接好并按验收清单自查。
>
> HTML: https://blockwallets.io/docs/ai · English: https://blockwallets.io/docs/ai.md?lang=en

## 一键通用提示词

```text
请帮我在我的网站上接入 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 里的验收清单逐项自查，每一项告诉我结果。

我不太懂编程，每一步请告诉我改了什么、需要我做什么。
```

## 说说你的情况。

选不准就选“其他 / 不知道”，AI 会先看你的项目再说。

- 网站用什么做的: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · 其他 / 不知道
- 想怎么收款:
  - 下单跳转付款页: 下单时建账单，到账后通知你的服务器，自动发货。
  - 每个用户一个固定充值地址: 用户拿到专属地址，随时充任意金额。
  - 收款链接（不写代码）: 在后台建链接直接发给客户，AI 只帮你加个按钮。

收款链接本身不用写代码：商户后台 →「收款 › 收款链接」→ 填金额 → 创建，把链接发给客户就能收。AI 只帮你把按钮放到网站上。

## 你用哪个 AI？

- **Claude Code / Codex**: 能直接改代码、跑命令的 AI，最省事。
  - 在网站项目的根目录打开终端，运行下面这行，把接入规则存成 AGENTS.md：
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Codex 会自动读 AGENTS.md。用 Claude Code 的话，再运行一行：
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - 然后把第 3 步生成的提示词贴给它。
  - 也可以装 blockwallets MCP，AI 能直接查文档、建测试单。 https://blockwallets.io/docs/mcp
- **Cursor / Windsurf / Copilot**: 在代码编辑器里干活的 AI。
  - 同样把 AGENTS.md 放到项目根目录（Cursor 会自动读取）：
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - 切到 Agent 模式，把提示词贴进去。
  - 也可以装 blockwallets MCP，AI 能直接查文档、建测试单。 https://blockwallets.io/docs/mcp
- **ChatGPT / Claude 网页版**: 只能聊天，代码要你自己放进网站。
  - 把提示词贴进一个新对话，或者用下面的“在 ChatGPT 中打开 / 在 Claude 中打开”。
  - 如果它说打不开链接：打开 https://blockwallets.io/llms-full.txt，全选复制，一起贴给它。
  - 它会给出完整代码和放的位置，照着一步步做。换成能直接改代码的工具（Claude Code、Codex、Cursor）会省掉很多复制粘贴。
- **其他 AI**: Gemini、豆包、Kimi 等。
  - 把提示词贴进去。它打不开网页的话，把 llms-full.txt 的内容一起贴给它。

## 复制提示词。

提示词会随上面的选择实时变化，里面带着文档地址、最容易出错的几处和一份验收清单。

例：其他 / 不知道 + 下单跳转付款页 + Claude Code / Codex

```text
你是我的开发助手。请帮我在我的网站上接入 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 做完后，对照这几项

**下单跳转付款页**

1. 用 Test 凭据建一张测试账单，拿到付款页链接（result.url）
2. 打开付款页，点「模拟付款」→ 付全款
3. 我的服务器收到 status 为 paid 的回调，验签通过
4. 对应订单被标记为已付
5. 同一条回调再到一次（在商户后台「开发者 › 回调日志」里重发，或调 POST /v1/payment/resend），不会重复发货

**每个用户一个固定充值地址**

1. 用 Test 凭据给一个测试用户开地址，拿到地址和充值页链接
2. 调 POST /v1/test-webhook/wallet 发一条样例回调
3. 我的服务器收到 type 为 wallet 的回调，验签通过
4. 这个用户的余额按 payment_amount_usd 增加
5. 同一条回调再到一次，余额不会重复增加

**收款链接（不写代码）**

1. 按钮在电脑和手机上都显示正常
2. 点按钮打开的是我的收款链接（先用后台 Test 模式建的链接）
3. 在付款页点「模拟付款」后，后台「收款 › 收款记录」里能看到这一笔

## AI 卡住了怎么办。

- **验签总是不过**: 把收到的原始回调体贴进[在线验签](https://blockwallets.io/docs/sign)，它会列出每一步的中间结果并标出第一处不同。把这个差异原样告诉 AI。
- **接口报错**: 把请求和应答原文（包括 message）贴回给 AI。签名不对时，401 应答里的 debug.body_base64 是我们算签名用的原文，让 AI 和它自己的对比。
- **不知道卡在哪**: 让 AI 按验收清单从第一项开始，一项一项做，每项做完告诉你结果。商户后台「开发者 › 回调日志」里能看到每次回调的请求和你服务器的应答。

### 四件事，自己把关。

- **只给 AI 测试凭据**: Test 的 merchant 和 API key 跑在测试网上，泄露了也动不了钱。
- **正式 API key 不进聊天**: Live 的 API key 自己填进服务器的环境变量，不要贴进任何聊天框或提交到代码仓库。
- **改代码前先备份**: 让 AI 动手之前先提交一次（git commit）或复制一份网站文件，改坏了能退回去。
- **上线前自己付一笔**: 换成 Live 后，从商户后台首页的「试一笔」付一小笔真币，确认订单变成已付、余额到账，再对外开放。

## 给编程 agent 的规则文件。

AGENTS.md 里是接入要点、常见坑和验收清单。放进项目根目录，Codex、Cursor 会自动读，Claude Code 用 @AGENTS.md 引入。

```sh
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md
echo '@AGENTS.md' >> CLAUDE.md
```

- [接入规则（AGENTS.md）](https://blockwallets.io/agents.md)
- [一页概览](https://blockwallets.io/llms.txt)
- [完整文档](https://blockwallets.io/llms-full.txt)
- [本页 Markdown](https://blockwallets.io/docs/ai.md)
- [接入文档 Markdown](https://blockwallets.io/docs.md)
- [MCP server](https://blockwallets.io/docs/mcp)

## 常见问题。

### 不会写代码，真的能用 AI 接好吗？

大多数网站可以。AI 照着文档写建单和验签代码，你负责把凭据填进环境变量，再按验收清单在测试模式里点一遍。完全不想碰代码的话，用收款链接就行。

### 该用哪个 AI 工具？

能直接改项目代码、能跑命令的工具最省事，比如 Claude Code、Codex、Cursor。网页版 ChatGPT 或 Claude 也能用，只是代码要你自己放进网站。

### 要把 API key 给 AI 吗？

只给 Test 凭据，而且放进环境变量文件，不要贴进聊天。Live 的 API key 由你自己填到服务器上。

### 验签总是不过怎么办？

回调验签要先去掉 sign，再按 PHP json_encode 的方式重新编码，/ 要转成 \/。把原始回调体贴进 /docs/sign 对比每一步，再把差异告诉 AI。

### AI 说接好了，怎么确认？

按验收清单走一遍：建测试单、点模拟付款、回调验签通过、订单变成已付、重发同一条回调不会重复发货。上线前再用 Live 付一小笔。