agenttoll

AgentToll

agenttoll.app 为 Agent 提供 21 个付费数据端点，价格为 0.001 至 0.008 USDC。托管服务在 Base 主网上结算。链上身份：agenttoll.base.eth。源码 · MCP 包。

新池发现、代币安全检查、采样雷达历史记录、钱包活动和市场数据共用一个 API。Base 市场和链上数据始终使用主网；可自托管的实例则可在 Base Sepolia 上收款，而无需更改数据网络。

在浏览器中检查代币

/inspect.html 中的浏览器流程包含一份免费报告，报告标注了日期，并根据真实提供方的数据生成。粘贴 Base 代币合约地址，无需连接钱包即可查看价格，然后授权支付一笔 USDC，以获取包含八项检查的报告。该流程使用现有的 /api/base/safety/:address 端点（$0.003），保留缺失的证据，并提供结算收据和 JSON 下载。报告最多可缓存五分钟。对于含糊不清的签名失败，必须先检查钱包，才能再次请求付款。

web/inspect.html 是页面模板；web/inspect.ts 控制报价和付款，web/token-report.ts 展示数据。npm run build:web 会构建两个浏览器包，并将 public/token-example.json 嵌入生成的页面，因此即使没有 JavaScript，示例也能正常显示。npm run check:generated 会检查所有三个生成文件是否与其源文件一致。仅在获得新记录的响应及其采集时间和来源信息后，才刷新示例；不要将旧示例标注为实时数据。

运行检查指标来自导出的应用日志；请参阅 ops:inspections in OPERATIONS.md。这些指标会区分主网结算、测试网活动和已知的运营方钱包，但不会声称钱包代表某个人，也不会声称报价代表唯一访客。

已保存的研究、比较结果和钱包持仓

/research.html 会在浏览器本地保存关注列表和带日期的报告历史记录。保存代币地址或已记录的示例；也可以从检查器保存已完成的检查结果。存储上限为 50 个关注代币和 100 份经过清理的报告，每个代币最多 10 份。存储中不会包含密钥、签名、付款凭证或付款钱包地址。数据仅适用于此浏览器；移除站点数据会删除历史记录。存储失败时会显示提示，并保留此前存储的数据。

历史记录视图会比较同一代币、同一来源类型的观察结果，保留缺失的证据，并在日期不可用或同一观察结果的内容相互冲突时发出警告。重复的缓存结果不会被当作最新检查结果呈现。示例和共享快照与检查结果保持区分。

使用已保存的观察结果比较 2 至 5 个代币地址，或查看新检查的总报价。每个代币都使用现有的安全检查端点，并分别进行钱包授权。批次按顺序执行，保留已完成的响应和凭证，遇到失败时停止。剩余请求需要新的明确报价；如果付款状态不确定，必须先检查钱包并确认后，才能开始下一笔付款。显示的报价在 60 秒后过期，包括长批次中的剩余步骤。

钱包面板会单独为 /api/base/portfolio/:address?minValue=0&limit=50 定价，显示观察到的持仓和来源覆盖情况，并允许访客从中选择最多 5 个已发现的 ERC20 代币，分别付费进行检查。原生 ETH、缺失或无价格的持仓以及覆盖缺口，不会被默认为已检查。钱包地址和投资组合响应仅保留在页面内存中。

报告操作会复制有长度限制的 URL 片段快照，或下载 1200×1200 的 PNG 卡片。/shared-report.html 会将每个导入的快照标记为用户提供且未经验证，保留观察日期，并且不会自动付款或保存。任何人都可以读取或更改片段内容；它们不是经过身份验证的 AgentToll 记录。付款和钱包元数据不会包含在内。没有后台监控或消息服务。

web/research*.ts、web/portfolio-model.ts 和 web/report-share.ts 实现这些工具。构建过程会共用 CSS 源文件，同时将其内容内联到生成的 HTML 中，以符合现有部署的内容安全策略。npm run build:web 会重新生成所有浏览器入口；npm run check:generated 会验证生成结果。

付款流程

1. 未签名的请求会返回 HTTP 402，并在 PAYMENT-REQUIRED 中提供 base64 编码的 JSON 报价。JSON 响应也会在正文中包含相同的完整报价，供读取 accepts 的客户端和发现爬虫使用。
2. 客户端会验证端点限额、预期来源、网络、USDC 合约和收款方，然后在其预算范围内签署 EIP-3009 授权。
3. 重试请求会携带 PAYMENT-SIGNATURE。facilitator 会验证付款，并在处理程序成功响应后结算。PAYMENT-RESPONSE 会携带结算凭证。

