vouch

Vouch

面向 AI Agent 的按次付费信任与信誉 API——通过 x402 实现收费。

自主 Agent 即将向商家、API 或交易对手付款时，会先向 Vouch 提出一个问题：付款安全吗？ Vouch 会返回可解释的信任评分，并按次收取不到一美分的 USDC——无需账户、无需 API 密钥，也无需 Stripe。计费本身就是 x402 协议。

为什么要做

代理商务的基础设施（Coinbase x402、AWS、Visa、Mastercard、Agnic）正由巨头打造。治理层——Agent 是否应该信任这个交易对手并向其付款？——是自主支出的首要障碍，目前仍是一片蓝海。Vouch 是构建在这些基础设施之上的轻量自助工具。

每次调用都会让产品变得更好：检查记录和社区举报不断积累，形成随使用而增长的信誉数据集——这是资源有限的团队真正能够建立的护城河。

工作原理

agent ──POST /v1/check { target }──▶  x402 paywall (402 → pay USDC → retry)
                                          │
                                          ▼
                          ┌─────────── scoring engine ───────────┐
                          │ transport · domain heuristics ·       │
                          │ threat feed · reputation (D1)         │
                          └───────────────────────────────────────┘
                                          │
                            { score, risk, reasons[] }

评分是多个独立信号的加权平均，并设有安全覆盖机制：任何单个强负面信号（例如命中威胁源）都会限制总分，避免一个严重危险信号被平均掉。

信号	权重	来源
threat_feed	3	URLhaus 主机列表（THREAT_FEED_URL），带缓存，获取失败时放行
reputation	2	Vouch 自身持续积累的 D1 数据（护城河）
transport	1.5	HTTPS / 有效主机
domain_heuristics	1	Punycode、裸 IP、易被滥用的顶级域名等

在你的 Agent 中使用

Vouch 提供真正的 MCP 服务、通过 x402 付费的 HTTP API，以及一个小巧的 SDK——选择适合你技术栈的方式即可。使用时无需账户或 API 密钥。

MCP（免费工具，适用于任何 MCP 客户端）

将客户端指向 Streamable-HTTP 端点——该端点提供 vouch_score 和 vouch_report，并附带面向模型的 instructions，让 Agent 知道应在付款之前检查交易对手：

{
  "mcpServers": {
    "vouch": { "type": "streamable-http", "url": "https://vouch.futuronoti.workers.dev/mcp" }
  }
}

对于仅支持 stdio 的客户端，可使用 npx mcp-remote https://vouch.futuronoti.workers.dev/mcp 进行桥接。Vouch 也已列入官方 MCP 注册表，名称为 io.github.notifuturo/vouch。

免费 HTTP（curl）

curl -s https://vouch.futuronoti.workers.dev/v1/score \
  -H 'content-type: application/json' -d '{"target":"https://some-merchant.com"}'
# → {"target":"...","host":"some-merchant.com","score":91,"risk":"low"}

使用 SDK 为付款设置门槛（一行代码）

import { assertTrusted } from "vouch-sdk";

await assertTrusted("https://some-merchant.com", { minScore: 75 }); // free; throws if risky
await payTheMerchant();

付费的 POST /v1/check 会额外提供可解释的 reasons、加权后的 signals，以及经过 Ed25519 签名的证明（可将其保留为尽职调查凭据）。完整的 x402 付费与重试流程见 examples/buyer.ts，客户端见 sdk/。

端点

方法和路径	费用	描述
POST /v1/check	x402（USDC）	完整判定 → { score, risk, reasons, signals, attestation }（已签名的 Ed25519 收据）
POST /v1/score	免费（有速率限制）	仅返回评分和风险 → { score, risk }。如需原因，请支付费用调用 /v1/check
GET /v1/attestation/pubkey	免费	Ed25519 公钥（JWK），用于验证 /v1/check 的 attestation
POST /v1/report	免费	为某个主机提交 flag 或 vouch
GET /v1/stats	免费	汇总信誉统计（主机、检查、标记、背书）
POST /mcp	免费	MCP Streamable-HTTP 服务（vouch_score、vouch_report 工具）
GET /health	免费	存活状态
GET /	免费	服务信息（面向浏览器的 HTML 落地页）

CORS 对所有来源开放（*），并且 x402 支付标头已公开，因此托管在浏览器中的 Agent 可以预检并完成支付/重试流程。

解读 /v1/report（滥用模型）

POST /v1/report 按设计免费且无需身份验证——任何人都可以为某个主机提交 flag 或 vouch，因此原始的 flags/vouches 计数是社区信号，而非事实依据。滥用行为通过以下方式得到遏制：

• 速率限制 — 每个客户端 IP 每 60 秒最多提交 10 份报告（Cloudflare Rate Limiting，故障时默认拒绝）。
• 基于报告者信誉的加权 — 每份计入统计的报告按权重贡献数值 （而非固定的 +1），权重取决于报告来源的资历：全新或匿名来源的计数权重为 0.3，只有持续报告约 7 天后才会逐步升至 1.0。评分信号使用这些加权总数，因此创建全新的女巫身份能获得的影响力要小得多。每个来源每 24 小时最多只能改变某个主机的计数器一次（按来源去重）；原始计数仍会记录，以供审计。
• 评分抗投毒 — 社区 reputation 是非权威信号：它可以降低评分，但单独无法强制判定为 critical。 只有客观信号（威胁情报源、传输）才能对评分设置硬性上限。因此，一阵匿名标记无法单方面将合法的交易对手列为不安全。
• 输入长度限制 — 存储前会限制 target/reason/reporter 的长度。

应将 /v1/stats 和报告计数视为影响付费判定的众包先验信息，而非权威封锁列表。

技术栈（运行成本为 $0）

TypeScript · Hono · Cloudflare Workers（免费套餐）· D1（免费 SQLite）· @x402/* v2 · 公共 facilitator：x402.org/facilitator。

已在 Base 主网运行（X402_NETWORK=base，使用真实 USDC，每次调用 $0.01）。本地开发时， 请设置 X402_NETWORK=base-sepolia，并通过免费的 Circle 水龙头为临时钱包充值。实时网络和价格会在 /.well-known/x402 中以权威信息发布。

开发

npm install
npm run typecheck
npm test

cp .dev.vars.example .dev.vars   # set PAY_TO_ADDRESS (your testnet wallet)
wrangler d1 create vouch         # paste database_id into wrangler.toml
npm run db:init                  # apply schema locally
npm run dev                      # local Worker

许可证

MIT — 详见 LICENSE。