assay

Assay

x402 Agent 经济的质量标尺 —— x402 是一种开放协议，可让机器使用稳定币进行小额支付，以调用 HTTP API。Assay 使用真实 USDC 探测支持机器支付的服务，验证实际返回的内容，并出售由此得出的质量评分——每项评分都有链上支付收据和锚定到 Bitcoin 的证据链作为凭证。

在线体验： assay.nominal-labs.com · 排行榜 · Agent 指南（SKILL.md）

问题

Agent 已开始通过 x402 向其他机器购买 API 响应——HTTP 402 支付挑战以 USDC 在 Base（Coinbase 的 Ethereum L2）上结算，无需账户，也无需发票。数以万计的服务已经在 Coinbase x402 Bazaar 等发现目录中发布信息。但持有钱包的 Agent 无从得知哪些服务确实能兑现承诺：支付是否成功结算、响应是否符合所宣传的架构、数据是否真实。现有的信任信号只评估运行状态——在线时间、延迟、支付遥测。没有人会向这些服务付费并验证实际返回的内容。付费验证是唯一真正有效的测试——因此 Assay 会按计划使用自己的资金进行测试，让你的 Agent 无需亲自承担。

评分机制

Assay 每天多次在随机时间，通过真实付费请求探测一组经过筛选的 x402 服务。每次探测都会根据四项独立检查进行评分：

组成部分	权重	检查内容
结算	40%	支付是否成功结算并返回响应？（记录交易哈希）
架构	30%	响应是否符合服务所宣传的输出架构？
真实数据	20%	数据是否与独立参考来源一致？
LLM 评审	10%	响应是否兑现了服务所宣称的内容？

权重会根据服务已有数据的组成部分重新归一化。服务的综合评分（0–100）根据其过去 30 天的探测结果计算，且只有在跨多个日期累计 20 次或更多探测后才会发布评分——证据不足时不评分。等级：金牌 ≥ 85，良好 ≥ 60，否则为应避免。

为什么历史记录无法被悄悄篡改

评分的可信度取决于其背后的证据，因此探测数据集只追加内容，并公开锚定：

• 每条探测记录（结算结果、响应哈希、支付金额、交易哈希）都会成为每日一棵 Merkle 树中的叶节点；安全延迟期过后，树根会通过 OpenTimestamps 锚定到 Bitcoin（OTS）。
• 每日 Merkle 树根及其 OTS 证明均公开发布在 /api/digests。
• 任何会影响已记录历史的操作——迁移、重新锚定——都会公开记录在 docs/CORPUS-LOG.md 中。

持续累积的数据集才是关键：任何人都可以复制代码，但没人能伪造证据的日期——锚定证明了每天的记录何时已存在。

使用 Assay

HTTP — oracle 本身是一个位于 https://assay.nominal-labs.com 的 x402 服务。 付费端点会返回 HTTP 402 付款挑战，任何 x402 客户端都可以自动完成结算：

端点	价格	返回内容
GET /score/{url-encoded service URL}	$0.005 USDC (Base)	综合评分、各项评分明细、趋势、探测次数
GET /tier/{url-encoded service URL}	免费	gold / ok / avoid / unrated 判定
GET /leaderboard	免费	所有已评分服务的排名
GET /api/digests	免费	每日 Merkle 根哈希 + OTS 证明

MCP 服务（Model Context Protocol — AI 助手调用外部工具的方式）— npm 和官方 MCP 注册表上的 assay-oracle-mcp。 用于 Claude Code：

claude mcp add assay -- npx -y assay-oracle-mcp

支出防护 — assay-x402-guard 会封装 Agent 的付费 fetch，并在资金转给评分为 avoid 的服务之前抛出异常：

import { wrapFetchWithAssay } from "assay-x402-guard";
// payFetch = your x402-paying fetch (e.g. wrapFetchWithPayment from @x402/fetch)
const safeFetch = wrapFetchWithAssay(payFetch);

更多背景信息：SUMMARY.md（是什么／为什么）和 docs/specs/（设计）。

开发（任何操作系统）

1. 执行 cp .env.example .env 并填写配置（示例文件中记录了所有变量）：
   • PROBE_WALLET_KEY：新建的专用钱包，在 Base 主网上存入不超过 $50 USDC（无需 ETH — x402“exact”通过 EIP-3009 签名由 facilitator 完成结算）
   • ANTHROPIC_API_KEY：LLM 评审器
2. 执行 npm install && npm test（测试套件无需网络或钱包）
3. 执行 npx tsx scripts/verify-env.mts — 预检；配置错误时会明确报错
4. 执行 npm run dev — 在 :3402 启动服务（默认绑定 localhost），并运行定时任务： 目录导入（每 6 小时）、探测扫描（每 4 小时，在 :15 开始并加入抖动）、每日摘要锚定
5. 整理要探测的服务：
   • npm run curate -- list
   • 编写模板 JSON（参见 docs/templates/），然后执行 npm run curate -- add <serviceUrl> <template.json>
6. 运维仪表板：http://127.0.0.1:3402/dashboard（暂停／恢复、立即探测、退役／恢复）

资金处理路径经过刻意的严格防护：设置单笔付款硬上限，根据实际结算金额累计每日预算，并对无法解析的付款要求采取失败关闭保护 ——以上均通过注入模拟对象进行了单元测试。

请注意，全新部署的语料库为空 — 评分质量取决于其背后的探测历史。

生产环境部署

参考 assay.nominal-labs.com 实例的运行方式（可根据自己的情况调整）： 提交到 main，将代码作为 git bundle 部署到 VPS，再通过 git reset --hard + systemctl restart assay 应用（配置和更新操作手册见 deploy/README.md）。data/assay.db 中的 SQLite 文件就是产品 ——切勿重新创建；VPS 会通过 /etc/cron.daily/assay-backup 在本机保留每日快照。

付款配置：PAYMENTS_ENABLED=true + RECEIVE_WALLET_ADDRESS + 一个 Coinbase Developer Platform (CDP) API 密钥 （CDP_API_KEY_ID/CDP_API_KEY_SECRET — 两者均已设置时，服务器会自动为 Base 主网选择 CDP facilitator）。

目录结构

• src/ — 整个系统：服务 + API、探测器、评分、摘要、导入、页面
• mcp/ — assay-oracle-mcp：MCP 服务（check_service、get_score、top_services）
• middleware/ — assay-x402-guard：面向 Agent 的 wrapFetchWithAssay 支出防护
• tests/ — vitest；通过注入模拟对象对资金处理逻辑进行单元测试
• scripts/ — 预检、钱包轮换、冒烟测试；start-assay.* 是旧版启动脚本， 来自更早的家用电脑部署，现已由 systemd 取代
• deploy/ — Caddyfile、systemd 单元文件、配置操作手册
• docs/ — CORPUS-LOG.md（公开完整性日志）、规格说明、模板

许可证

MIT — 整个仓库，包括 npm 软件包（mcp/ 和 middleware/）。代码可自由复用；新部署无法复制的是证据语料库及其锚定在 Bitcoin 上的历史记录。