API 使用者无需账户或 API 密钥。付款客户端需要钱包密钥；运营者可能需要 facilitator／上游凭证。初始报价和携带签名的重试是两个独立的 HTTP 请求。

结算前发生的处理程序故障不会收费。签名或结算后如果响应丢失或请求超时，结果可能无法确定：重试前请检查凭证和钱包。受限客户端会将存在歧义的已签名金额保留为占用额度。

端点

GET 端点	说明	每次调用的 USDC
/api/price/:symbol	现货 USD 价格和 24 小时涨跌幅	$0.001
/api/gas?gasLimit=	Base Gas、最新区块和可选的交易成本估算	$0.001
/api/trending?limit=	全市场热门资产	$0.002
/api/base/token/:address	Base 链上代币价格	$0.001
/api/base/address/:address	Base 地址概览和已验证的主要 Basename	$0.001
/api/base/portfolio/:address?minValue=&limit=	已观察到的持仓和 USD 估值，以及覆盖情况	$0.003
/api/base/safety/:address	自动代币检查和缺失证据覆盖情况	$0.003
/api/base/scout?minLiquidity=&pools=	经过筛选的雷达池及安全性结果	$0.008
/api/base/fresh?minutes=&limit=&fundedOnly=	近期 Uniswap v4 池事件、代币归属和资金活动	$0.004
/api/base/radar/history?date=	固定到不可变 git SHA 的已发布快照	$0.002
/api/base/scorecard?days=	最新发布的样本与当前观测结果的对比	$0.005
/api/base/name/:nameOrAddress	Basename 正向解析和已验证的反向解析	$0.001
/api/feargreed?days=	情绪指数，可选包含每日历史记录	$0.001
/api/base/trending?limit=	Base DEX 热门池	$0.002
/api/brief?symbols=	一次调用获取价格、Base Gas 和市场情绪	$0.005
/api/base/radar?minLiquidity=&limit=	流动性高于设定下限的新池排名列表	$0.003
/api/try/premium?asset=	加密货币隐含 USD/TRY 汇率与官方汇率对比	$0.002
/api/try/spread?asset=	土耳其交易所报价与全球 USD 价格对比	$0.002
/api/watch/address/:address?since=	分页列出的已确认地址交易	$0.002
/api/watch/radar?since=	当前部分雷达列表中的较新观测结果	$0.003
/api/watch/price/:symbol?ref=&pct=	价格阈值检查	$0.001
/api/stats	按网络／接收方统计的链上费用总额	免费
/api/catalog	机器可读的端点目录	免费
/api/demo	静态示例响应格式	免费
/api/health	进程存活状态	免费
/api/ready	Facilitator 和 Base RPC 就绪状态	免费

可选查询参数不会改变已注册价格。无效输入将返回 400。fundedOnly 仅接受字面值 true 或 false。目录和 OpenAPI 文档说明了参数限制。部分上游结果会被缓存，并发加载会合并处理；TTL 各不相同，历史缓存的有效期长于实时市场缓存。

API GET/HEAD 请求使用 URL 参数和支付标头；若请求包含正文，则会返回 400 并关闭连接。支持经过编码的路径参数、大小写变体和一个尾随斜杠；在支付验证前会拒绝经过编码的路由前缀，以及重复或经过编码的路径分隔符。

解读数据

安全响应会保留未知检查项和提供方覆盖情况。缺少所有者标记或税费信息不代表通过。只有具备必要证据时，结果才会是 clear；即使其他检查项未知，检测到失败仍可能导致高风险。自动化检查通过并不能保证安全。解读投资组合和雷达响应时，也需要正确理解其中的 partial 和 coverage 字段。

免费的补充安全数据源可提供地址风险筛查、经过验证的界面背景信息和观测到的资金池流动性。界面名称和市场价值不能弥补缺失的权限或流动性所有权检查。请参阅安全证据与限制。

