Lumen Agent Utilities

Lumen Works Agent API（x402）

同一来源下有两个列表：

• Lumen Pre-Sign Check：POST /v1/tx/explain（$0.002）。在签署任何 EVM 交易或 EIP-712 消息前使用；返回 {summary[], flags[], verdict}，其中 verdict 为 looks_ok | review | do_not_sign_unless_intended。Agent 策略：遇到 do_not_sign_unless_intended 时中止，遇到 review 时升级处理。**仅供参考，并非安全保证；looks_ok 不代表安全；不进行模拟。**准确性范围和已知限制：ACCURACY.md。MCP：/mcp/presign。
• Lumen Agent Utilities：下方的所有其他路由。MCP：/mcp。

信任条款：无需注册；/v1/free/... 下的免费额度为每小时每个 IP 20 次调用；对任何付费路径执行 GET/HEAD 都会返回 402 报价（不会结算）；调用出错时不收费，因为 x402 中间件只会在处理程序返回低于 400 的状态码后结算。输入架构和真实示例输出（examples.json，由 test/capture-examples.mjs 实时捕获）位于每个路由的 Bazaar 扩展和 /openapi.json 中，并通过 node test/validate-bazaar.mjs <base> 验证。

统计数据：/v1/stats 仅包含匿名汇总数据（UA 系列、由每日轮换加盐 IP 哈希生成的每日唯一计数，保留 30 天）。设置 STATS_GIST_ID + STATS_GIST_TOKEN（仅限 gist 的令牌）后，数据会在部署间保留；否则会保存在内存中。

按次付费的 Agent 工具，通过 x402 在 Base 主网上每次调用收费 0.001–0.002 USDC（精确方案，使用 PayAI 公共 facilitator）。作者：Dan（Dansgit2b）。早期阶段，未经审计。

端点（POST JSON）	用途
/v1/x402/lint {header}	解码并检查 x402 PAYMENT-REQUIRED/SIGNATURE/RESPONSE
/v1/eip712/decode {typedData}	域分隔符、摘要、风险提示
/v1/calldata/decode {data, signature?}	选择器、openchain/4byte 查询、已解码参数
/v1/web/markdown {url, fullPage?, maxChars?} — $0.001	公共页面 → 清理后的 Markdown（Readability）+ 元数据。不渲染 JS。
/v1/web/unfurl {url} — $0.001	最终 URL、状态、标题、描述、OG 图片、规范链接、favicon
/v1/evm/address {address}（0x 或 ENS）— $0.002	Ethereum+Base：ENS + 记录、EOA/合约/7702、余额、USDC/USDT、ERC-20 信息（公共 RPC）
/v1/domain/lookup {domain} — $0.002	DNS（DoH）A/AAAA/MX/NS/TXT/CAA、SPF/DMARC、RDAP 注册商/创建时间/到期时间、域名年龄

免费额度：相同路径位于 /v1/free/... 下（每小时每个 IP 20 次）。发现入口：/、/.well-known/x402、/openapi.json、/llms.txt。 payTo：0xee9790cB3960952F585379F831a89b4e00B4029A。

端到端验证（本地运行，2026-10-10）：付费调用已在 Base 上结算，交易 0xff4af45df7caeef958b77700e96ba94e5ed37d3bac6e8cf40d6528a9497d77d4。

部署：Render（render.yaml，免费套餐）或任意 Docker 主机（Dockerfile）。将 PUBLIC_BASE 设置为公共来源。不需要密钥（服务器只接收付款）。许可证：MIT。

MCP 服务

远程 MCP（流式 HTTP，无状态 JSON）：https://lumenworks-x402-decoder.onrender.com/mcp，提供工具 x402_lint、eip712_decode、calldata_decode、web_markdown、url_unfurl、evm_address_lookup 和 domain_lookup。免费额度：每小时每个 IP 可调用 20 次工具。超出后，工具会返回对应付费 HTTP 端点的 x402 付款要求（0.001–0.002 USD）。

Celo

设置 X402_CELO_API_KEY（从 x402.celo.org 控制面板获取）后，每个付费路由也接受 Celo 上的 USA₮ 和 USDC（eip155:42220），并通过 Celo 托管的 facilitator（api.x402.celo.org）结算。

免费 x402 支付安全检查

POST /v1/x402/safety-check（MCP 工具 x402_payment_safety_check）— 确定性支付前检查。请求体：{url?, method?, payment_required?, expected_pay_to?, expected_network?, max_price_usdc?, listed_price_usdc?, facilitator_url?, client_config?}。我们会获取未付款的 402 响应（带 SSRF 防护），并返回 ok | review | do_not_pay，检查内容包括：HTTPS/健康状况/延迟、payTo 有效性/校验和/不匹配、未知资产/网络、价格是否超过你的上限及标价、超时/重放窗口、多个 payTo、未知 facilitator，以及客户端配置中是否缺少支出上限/幂等性设置。不存储任何内容；看起来像私钥的输入会被拒绝。每小时每个 IP 限 30 次。

计划中（尚未构建）：持续监控价格/payTo/资产变化并发送提醒。免费候补名单：POST /v1/monitoring/waitlist {endpoint_url, contact?}（每小时每个 IP 限 5 次）。尚未承诺日期；数据仅存储在免费主机的内存/日志中，因此重启后可能丢失。

统计数据

GET /v1/stats — 自上次重启以来的匿名内存计数器：各端点的调用次数、未付款的 402 响应与已付款结算（转化率）、粗略的用户代理分类。不存储 IP 或请求体。

v1.3：签名前说明 + 公共数据工具

端点（POST）	价格	MCP 工具	上游数据源（免费，无需密钥）
/v1/tx/explain	0.002	explain_before_sign	calldata（openchain/4byte）+ EIP-712、风险标记
/v1/pubmed/search	0.001	pubmed_search	NCBI E-utilities
/v1/arxiv/search	0.001	arxiv_search	arXiv API
/v1/sec/filings	0.001	sec_filings	SEC EDGAR（根据 SEC 政策，设置 SEC_USER_AGENT 并填写联系邮箱）
/v1/weather/forecast	0.001	weather_forecast	Open-Meteo（CC BY 4.0）
/v1/polymarket/markets	0.001	polymarket_markets	Polymarket Gamma（只读数据）

免费套餐：/v1/free/<path> 或 MCP，每小时每个 IP 限 20 次。

Facilitators

如果设置了 CDP_API_KEY_ID 和 CDP_API_KEY_SECRET，则优先使用 Coinbase 的 CDP facilitator。通过它完成的结算会让服务被收录到 x402 Bazaar 中。PayAI facilitator 仍会注册为备用项。若未设置 CDP 密钥，则与之前一样，由 PayAI 处理所有请求。