让现有 API 收取按次费用，不交出业务入口。

一个简单的执行顺序

1. 根据当前请求向 LavoLoop 创建 Challenge。
2. 没有付款签名时，把 paymentRequiredHeader 作为 HTTP 402 返回给调用方。
3. 有签名时，使用同一请求描述调用 Verify。
4. 验证成功后执行你的业务逻辑。
5. 业务成功后调用 Settle，再把 paymentResponseHeader 返回给调用方。

开始配置

在商家控制台提供 Base 收款地址，创建一个 API 服务，再为精确的方法和路径设定 USDC 价格。服务密钥只展示一次。

LAVOLOOP_API_URL=https://api.lavoloop.com
LAVOLOOP_SERVICE_TOKEN=lv_service_...

1. Challenge

POST、PUT、PATCH 必须提供 bodySha256；应对收到的原始字节计算小写十六进制 SHA-256。GET 与 DELETE 可省略。

POST https://api.lavoloop.com/v1/merchant/x402/challenges
Authorization: Bearer $LAVOLOOP_SERVICE_TOKEN
Content-Type: application/json

{ "request": {
  "method": "POST",
  "path": "/v1/render",
  "query": "format=png",
  "bodySha256": "<sha256-of-exact-request-bytes>"
} }

响应包含 challengeId、完整 paymentRequired，以及可以直接返回的 paymentRequiredHeader。

2. Verify

POST https://api.lavoloop.com/v1/merchant/x402/verifications
Authorization: Bearer $LAVOLOOP_SERVICE_TOKEN
Content-Type: application/json

{ "challengeId": "mch_...",
  "paymentSignature": "<PAYMENT-SIGNATURE header value>",
  "request": { "method": "POST", "path": "/v1/render",
    "query": "format=png", "bodySha256": "<sha256>" } }

验证成功会返回短时有效的 settlementToken。此时再执行业务操作。

3. Settle

POST https://api.lavoloop.com/v1/merchant/x402/settlements
Authorization: Bearer $LAVOLOOP_SERVICE_TOKEN
Idempotency-Key: <stable-key-for-this-business-operation>
Content-Type: application/json

{ "challengeId": "mch_...", "settlementToken": "lvst1...." }

成功响应包含链上交易与 paymentResponseHeader。相同 Idempotency-Key 的安全重试会返回同一笔结算。

失败与重试

• 业务失败：不要调用 Settle，付款不会被结算。
• 副作用业务必须在你自己的系统中使用幂等键。
• 同一付款签名不能用于不同路径、查询或正文摘要。
• 服务密钥泄漏后，从控制台轮换；旧密钥立即失效。

让商家的 Agent 帮你接入

仓库内提供 LavoLoop 接入 Skill。安装后，开发 Agent 会识别你的框架、接入三个端点、补幂等处理并运行测试。