投资组合索引器扫描会在三页后停止，或在索引尾部低于 $1 的源读取下限时停止。降低 minValue 只会更改显示筛选条件，不会改变此源扫描上限。任何尚未读取的提供方页面都会使响应标记为 partial；总额和未定价数量仅描述已观测到的持仓，未见代币的数量仍然未知。情绪响应会将提供方的观测时间戳与获取时间分别保留，即使数据来自缓存也是如此。

地址到 Basename 的解析结果会反向解析回原始地址。新鲜资金池涵盖 Uniswap v4；代币归属可能为 null，资金池年龄是根据区块高度估算的，而 funded 记录的是观测到的流动性事件，并非以 USD 计价的流动性估值。

钱包和雷达监控

对于 /api/watch/address/:address，保持不透明游标不变，并将其作为 since 传入。在计划轮询恢复之前，只要 hasMore 为 true，就继续调用。每次调用读取一页提供方数据；partial 和 coverage.complete 用于报告该次扫描是否已读完。也接受初始 ISO 时间戳。

轮询重叠时间为 120 秒，最多记住 100 个交易哈希。请在使用这些数据的 Agent 中按哈希去重，尤其是在 coverage.replayPossible 为 true 时。这些限制无法涵盖所有延迟索引、较早的链重组或索引器缺口。

雷达监控使用 ISO 游标遍历经过流动性筛选并按排名排序的列表。其 coverage 始终为 partial：被省略或延迟索引的资金池可能会被漏掉。价格提醒监控会报告阈值结果，且没有游标。

已发布历史记录和评分卡

快照工作流会将选定的 scout 观测结果写入 data/scout/，并将其发布到 git。历史记录读取会将索引和快照字节固定到同一个不可变修订版本，并通过 provenance.revision 以及 commit/raw 链接公开。付款交易是结算记录；它无法验证快照内容，也不能证明捕获时间。

对于评分卡，days 选择最新发布的 N 天快照，而非严格的日历回溯范围。代币使用所选时间窗口内首次出现的记录，因此持有期各不相同。Coverage 会报告缺失的快照、未评估的资金池和不可用的报价。无法获取时，价格变化和结果会保持为 null。liquidityGone=true 表示在所选提供方交易对中观测到的流动性低于 $100；这并不能证明所有流动性都已消失。中位数仅使用有价格的观测值。这些选定样本并非 Base 上所有项目启动情况的完整记录。

响应、失败与就绪状态

成功的数据响应包含 meta.requestId、servedAt、observedAt、ageSeconds、dataNetwork 和 paymentNetwork。无法获取的观测时间戳和数据时效将保留为 null。HTTP X-Request-Id 标头用于标识请求。

结构化 API 错误包含 error、code、retryable、retryAfter 和 requestId。常见状态码包括：输入无效时为 400，请求体过大时为 413，触发速率限制时为 429，上游不可用时为 502，以及超时时为 504。结算尝试结果未知时，将返回 paymentOutcome: "unknown" 和 retryable: false。如果提供了 Retry-After，请遵循其指示；不要自动重试结果不明确的已签名付款。

免费的 /api/health 端点用于报告存活状态。/api/ready 会通过有时限的探测检查 facilitator 支持和 Base RPC，并将结果缓存 15 秒；未就绪时返回 503。就绪状态并不保证每个数据提供方都可用。

运行自己的服务

托管服务运行在 Hetzner 上，使用 Docker/Caddy。推送到 main 的代码会在 GitHub CI 成功且候选版本通过 API 和代理检查后自动部署。请参阅自动部署运行手册和迁移验证记录。

需要 Node.js 22 或更高版本。

git clone https://github.com/tevfikefeaydin/agenttoll
cd agenttoll
npm install
cp .env.example .env
# Replace ADDRESS with your public receiving wallet address.
npm run dev

默认地址为 http://localhost:4021，使用 Base Sepolia 付款。ADDRESS 为必填项；如果保留占位符，或使用零地址／格式错误的地址，服务将无法启动。不要将生产钱包密钥用作服务端的 ADDRESS：ADDRESS 是公开的收款地址，不是私钥。

