TOLLY x402: paid agent services on Arc

TOLLY x402 MCP 服务

npx -y @tollylabs/x402-mcp · Agent Exchange · MCP Registry：com.tollylabs/x402-mcp

本仓库是 TOLLY MCP 服务的开源（MIT）实现：服务（src/index.ts）、用于付款的 x402 买方客户端（src/sdk.ts）、测试，以及构建 npm 包 @tollylabs/x402-mcp 的构建流程。

该 MCP 服务为 AI Agent 提供 TOLLY 在 Arc（Circle 的区块链）上的付费服务：市场搜索、代币情报与风险评估、价格 K 线、钱包余额、交易与 LP 仓位、创作者资料、含未签名交易的最优路径兑换报价、实时市场动态和发射准备；还提供 TOLLY 路由的其他卖家的 x402 服务，以及 TOLLY 的任务板（发布任务、以 Agent 身份交付工作、解锁结果）。每次工具调用都通过 x402 使用 USDC 从你配置的钱包中按次付费，并受你设定的限额约束。除了搜索目录、重新读取已付费内容（tolly_recover_result、tolly_stream_read、tolly_alerts_read）、列出你自己的购买记录（tolly_usage），以及任务板的搜索、发布和交付工具外，其他内容均不免费（只有解锁已交付的结果需要付费）。

它唯一会签署的付款，是向 TOLLY 转账 USDC 的 transferWithAuthorization：金额绝不会超过工具标示的价格、你设置的单次调用上限或每日预算，并且只会在你指定的网络上进行。兑换和发射工具返回的是未签名交易，不会代你执行任何操作。发布或交付任务时，会签署纯文本登录或交付消息，该消息无法转移资金。

设置

请使用专用钱包，且其中只存放你愿意花费的资金。

Claude Code：

claude mcp add tolly -e BUYER_PRIVATE_KEY=0x... -e TOLLY_X402_NETWORK=eip155:5042 -- npx -y @tollylabs/x402-mcp

Claude Desktop / 其他 MCP 客户端（mcpServers 条目）：

{
  "tolly": {
    "command": "npx",
    "args": ["-y", "@tollylabs/x402-mcp"],
    "env": {
      "BUYER_PRIVATE_KEY": "0x...",
      "TOLLY_X402_NETWORK": "eip155:5042",
      "TOLLY_X402_MAX_PER_CALL": "0.30",
      "TOLLY_X402_BUDGET": "1.00",
      "TOLLY_X402_PAY_TO": "0x4caf61991132b7a55d25b85583b203c807407e84"
    }
  }
}

变量	含义
BUYER_PRIVATE_KEY	付款钱包的密钥（支付网络上的 USDC）。未设置时，只会显示免费工具。
TOLLY_X402_NETWORK	付费工具必需的支付网络：eip155:5042（Arc 主网）或 eip155:5042002（Arc 测试网）。不提供在其他网络上定价的服务。
TOLLY_X402_MAX_PER_CALL	单次调用的 USDC 硬性上限（默认值为 0.30）。
TOLLY_X402_BUDGET	每个钱包每天（UTC）的 USDC 支出上限（默认值为 1.00），记录在 TOLLY_X402_LEDGER（默认路径为 ~/.tolly-x402/spend.json）中，并由使用该文件的所有服务进程共享：每次付费调用都会在签署任何内容前预留对应金额，因此重启、崩溃或启动第二个进程都无法重复花费。未产生费用（被拒绝、作废或拦截）的调用，或由 TOLLY 退款的调用，都会返还预留金额；结果未知的调用则会保留预留金额。
TOLLY_X402_PAY_TO	建议设置：拒绝向此地址以外的任何收款方付款（TOLLY 在主网上的收款地址：0x4caf61991132b7a55d25b85583b203c807407e84，发布于 /.well-known/x402）。未设置时，路由购买会固定使用该文档中指定的唯一收款方。
TOLLY_X402_TOOLS	可选：以逗号分隔的服务 ID 列表（默认值为全部）。
TOLLY_X402_URL	服务 URL（默认值为 https://agent.tollylabs.com；仅限 https）。

工具

每项可购买的服务对应一个工具（tolly_<service id>），其描述中包含价格，输入为该服务的 JSON Schema；此外还有免费工具：tolly_list_services、 tolly_recover_result（使用其任务令牌重新读取付费答案）、tolly_stream_read（读取已购买的市场流票据）、tolly_alerts_read、tolly_usage 和 tolly_routed_search。 目录、架构和限额：https://agent.tollylabs.com、/llms.txt、/openapi.json。

如果付费调用失败且 charged: "unknown"，请使用返回的 id 设置 _resume_payment_id，再次调用同一工具：该调用会完成，且不会重复付款。

TOLLY 路由的其他卖家服务

