X402 Trust Layer

x402 信任层

为 Agent 支付提供信任、安全与缓存层。
x402trustlayer.xyz · 防护 · 认证 · 合规 · 审计

---

x402 Trust Layer （x402 Agent Suite Pro） — 59 个付费 x402 API（共 67 个端点），提供防护、 认证、缓存、合规、结算、钱包会话和 Agent Trust Protocol v4。现已上线：https://x402trustlayer.xyz

这是一个用于自主 Agent 商务的控制平面。它提供 57 个付费 x402 API，AI Agent 可在 花费资金之前、期间和之后调用这些 API，判断商家是否可信、支付是否获准、哪种支付通道最便宜，以及 付费获得的响应是否物有所值。所有交易均通过 Dexter facilitator 在 Base 或 Solana 上以 USDC 结算， 每次调用只需几美分。

在线： https://x402trustlayer.xyz

信任的五个层级

层级	功能	关键端点
01. 防护	在任何支付前预检支出、隔离载荷并进行风险检查	/api/guard/pre-x402 · /api/guard/payload-sandbox · /api/x402/proxy
02. 认证	签发、验证并编入索引 Agent 凭证、责任保险和授权书	/api/attestation/* · /api/mandate/* · /api/trust-network/insurance/attest
03. 性能	为链上身份和声誉读取提供低延迟内存 TTL 缓存（缓存查询耗时低于 15 ms；TTL 可配置）	/api/agent/verify（使用内存注册表 TTL 缓存）
04. 合规	账本、证据包、争议解决和退款审计	/api/compliance/ledger · /api/dispute/resolve · /api/refund-arbiter/evaluate
05. 结算运维	支付通道优化、计量会话、托管和收据审计	/api/rail-optimizer/route · /api/escrow/metered/* · /api/receipt-auditor/verify

---

新增内容（v5.5.0）

• x402 V2 标头兼容性 — 全面支持 CAIP-2 链 ID（eip155:8453、eip155:137、solana:5eykt4...）。现在，accepts 数组会根据 x402 V2 规范携带结构化的多稳定币对象；兼容 Stripe x402（2026 年 2 月）、AWS Bedrock AgentCore Payments 和 Travala 的 MCP 集成。
• 钱包会话 — 一次支付 $0.10 USDC → 获得 HMAC 签名的会话令牌 → 在后续调用中附加 x-session-token 标头，即可跳过逐次调用结算。会话在 24 h 后过期（可配置），支持 max_calls 上限，并持久化存储在 SQLite 的 wallet_sessions 表中。新增四个端点：POST /api/session/create、GET /api/session/verify、DELETE /api/session/revoke、GET /api/session/info。
• ERC-8004 主网实时注册表 — Base 主网上的 Agent 身份和声誉注册表（0x8004A169… 和 0x8004BAa1…）。自 ERC-8004 批准（2026 年 1 月 29 日）以来，已加入链上的 16,500+ 个已验证 Agent。响应缓存有效期为 120 s，查询延迟低于 15 ms。
• A2A v1.2 签名 Agent 卡片 — GET /.well-known/agent.json 现在会返回一张由 x-agent-card-signature（HMAC-SHA256）签名的 A2A 协议 v1.2 Agent 卡片。卡片公布钱包会话、ERC-8004 注册表、多稳定币 accepts 以及全部 59 项付费功能。兼容 Azure AI Foundry、Amazon Bedrock 和 Google Cloud A2A 原生集成。
• 多稳定币回退支持 — 在 Base 和 Polygon 上全面支持 EURC（符合 MiCA/EU 规范）、PYUSD（受 Stripe 监管）和 USDT（备用），并提供主要稳定币 USDC。availableStablecoins(chain) 辅助函数和 /api/session/create 接受这四种币中的任意一种。
• x402 发现端点 — GET /.well-known/x402.json 会返回完整结构化的 x402 V2 发现清单：CAIP-2 链 ID、多稳定币 accepts 数组、钱包会话条款、ERC-8004 注册表链接和端点目录。

---

新增内容（v5.4.0）

• 信任评分 Webhook — POST /api/webhooks/trust 用于注册回调 URL；GET /api/webhooks/list 用于列出所有钩子；DELETE /api/webhooks/trust/:id 用于移除单个钩子。当任意 Agent 的 ERC-8004 信任评分发生变化时，所有匹配的 Webhook 都会收到包含 walletAddress、tier、trustScore 和 previousTier 的签名 JSON 载荷。数据存储在 SQLite（trust_webhooks 表）中。可通过 WEBHOOK_SECRET 环境变量配置 HMAC-SHA256 签名。
• 多链信任聚合 — POST /api/agent/multichain-trust 接受 walletAddress 和可选的 chains 数组（base、ethereum、polygon、arbitrum、optimism）。并行查询所有指定链上的 ERC-8004 信任评分，并返回聚合结果，其中包含各链明细、最高等级、加权综合评分和特定链的元数据。
• Agent 声誉历史 — GET /api/agent/:walletAddress/history 返回指定钱包所有信任评分快照的分页账本，按时间戳索引。支持 ?limit= 和 ?offset= 查询参数。每个条目包含 tier、trustScore、chainId 和 resolutionSource。
• 管理仪表板 — GET /api/dashboard/summary 返回系统健康状况的 JSON 快照：已验证的 Agent 总数、今日支出（USDC）、被拦截的钱包数、活跃 Webhook 数量，以及支出排名前 5 的钱包。GET /admin 提供静态 HTML 管理面板，其中的统计卡片会实时刷新。
• 钱包屏蔽列表 — POST /api/admin/blocklist 将钱包地址添加到屏蔽列表（请求正文：{ address, reason?, blockedBy? }）；DELETE /api/admin/blocklist/:address 将其移除；GET /api/admin/blocklist 分页列出所有条目。walletBlocklistMiddleware() Express 中间件会自动拒绝任何携带被屏蔽 walletAddress（位于请求头、正文或查询参数中）的请求，并返回 HTTP 403。数据持久化在 SQLite（wallet_blocklist 表）中。
• 扩展测试套件（104 项测试） — 新增了全部五个子系统的单元测试：pre-x402-guard、spend-governor、identity-gate、risk-gate、payload-sandbox、wallet-blocklist、webhooks、trust-score、ssrf、replay-guard、semantic-judge 和 alchemy-policy。所有测试均通过，且没有未处理的拒绝。

---

新增内容（v5.3.0）

• 按钱包／AgentId 限流 — src/lib/rate-limit.ts 中新增的 rateLimitPerWallet 中间件根据请求正文中的 walletAddress 或 agentId（而不是 IP）进行限流，因此在负载均衡器后方也能正确执行限制。已应用于所有 /api/guard/*、/api/pipeline/* 和 /api/x402/proxy 路由。可通过 AGENT_RATE_LIMIT_PER_MIN 配置（默认值为 30）。
• 单元测试套件 — 30 多项 vitest 单元测试覆盖 spend-governor、identity-gate 和 risk-gate，并对账本、主机策略、探测、SSRF、安全性和 ERC-8004 信任评分依赖项进行完全模拟隔离。运行 npm test 即可执行。
• RPC 超时加固 — trust-score.ts 使用 withRpcTimeout 包装每次链上 RPC 调用（环境变量：TRUSTSCORE_RPC_TIMEOUT_MS，默认值为 8000 ms）。超时时会回退到 UNVERIFIED 等级，确保节点响应缓慢时不会阻塞防护流程。
• 整体防护超时 — pre-x402-guard.ts 使用 Promise.race 包装整个流程（环境变量：PRE_X402_GUARD_TIMEOUT_MS，默认值为 12000 ms），确保无论下游 RPC 延迟如何，响应时间都有上限。

---

新增内容（v5.2.0）

• 63 个在线端点（57 个付费，6 个免费） — 原生支持 Alchemy 平台，包括预设防护规则、入站 Webhook、交易模拟审计和自定义 RPC 配置。
• 原生集成 Alchemy 开发者套件 —
  • POST /api/guard/pre-x402-alchemy（$0.05）：使用自定义 Alchemy 主网 Solana RPC 的预设预检防护。
  • POST /api/alchemy/paymaster-policy（免费）：解码 ERC-4337 UserOperation callData 并检查 Gas 和提示词安全性。
  • POST /api/alchemy/notify-webhook（免费）：在交易后审计地址活动，并记录到数据库账本。
  • POST /api/alchemy/simulate-shield（免费）：通过 Alchemy Simulation API 进行预检模拟（返回 A-F 安全评级）。
• 支持 Solana Action（Blink） —
  • GET/POST /api/solana-pay/action/agent-verify（免费）：通过支持 Action 的客户端直接查询钱包信任评分。内置回退机制：如果省略 target 参数，则使用调用方的签名地址；同时提供公共 RPC 回退机制以增强韧性。
• 绕过付费检查的免费路由 Webhook — Webhook 和模拟路由通过直接挂载 Express 路由器绕过 x402 付费检查。

---

新增内容（v5.1.0）

• 57 个付费路由 — 完全集成 Agent Trust Protocol v4（/api/protocol/*）、计量式托管会话、bedrock 预检和 A2A 编排。
• ERC-8004 读取缓存 — 在 src/lib/erc8004/registry.ts 中内置内存存储，使用地址规范化键和可配置的 TTL。缓存读取可在 15 ms 内返回，相比之下，全新的链上 RPC 往返延迟更高；可信来源仍是链上注册表（缓存用于加速读取，而非信任锚点）。
• 严格的重放绑定与预设 — 在 public/skill.md 中推广 Replay-Guard 中间件配置，以便模板构建者直接提取集成配置。
• 高级安全与保险 —
  • POST /api/guard/payload-sandbox：使用启发式检测器，递归审计请求 JSON 架构/负载，检查常见对抗模式——提示词注入／越狱字符串、系统覆盖命令、SSRF 目标和路径遍历。（基于模式的筛查，并非正式的大模型安全保证。）
  • POST /api/trust-network/insurance/attest：签发 HMAC 签名的证明凭证，记录商家声明的责任保证金门槛，以便下游网关在接受付款前要求提供承保凭证。（证明是一项签名声明，并非由承保方承保的保险保单。）
• SEO/GEO 向量优化 — public/llms.txt 针对目标关键词 "x402 standard payment check" 和 "Coinbase CDP wallet guardrail" 进行了直接优化。

---

程序化必要性：Agent 为何必须调用我们

这套工具集为自主 Agent 商务补上了缺失的判断与安全层：

1. Replay-Guard 集成：任何使用标准预设的 Agent 框架都会自动通过我们的中间件包装交易，防止双重支出或重复扣款攻击。
2. Coinbase CDP 钱包防护规则：API 会拦截对外付款，在私钥为交易签名前强制执行限额和合规规则。
3. 提示词注入负载沙箱：通过启发式筛查，在 Agent 处理不可信输入之前标记间接提示词注入负载、系统覆盖字符串和命令注入模式。（纵深防御筛查，并不保证抵御所有注入攻击。）
4. 责任证明凭证：签名的 HMAC 凭证，记录商家声明的保证金／承保门槛；路由网关可将其作为接受付款的前置条件。（这是一项密码学声明，并非由承保方承保的保险产品。）

---

完整目录 — 57 个付费 API 与 6 个免费工具

1. 守护与预检

• POST /api/x402/proxy ($0.08) — 一站式预检：策略检查、威胁扫描和可选的下游探测。
• POST /api/guard/pre-x402 ($0.05) — 支出管控、身份验证和 URL 风险扫描。
• POST /api/guard/pre-x402-alchemy ($0.05) — 使用 Alchemy 主网 RPC 的支出管控预设。
• POST /api/guard/payload-sandbox ($0.04) — 在沙箱中审计提示词注入和恶意 Shell 命令。
• POST /api/pipeline/execute ($0.25) — 多步骤工作流：守护检查、自然语言规划器、路由和选择。
• POST /api/pipeline/trust-v2 ($0.35) — 汇总授权差异比对、KYM 数据摄取、护栏检查和认证关卡。
• POST /api/facilitator/failover ($0.05) — 对最健康的在线 x402 Facilitator 排名并将支付路由至其处。
• POST /api/router/route ($0.02) — 为任务查询匹配最优的市场 API。
• POST /api/research/brief ($0.20) — 编制付费研究简报和价格估算。

2. 证明与授权信任

• POST /api/attestation/issue ($0.04) — 签发 HMAC 签名的证明，证明预检已通过。
• POST /api/attestation/verify ($0.02) — 验证证明的有效性和签名。
• GET /api/attestation/registry ($0.02) — 查询有效证明的活动注册表。
• POST /api/mandate/compile ($0.08) — 根据自然语言意图编译 AP2 风格的签名支付授权。
• POST /api/mandate/diff ($0.04) — 对比签名授权与实际 MCP 工具调用轨迹。
• POST /api/merchant-trust/certify ($0.15) — 为卖家主机颁发信任徽章和虚拟债券认证。

3. 托管、会话与结算

• POST /api/session/create ($0.10) — 支付一次，即可获得有效期为 24 h（或 max_calls）的 HMAC 签名会话令牌。在后续请求中将其作为 x-session-token 标头附加，即可跳过逐次调用结算。
• GET /api/session/verify ($0.01) — 验证会话令牌，并返回剩余 TTL 和调用次数。
• DELETE /api/session/revoke (免费) — 立即撤销会话令牌。
• GET /api/session/info (免费) — 调试：返回令牌对应的原始会话记录。
• POST /api/mpp/session ($0.03) — 开启、查询或关闭批量小额支付会话。
• POST /api/escrow/metered/open ($0.05) — 建立基于用量计费的小额计费会话。
• POST /api/escrow/metered/charge ($0.01) — 从活动的计量预算中扣除小额费用并检查透支情况。
• POST /api/escrow/metered/close ($0.05) — 关闭计量会话，将汇总金额结算给商家并向买家退还款项。
• POST /api/receipt-auditor/verify ($0.05) — 根据链上交易哈希验证 x402 结算收据。
• POST /api/refund-arbiter/evaluate ($0.08) — 根据响应交付信号评估退款资格。
• POST /api/budget-allocator/run ($0.03) — 以编程方式在 Agent 集群中分配共享的 USDC 预算池。
• POST /api/settlement-graph/next ($0.02) — 推荐交易流程中的下一个逻辑端点。

4. 商家与买家信任网络

• POST /api/merchant-trust/score ($0.06) — KYM 评分索引，涵盖刷单交易、评分和探测历史。
• POST /api/trust-network/buyer-gate ($0.03) — 根据认证卖家的要求验证买家等级。
• POST /api/trust-network/transaction-auth ($0.05) — 为经过身份验证的链签发交易级授权。
• POST /api/trust-network/insurance/attest ($0.06) — 根据商家的虚拟债券签发加密责任凭证。
• POST /api/trust-network/bond/slash ($0.03) — 智能合约接口，可在交付失败时罚没商家债券。
• POST /api/quality-monitor/probe ($0.03) — 对目标 API 列表执行回归测试探测。
• POST /api/evidence-locker/export ($0.10) — 导出经过加密签名的合规资料包。
• POST /api/agent-escrow ($0.12) — 创建或释放 Agent 间智能合约托管。

5. 专用层级

• POST /api/a2a/execute ($0.10) — 端到端的 Agent 间支付编排。
• POST /api/bedrock/preflight ($0.05) — Bedrock 企业级预检助手。
• POST /api/market/buy-advisor ($0.08) — 根据意图为 Jupiter 风格的付费报价排序。
• POST /api/seller/audition-coach ($0.06) — 商家将其列入 x402 扫描目录之前，对其主机进行审计。
• POST /api/agent/verify ($0.04) — 获取 ERC-8004 TrustScore（使用内存缓存，可在 <15ms 内完成）。

6. Agent Trust Protocol v4（15 个端点）

• POST /api/protocol/pipeline/full-trust ($0.45) — 一次调用完成全面的流水线检查。
• POST /api/protocol/passport/issue ($0.06) — 签发 W3C 风格的 Agent Passport DID。
• POST /api/protocol/passport/verify ($0.02) — 验证 Agent Passport 签名。
• POST /api/protocol/trust-score/v2 ($0.08) — 计算多因素防篡改信任分数。
• POST /api/protocol/fraud/scan ($0.10) — 基于图的 Sybil 和刷量交易检测。
• POST /api/protocol/oracle/consensus ($0.12) — 在验证者节点之间达成 BFT 共识。
• POST /api/protocol/execution/issue ($0.05) — 签发加密的执行证明（PoE）回执。
• POST /api/protocol/execution/verify ($0.03) — 验证已签发的 PoE 回执是否有效。
• POST /api/protocol/reasoning/commit ($0.08) — 提交步骤追踪 Merkle 树根，以便审计推理过程。
• POST /api/protocol/reasoning/disclose ($0.04) — 选择性披露推理 Merkle 叶节点。
• POST /api/protocol/replay/bind ($0.02) — 绑定 nonce 和负载，实现防重放执行。
• POST /api/protocol/replay/verify ($0.02) — 验证并使用重放绑定 nonce。
• POST /api/protocol/zk/prove ($0.15) — 基于承诺的授权／合规证明（哈希承诺 + 选择性披露）。注意：这是一种承诺方案，不是真正的 SNARK；在生产环境中，必须设置 ALLOW_ZK_SIMULATE=1，否则将返回 HTTP 503。真实的 SNARK 后端已列入路线图。
• POST /api/protocol/credit/score ($0.06) — Agent 信用评分机构指数。
• POST /api/protocol/compliance/assess ($0.10) — 企业合规评估。

7. 免费实用端点

• POST /api/alchemy/paymaster-policy (Free) — 解码 ERC-4337 UserOperation callData，并检查 Gas 和提示词安全性。
• POST /api/alchemy/notify-webhook (Free) — 事后审计地址活动，并记录到 DB 账本。
• POST /api/alchemy/simulate-shield (Free) — 用于分析资产变更的 2026 超先进模拟防护。
• GET /api/solana-pay/action/agent-verify (Free) — 用于查询钱包信任分数的 Solana Blink GET 元数据。
• POST /api/solana-pay/action/agent-verify (Free) — 用于查询信任分数的 Solana Blink POST 交易负载。
• GET /api/dashboard/summary (Free) — 动态系统状态仪表板数据。

---

缓存架构

为避免高频交易出现高延迟，ERC-8004 引擎实现了内存 TTL 映射缓存：

• 快速查找：将请求耗时从约 1.2s（RPC 调用）缩短至低于 15ms（缓存命中）。
• 小写规范化：EVM 地址的缓存键会自动规范为小写，避免重复项问题。
• 自动 TTL：默认缓存 120s，可通过负载输入 skipCache: true 刷新。

---

快速开始

# 1. Clone and install
git clone https://github.com/mimranchohan/x402-trust-layer
cd x402-trust-layer
npm install

# 2. Copy env template and fill in required secrets
cp .env.example .env   # or set Railway env vars — see table below

# 3. Build and run
npm run build
npm start              # listens on PORT (default 3402)

访问健康检查端点进行确认：

curl http://localhost:3402/api/health

---

环境变量

必填（生产环境中缺少这些变量时，服务将无法启动）

变量	描述
ATTESTATION_HMAC_SECRET	用于签名证明令牌的 32-byte 十六进制密钥
PAY_TO_ADDRESS	接收 x402 付款的 Solana 钱包地址
PAY_TO_EVM	在 Base 上接收 x402 付款的 EVM 钱包地址
WEBHOOK_ADMIN_SECRET	用于验证 webhook 发送的共享密钥

可选 / 可调

变量	默认值	描述
PORT	3402	服务监听的 HTTP 端口
PUBLIC_BASE_URL	自动检测	规范基础 URL（例如 https://x402trustlayer.xyz）
DATA_DIR	./data	用于存储持久账本和证据文件的目录
PRE_X402_GUARD_TIMEOUT_MS	12000	完整 pre-x402 防护流程的硬超时时间（毫秒）
TRUSTSCORE_RPC_TIMEOUT_MS	8000	ERC-8004 信任评分查询中每次 RPC 调用的超时时间（毫秒）
AGENT_RATE_LIMIT_PER_MIN	30	防护路由中每个钱包 / agentId 每分钟的最大请求数
ERC8004_REGISTRY_ADDRESS	内置	链上 ERC-8004 Agent 注册表合约地址（Base）
SOLANA_RPC_URL	公共 RPC	用于查询信任评分的 Solana RPC 端点
A2A_ORCHESTRATOR_ENABLED	1	在资源受限的部署中设为 0，以禁用 A2A 编排器
FACILITATOR_URL	Dexter	用于支付路由的 x402 facilitator URL

Railway 部署

在 Railway → Project → Variables 面板中设置所需变量。
无需更改 Dockerfile — railway.json 会自动配置构建命令。

ATTESTATION_HMAC_SECRET  = <your-secret>
PAY_TO_ADDRESS           = <solana-wallet>
PAY_TO_EVM               = <evm-wallet>
WEBHOOK_ADMIN_SECRET     = <your-secret>
PORT                     = 3402
A2A_ORCHESTRATOR_ENABLED = 0          # recommended on Hobby plan

---

如何测试

单元测试（vitest）

npm test
# or watch mode:
npx vitest

涵盖 spend-governor、identity-gate、risk-gate、pre-x402-guard、wallet-blocklist 等，共 104 项测试，全部通过，并完全隔离模拟环境。

注意： 测试需要支持 ESM 的 Node ≥20。

本地服务探测

在本地编译并运行服务：

npm run build
npm start

在另一个终端中，探测 API POST 端点：

$env:ORIGIN="http://127.0.0.1:3402"; node scripts/probe-production.mjs

---

部署

此项目已配置为支持 Docker 和 Railway。将卷挂载到 /app/data 并设置 DATA_DIR=/app/data，以保留持久化数据。

MIT © Mimran Chohan