设置	含义
ADDRESS	必填的非零公开收款地址
NETWORK	base-sepolia（默认值）或 base；仅控制结算
PUBLIC_URL	用于发现服务的公开 URL；本地默认为 http://localhost:PORT，在 Vercel 上则使用 Vercel 主机
PORT	本地端口，默认为 4021
REQUEST_TIMEOUT_MS	请求的总截止时间，默认为 25000；允许范围为 100–120000
PAUSED_ENDPOINTS	可选的逗号分隔目录路径；付款前返回 503，在目录中标记 available:false，并从活动发现中排除。计划预热会跳过已暂停路由；在恢复前，手动修复任务仍会失败。
TRUST_PROXY	false、1–5 个受信任跳数，或明确的 IP/CIDR 条目；本地默认为 false，在 Vercel 上为一跳
FACILITATOR_URL	默认为 https://x402.org/facilitator；在主网上默认选择 CDP
CDP_API_KEY_ID / CDP_API_KEY_SECRET	使用默认的主网 CDP facilitator 时，两者均为必填项
BLOCKSCOUT_API_KEY	可选的上游配额凭证
ADDRESS_ACTIVITY_PROVIDER	仅用于地址活动：blockscout（默认值）或 ankr。Ankr 使用 Base 索引交易 API，包括零值调用和已回滚的交易。
ANKR_API_KEY	地址活动使用 Ankr 时必填。请存储在私有运行时配置中；切勿提交真实令牌。

Ankr 地址监控游标是不透明的，且绑定到特定提供方。在 Ankr 上使用现有的 Blockscout 游标时，会重新开始其原始时间窗口，同时保留近期去重记录；coverage.replayPossible 会提示迁移可能重放较早的交易。 请处理完所有 hasMore 分页，并按交易哈希去重。每次调用最多读取 50 笔已索引的确认交易。此数据流不包含待处理交易、内部调用或代币转账日志。验证其 Base 访问和分页功能后，再启用该提供方，并从 PAUSED_ENDPOINTS 中移除地址监控路由。

除 localhost 外，URL 设置均要求使用 HTTPS。请根据实际部署配置 PUBLIC_URL 和 TRUST_PROXY。每个实例的速率限制为每个 IP 每分钟 60 次免费 API／发现请求和 600 次付费路由请求；未签名的报价和已签名的重试都会计入。这些限制不会在多个实例之间共享。

不带签名调用付费端点时，只会查看其报价：

curl -i http://localhost:4021/api/price/eth
# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: <base64 x402 v2 quote>

浏览器演示会从同源 Agent 卡中读取自托管收款地址／网络，验证显示的报价，并且只对这些条款进行签名。它支持 Base 和 Base Sepolia，并使用注入钱包的 RPC。

有限额度的付费客户端

src/pay.ts 提供 payingFetch(privateKey, network, options?)。每个客户端实例默认的有限预算为 1 USDC，总期限为 30000 ms。报价不能超过已注册端点的价格。可选的 maxPerCallUsdc 参数可进一步降低此上限。并发调用的预算检查和预留操作是原子的。

import { payingFetch } from "./src/pay.js";

const key = process.env.AGENT_PRIVATE_KEY;
if (!key) throw new Error("AGENT_PRIVATE_KEY is required");
const client = payingFetch(key, "base", {
  baseUrl: "https://agenttoll.app",
  totalBudgetUsdc: "1",
  maxPerCallUsdc: "0.008",
  timeoutMs: 30_000,
});
console.log(await client.getPaymentQuote("/api/price/eth")); // no payment
const response = await client.fetchWithPayment("/api/price/eth");
console.log(await response.json());
console.log(client.getPaymentBudget());

成功执行上述签名请求会消耗真实的主网 USDC。getPaymentBudget 会报告总额、已花费金额、已预留金额和剩余金额。签名失败，或超时／取消时仍有待处理签名，都会保留相应预留金额。预算会随客户端实例重置，不会撤销先前的授权。调用方的 AbortSignal 会得到遵从；重定向和未注册的路由会被拒绝。

对于自定义源站，请传入 baseUrl 和明确指定的可信收款方。两个 TypeScript 示例默认使用 localhost，在此情况下可能会复用服务端公开的 ADDRESS。对于远程主机，它们不会复用 ADDRESS。AGENTTOLL_NETWORK 的优先级最高；否则 localhost 使用 NETWORK（默认值为 base-sepolia），而远程示例／脚本默认使用 base。

示例和付费脚本接受 AGENTTOLL_BUDGET_USDC、AGENTTOLL_MAX_PER_CALL_USDC 和 AGENTTOLL_TIMEOUT_MS。若要使用远程测试网服务，请明确设置 AGENTTOLL_NETWORK=base-sepolia 和 AGENTTOLL_RECIPIENT。测试网 USDC 不能用于支付托管的主网 API。

