tx402

tx402

以通俗易懂的语言解释 Algorand 交易，通过 Algorand 上的 x402 按调用付费 API 提供服务。

在线服务：

https://tx402-production.up.railway.app

解释一笔交易、原子组中的每笔交易、批量交易 ID，或近期账户活动。响应包含缩放后的金额、内部交易、资产名称、费用、时间戳、交易对手方，以及经来源验证的协议标签。

无需钱包，即可试用免费的固定交易演示：

https://tx402-production.up.railway.app/demo?example=algo

GET /explain?txid=YRSG7IKDPCK4XMKFFTFFFYMIHF6SJOMHUOIE4FFUWNLEQ4WG2ZOQ

付款后的示例响应：

{
  "txid": "YRSG7IKDPCK4XMKFFTFFFYMIHF6SJOMHUOIE4FFUWNLEQ4WG2ZOQ",
  "network": "mainnet",
  "summary": "On June 16, 2019, wallet VCINCV...JPMIPM sent 1 ALGO to CRBMB5...QLXZOY. Paid 0.001 ALGO in fees.",
  "details": {
    "type": "pay",
    "sender": "VCINCVUX2DBKQ6WP63NOGPEAQAYGHGSGQX7TSH4M5LI5NBPVAGIHJPMIPM",
    "transfer": {
      "amount": "1",
      "assetId": 0,
      "unit": "ALGO"
    }
  }
}

原始 Algorand 索引器 JSON 面向记账机器进行了优化：金额以基础单位表示，资产使用数字 ID，备注则采用 base64 编码。tx402 是面向 Agent 和应用的转换层，帮助它们向用户解释交易。

API

公开路由：

• GET / - 提供服务元数据链接的着陆页
• GET /health - 进程存活检查
• GET /health?deep=1&network=mainnet - 上游服务就绪检查
• GET /discovery - 机器可读的服务说明和定价元数据
• GET /openapi.json - OpenAPI 3.1 规范
• GET /.well-known/agent.json - Agent 市场清单
• GET /.well-known/x402 - x402 资源清单
• GET /llms.txt - 面向 Agent 的可读文档
• GET /demo?example=algo|usdc - 免费的 Mainnet 白名单示例
• GET /explain?txid=...&network=mainnet - 付费交易解释
• GET /group?txid=...&network=mainnet - 付费原子组解释
• POST /batch - 包含 1 到 10 个交易 ID 的付费批次
• GET /account/activity?address=...&limit=25 - 付费活动摘要
• GET /analytics - 免费的汇总采用情况计数

默认价格为：/explain 收费 $0.005，/group 收费 $0.01，/batch 收费 $0.02，/account/activity 收费 $0.01。生产环境接受 Mainnet USDC：

• 网络：algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=
• 资产：31566704
• 收款方：6RK3U3OF2B4Q773L4KC7OVFHQGU5I74NHRZ36QN6CVF527CKXAL62YR754

架构

tx402 由一个小型确定性核心和一个轻量服务外壳组成。

核心：

• src/decoder.js 将原始 Algorand 索引器 JSON 转换为规范化交易对象。
• src/narrator.js 将该规范化对象转换为一句易读的句子。
• src/insights.js 生成组级和账户级摘要。
• src/explainer.js 解析资产，并协调单笔交易、交易组、批次和账户产品。
• src/knownApps.js 将已知应用和资产 ID 映射为易读标签，并为每条叙述中的协议声明提供验证来源。

服务外壳：

• src/index.js 负责 HTTP 路由、中间件顺序、日志、速率限制、健康检查和优雅关闭。
• src/indexer.js 是唯一与 AlgoNode 公共索引器通信的模块。
• src/payments.js 声明 x402 价格和收款方，然后将验证和结算交由托管式 GoPlausible facilitator 处理。
• src/rateLimit.js 提供基于内存的 IP 速率限制器。
• src/analytics.js 保存仅限进程本地的汇总采用情况计数，不使用 Cookie，也不记录原始钱包地址、查询字符串或 IP 历史记录。

服务器绝不存储私钥。买方在客户端进行签名。资源服务器只公布价格、验证付款，并在产品路由成功响应后通过 facilitator 结算。

本地运行

npm install
npm start
npm test

本地端点：

curl "http://localhost:4021/health"
curl "http://localhost:4021/discovery"
curl "http://localhost:4021/explain?txid=SOME_REAL_MAINNET_TXID"
curl "http://localhost:4021/group?txid=SOME_REAL_MAINNET_TXID"

应用会在存在 .env 文件时读取它。除非需要非标准资产，否则请勿设置 USDC_ASSET_ID；代码会根据 NETWORK 推导规范的 USDC 资产。

客户端示例

只读示例客户端：

npm run example:client
npm run example:catalog

默认客户端会打印发现元数据和 x402 付款挑战，但不会花费资金。若要让它付款，请配置已注资的买方钱包，并设置 TX402_EXAMPLE_PAY=1 和 CONFIRM_MAINNET_PAYMENT=1。

OpenAPI：

• openapi.json
• https://tx402-production.up.railway.app/openapi.json

Agent 市场元数据：

• https://tx402-production.up.railway.app/.well-known/agent.json
• https://tx402-production.up.railway.app/.well-known/x402
• https://tx402-production.up.railway.app/llms.txt

可直接复制粘贴的集成方案和分发资源：

• 集成指南
• 分发清单
• GoPlausible MCP 提案
• 推广资料包

付费路由还声明了标准 x402 Bazaar 扩展，其中包括输入/输出模式、服务元数据和示例请求。结算成功后，支付促进方可索引这些元数据。

MCP 封装器：

npm run mcp

公开 npm 软件包发布后，Agent 无需克隆此代码库即可安装：

npx tx402-mcp

默认情况下，MCP 封装器为只读，会为付费调用返回 x402 付款要求。若要让它使用本地钱包付款，请设置 TX402_MCP_ENABLE_PAYMENTS=1 和 CONFIRM_MAINNET_PAYMENT=1。

六阶段采用路线图见 PLAN.md。

提交材料

• 演示文稿
• 演示视频脚本

安全说明

• 输出字符串可能包含不可信的链上数据，包括资产名称和备注。JSON 输出作为 JSON 是安全的，但使用者在渲染 HTML 时必须对其进行转义。
• 无效的 txid 输入会在访问索引器和付款前被拒绝。
• 仅在成功响应后才会完成付款结算。
• 所有产品路由、/analytics、/discovery 和深度健康检查均受速率限制。
• 只有标记为 verified: true 时，协议/应用名称才会作为事实陈述。
• 应用程序日志不会记录查询字符串和客户端 IP 地址。

状态

• 阶段 1 - 核心说明器，免费且本地运行
• 阶段 2 - 在 Testnet 上部署 x402 付款中间件，并完成端到端验证
• 阶段 3 - 公开 HTTPS 部署
• 阶段 4 - Mainnet 付款配置
• 阶段 5 - 首笔真实 Mainnet 结算
• 阶段 6 - 示例客户端、OpenAPI 规范、可选 MCP 封装器

首笔 Mainnet 结算：

• txid：XA7HMRPUV4X2GWI4AAGUT5FKAVTNCQJ5ZMUNTVTBKG3GZMES27LA
• 金额：0.005000 USDC

维护者说明

实现操作手册、部署命令、阶段证据和运维注意事项见 CLAUDE.md。