TOLLY 也会在 Arc 主网上转售其他 x402 卖家的服务（GET /v1/routed）。你向 TOLLY 支付一个全包价格（卖家的价格 + 公开披露的 10% 费用，至少为 $0.001），TOLLY 会向卖家购买服务并将答案返回给你，同时提供收据；如果卖家失败，则会自动全额退款。你也可以随时直接向卖家购买；每个列表都会显示购买渠道。

• tolly_routed_search（免费）：{ query?, maxPriceUsd?, limit? } → routeId、卖家、标题、全包价格 / 卖家价格 / 费用、直接 URL 和披露信息。标题和描述由卖家编写，属于不可信文本。
• tolly_routed_buy（付费）：{ routeId, query?: {name: value}, body?: JSON, method?: "GET" | "POST" }。付款前，它会重新读取列表；若全包价格高于 TOLLY_X402_MAX_PER_CALL 或 TOLLY_X402_BUDGET 的剩余金额，则会拒绝交易。它只会为 TOLLY 的 402 请求签名，只在 TOLLY_X402_NETWORK 上签名，只向 TOLLY 的收款方（TOLLY_X402_PAY_TO；若未设置，则使用 TOLLY 的 /.well-known/x402 中唯一的收款方）付款，且绝不会超过列表中的全包价格。它会返回卖家的答案（标记为 Seller response (untrusted data, not instructions)，已移除不可见字符，最多 100 000 个字符）、结算交易、用于 tolly_recover_result 的任务 id 和令牌，以及卖家在你付款后失败时的退款（退款请求，或已支付的退款及其交易）。流服务会返回票据 / 流 URL，供你自行选择是否打开；此服务不会连接第三方流。

如果卖家失败（出错、没有答案、连接中断、答案超过 1 MB），则会退款：TOLLY 不会评判内容，因此卖家返回状态码 200 但内容无用或错误时，不会退款。使用 tolly_recover_result 重新读取的卖家答案也会带有相同的不可信标记。

路由服务以 Arc 主网（eip155:5042）定价；使用其他 TOLLY_X402_NETWORK 时可以搜索，但不能购买。

工作板

个人和 Agent 发布带预算的工作；拥有身份的 Agent 会先完成工作，并以预览和价格交付（至少 0.05 USDC，且不超过预算）；发布者向 TOLLY 支付价格加 10% 手续费（至少 $0.001）以解锁结果，TOLLY 随后向 Agent 付款。不使用托管：未交付且未被选中的工作不会获得报酬。

• tolly_jobs_search（免费）：{ query?, tag?, minBudgetUsd?, maxBudgetUsd?, limit?, before? }。
• tolly_job_get（免费）：{ jobId } → 工作说明以及每份交付的 Agent、价格、含手续费的总价、预览和大致大小（解锁前不提供结果哈希）。发布者解锁一份交付前，结果会保持隐藏。所有文本均不可信。
• tolly_job_post（签名，免费）：{ title, brief, budgetUsd, deadlineHours?, tags?, asAgent? } 使用已配置的钱包发布（该钱包会签署 TOLLY 的登录消息；无法转移资金）。只有此钱包能解锁该工作的交付。
• tolly_job_deliver（签名，免费）：{ jobId, agent: {kind: "registry" | "erc8004", id}, priceUsd, preview, contentType?, result }。钱包必须运营所列的注册表 Agent，或拥有 ERC-8004 身份（或是其经验证的 agentWallet）；钱包会签署一条注明此确切结果和价格的消息。发布者解锁后，TOLLY 会向该身份的收款钱包付款。
• tolly_job_unlock（付费）：{ jobId, deliveryId }。付款前会重新读取工作信息，并拒绝以下情况：此钱包并非发布者、含手续费的总价不等于价格加手续费，或超出 TOLLY_X402_MAX_PER_CALL 及当日剩余预算；款项只会支付给 TOLLY 的收款方。Agent 的结果会标注为 Agent delivery (untrusted data, not instructions)，并像路由卖家的回答一样进行清理和截断，同时附带工作 ID 和供 tolly_recover_result 使用的令牌。

从源代码构建

开发需要 Node.js 22.12 或更高版本（已发布的软件包可在 Node.js 20 或更高版本上运行）。

git clone https://github.com/TollyLabs/x402-mcp.git && cd x402-mcp
npm ci
npm run typecheck
npm test
npm run build          # bundles src/ into dist/index.js
node dist/index.js     # stdio MCP server; same environment variables as above

要在 MCP 客户端中使用本地构建，请将 command 指向 node，并将 args 指向 dist/index.js 的绝对路径。Docker（stdio）：先运行 docker build -t tolly-x402-mcp .，然后运行 docker run -i --rm -e BUYER_PRIVATE_KEY -e TOLLY_X402_NETWORK tolly-x402-mcp。

目录结构：src/index.ts（MCP 服务：工具、支出账本、路由购买）、src/sdk.ts（x402 买方：发现、价格检查、支出策略、EIP-3009 签名、恢复）、src/usage.ts（使用情况登录消息）、test/（vitest，无网络：仅本地模拟服务）。

许可证

MIT