npm run example:client
npm run example:langchain

这些命令会使用 AGENT_PRIVATE_KEY 发起付费请求。LangChain 工具会转发框架的取消信号。snapshot／demo／findings 脚本也使用此有限额度辅助函数；由于它们会导入 dist，请先构建。scripts/demo.mjs --dry 仅执行经过验证的报价检查。

CrewAI Python 示例使用独立的有限额度客户端，依赖项已固定，设有 $0.003 的代币安全上限，并执行可信源站／收款方／网络检查及共享有限预算。其操作期限也涵盖签名和响应正文读取。安装方法及如何处理不明确的付款结果，请参阅该指南。

MCP

MCP 软件包版本为 0.14.0，包含 21 个付费工具和两个免费工具。不设置 AGENT_PRIVATE_KEY 即可启动仅报价模式：

{
  "mcpServers": {
    "agenttoll": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

免费工具为 get_payment_budget 和 get_payment_quote。付费工具为 get_price、get_base_gas、get_trending、get_base_token_price、get_base_address_info、get_fear_greed、get_base_trending_pools、get_market_brief、get_new_token_radar、get_try_premium、get_try_spread、get_base_portfolio、check_token_safety、scout_new_tokens、get_fresh_pools、get_radar_history、get_radar_scorecard、resolve_basename、watch_base_address、watch_new_tokens 和 watch_price_alert。

添加 AGENT_PRIVATE_KEY 以启用付款，并设置 AGENTTOLL_BUDGET_USDC 以选择会话限额。MCP 默认使用托管的主网源站；使用自定义源站时，必须设置 AGENTTOLL_RECIPIENT。get_payment_quote 接受已注册的端点路径，不接受任意 URL。工具取消会传递到付款 HTTP 请求。所有价格和配置请参阅 mcp/README.md。

将 0.13.0 或更早版本的安装升级时，请将软件包参数改为 [email protected]，并重启 MCP 进程。那些较旧的已发布软件包不提供免费的报价／预算工具，也不具备文档中说明的累计预算、可信收款方和取消控制功能。正在运行旧代码的进程不会自行更新。

HTTP 服务使用 x402 v2。请将签名后的重试请求发送为 PAYMENT-SIGNATURE，而非旧版 X-PAYMENT；从 PAYMENT-REQUIRED 读取报价，从 PAYMENT-RESPONSE 读取收据。请使用 v2 客户端，不要仅仅重命名 v1 载荷的请求头。对于被拒绝的旧版请求，服务会明确提供迁移指引。地址监控游标必须视为不透明值并原样传递；只有初始 since 值可以是 ISO 时间戳。

发现与开发

• 目录
• OpenAPI
• x402 发现
• Agent 卡片
• llms.txt

npm test                 # deterministic offline regressions
npm run typecheck        # API, browser and MCP
npm run check:generated  # manifests, descriptions, examples and version consistency
npm run build            # synchronize shared files, compile and build browser bundle
npm run build:web        # browser bundle only
npm run brand:png        # brand exports

开发检查使用模拟的外部数据／支付边界，不会发送真实付款或部署更改。根目录和 MCP 是独立的依赖树；请分别审计。有关凭据、信任边界和已知限制，请参阅 SECURITY.md。

使用 npm run ops:check 执行有界的、未签名的运行状况／目录／报价检查；使用 npm run ops:data 查看实际快照时效和来源覆盖情况；使用 npm run ops:report -- --input requests.ndjson 生成离线用量／错误／延迟及支付诊断摘要。构建完成后，保活和侦察快照脚本支持显式的 --dry-run 和 --quote-only 模式。统计快照任务会从已验证的最终确认点恢复，并重建一次旧版基线。有关限制、指标定义、只读监控、计划任务以及发布／回滚，请参阅 OPERATIONS.md。

更改 MCP 软件包版本后，请从代码库根目录运行 npm run generate。经授权的发布标签必须与 mcp-v 匹配；工作流会检查两棵依赖树、生成的产物、测试和类型，然后构建并对 npm 压缩包进行冒烟测试，再发布。

MIT。本代码库是独立的 AgentToll 项目，位于 agenttoll.app，与其他地方运营的同名服务无关。