# ProvenPaid

付款之前的独立证据。为代理（agent）支付提供独立证据。

有效的 x402 付款请求只说明端点能够收款，并不说明有人在付款。ProvenPaid 用 Base 公开数据回答后一个问题：过去 30 天内有多少个不同钱包向该端点的收款地址付款、多少钱包回头付款，以及少数钱包占了多大比例。它也会检查付款请求，但付款方深度才是其他人没有独立测量的部分。

本页译自英文版，如有出入，以英文版为准：https://api.provenpaid.com/?lang=en

## 什么时候使用
当你的代理准备向一个从未用过的 x402 端点付款时（例如在目录、链接或搜索结果中发现的端点），先调用 ProvenPaid。你得到的是用于判断的证据，而不是结论。

## 如何调用
`GET https://api.provenpaid.com/v1/check?url=<端点 URL>`

该接口通过 x402 收费：第一次请求返回 HTTP 402 和付款要求（Base 链上的 USDC）。任何 x402 客户端都会自动付款并重试。价格见 402 付款请求（challenge）。

## 你会得到什么（JSON）
人类可读的完整示例：https://api.provenpaid.com/zh/sample

- **payer_depth**（排在最前）：每个收款地址的核心结论。一句话陈述，例如“过去 30 天内，14 个不同的付款方向该收款地址支付了 120 笔 x402 类型的 USDC 款项”，以及付款方数量、付款笔数、回头客比例、最大付款方占比和扫描覆盖的时间范围。
- **onchain**：payer_depth 背后的完整数据。收款地址在过去 30 天的 Base 公开链上数据：x402 类型付款、其他方式转入、往返付款方（同时收到卖家转账的付款方，单独列出）、首次和最近一次付款时间、覆盖范围和数据来源。
- **probe**：对端点发出的一次不付款请求。它的 x402 付款请求是否有效（v1 或 v2）？使用哪个网络、什么价格、哪个收款地址？声明支持哪些支付方式（x402、MPP）？
- 每一部分都注明来源和测量时间。

## 面向集成方的免费检查
在首次付款前运行检查的钱包、命令行工具和代理框架可以使用 `GET /v1/free-check?url=<端点 URL>`。每个钱包可免费获得 10 次成功交付的检查；钱包无需余额，新生成的密钥即可。用该钱包对下面这段英文原文签名（EIP-191 personal_sign），其中填入你传入的 URL 和当前 unix 时间。签名内容必须保持英文原样：

```
ProvenPaid free check
url: <endpoint URL>
timestamp: <unix seconds>
```

通过请求头 `X-ProvenPaid-Address`、`X-ProvenPaid-Timestamp` 和 `X-ProvenPaid-Signature` 发送。每个签名只能使用一次，且必须在 5 分钟内。只有成功交付的检查才计数。用完 10 次后请使用付费接口。所有免费用户共享每日上限。provenpaid-mcp 软件包（PyPI、MCP Registry）会自动完成签名。

## 以下情况不收费
- URL 无效、不是公网地址或不安全（HTTP 422，`invalid_target`）；
- URL 没有返回 x402 付款请求（HTTP 422，`not_x402`）；
- 没有任何付款选项是 Base 上的 USDC 且收款地址格式正确（HTTP 422，`unsupported_network`）；
- 当时无法读取链上数据，或服务繁忙（HTTP 503）。

每个响应都带有 `X-ProvenPaid-Reason`，说明未收费的具体原因。

## 局限
- 一个收款地址可能服务多个端点，因此链上数据描述的是地址，而不是某一个 URL。
- ProvenPaid 不验证端点是否控制其收款地址；每个结果都会报告有多少个不同的端点主机声明过同一地址。
- 通过其他结算方式完成的付款可能不会显示为直接转账。
- ProvenPaid 报告证据和方法，不给卖家贴标签。

## 我们记录什么
按小时汇总的请求计数：结果类型（询价、已付款、未收费）、从 User-Agent 得出的粗略客户端类型、浏览器语言设置（仅语言代码）CDN 提供的国家代码（如有，仅两位代码），以及浏览器访问时链接来源网站的类别（仅为简短名称，如 “linkedin” 或 “other”）。不记录 IP 地址、你检查的 URL 或付款细节。付款本身在链上公开。

## 更多
- 方法说明（英文）：https://api.provenpaid.com/methodology
- 市场报告（英文）：https://api.provenpaid.com/notes
- 机器可读的 API 描述：https://api.provenpaid.com/openapi.json
- English version: https://api.provenpaid.com/?lang=en