Fatstack

Fatstack

一个非托管市场，让 AI Agent 能通过 x402 在 Base 上以 USDC 按次发现并支付 API 和 MCP 工具调用费用。

提供方列出工具。Agent 在注册表中找到工具并调用它。工具以 402 Payment Required 响应并给出价格。Agent 签署 USDC 付款授权后重试。调用成功，资金在钱包之间转移。

Fatstack 绝不经手资金。 不托管资金，没有提现功能，付款流程中也没有平台钱包，且不会存储私钥。付款直接从 Agent 的钱包转给提供方；或者在提供方的推广期结束后，通过不可变的拆分合约，在一笔原子交易中向提供方支付款项并收取 2% 的平台费用。如果某项更改能让 Fatstack 转移他人的资金，那就是一个 Bug。

一行命令，让 Agent 使用它

添加一个 MCP 服务，Agent 就能访问完整目录：

https://www.fatstack.net/api/mcp

查看可用工具免费；只有调用才会产生费用。无需账户、API 密钥或注册——钱包就是身份。付款需要使用支持 x402 的客户端；任何 MCP 客户端都可以浏览。已发布到官方 MCP 注册表，名称为 net.fatstack/registry。

本仓库包含你需要运行、审计或依赖的部分。市场应用本身是闭源的；集成方接触到的所有内容都在这里，采用 MIT 许可证。

---

付款流程

sequenceDiagram
    participant A as Agent
    participant T as Tool (provider)
    participant F as Facilitator
    participant C as USDC on Base

    A->>T: call the tool
    T-->>A: 402 Payment Required + price, asset, payTo, resource
    Note over A: signs an EIP-3009 authorisation<br/>covering exactly this resource
    A->>T: retry with X-PAYMENT
    T->>F: verify
    F-->>T: valid
    T->>T: run the handler
    T->>F: settle
    F->>C: transferWithAuthorization
    C-->>F: mined
    T-->>A: 200 + result

Agent 签署的是授权，而不是交易：它无需支付 Gas，也不会自行发送转账。中介服务负责广播授权并支付 Gas。

付款一经结算上链即为最终结果。转账无法撤销，也不提供退款。 这句话会出现在每个 402 响应体、每个报价对象和每个面向付款的页面中；它不是装饰——正是这一特性让按次定价无需托管即可实现。

---

快速入门——提供方

在现有路由前设置付费墙。只需两行配置，按次收费。

npm install @fatstack/x402

import { Hono } from 'hono';
import { paywall } from '@fatstack/x402';
import { honoPaywall } from '@fatstack/x402/hono';

const app = new Hono();

app.use(
  '/convert',
  honoPaywall(
    paywall({
      price: '0.001',               // USDC, per call
      wallet: '0xYourWallet',       // paid directly, wallet to wallet
      toolId: 'unit-convert',
      network: 'base-sepolia',      // test here before base
    }),
  ),
);

app.post('/convert', (c) => c.json({ celsius: 20, fahrenheit: 68 }));

Hono、Express 和 Next 的适配器分别通过独立入口发布—— @fatstack/x402/hono、/express、/next——因此在边缘运行时导入客户端不会连带引入 Node 框架。

完整指南（包括如何列出工具）：docs/provider-quickstart.md

快速入门——Agent

为模型提供一组可调用的付费工具，并设置不可超出的支出限额。

npm install @fatstack/ai-sdk-tools ai viem

import { generateText } from 'ai';
import { fatstackTools } from '@fatstack/ai-sdk-tools';
import { privateKeyToAccount } from 'viem/accounts';

const tools = await fatstackTools({
  wallet: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY),
  networks: ['base'],              // the catalogue is mainnet-only; USDC here is real
  guards: {
    maxPerDay: 0.5,                 // hard ceiling per UTC day, in USD
    maxPerCall: 0.01,               // refuse any single call dearer than this
  },
});

const { text } = await generateText({ model, tools, prompt: 'Convert 20C to F.' });

guards 是必需参数，没有默认值。可花钱的工具集绝不应意外构造，因此省略此参数会导致类型错误，而不是获得无限预算。

完整指南：docs/agent-quickstart.md

---

本仓库包含什么

路径	内容
sdk/	@fatstack/x402 — 提供方中间件和 Agent 客户端
integrations/ai-sdk-tools/	@fatstack/ai-sdk-tools — 一组按次付款的 Vercel AI SDK 工具
contracts/	USDC 付款拆分合约及其工厂，包含测试和部署门槛
facilitator/THREAT-MODEL.md	针对付款流程的六类攻击所作的书面评估
docs/	提供方和 Agent 快速入门指南，以及注册表格式

软件包： @fatstack/x402 · @fatstack/ai-sdk-tools 市场： fatstack.net · 注册表： registry.json

---

安全性

我们针对六类攻击对支付流程进行了审计：重放、并发、跨资源替换、验证与结算顺序、字段绑定和配置错误。 每类攻击都有书面结论，以及至少一项用于证明安全行为的测试；这些测试使用真实的支付协调方，并在 Base Sepolia 上进行真实结算，而非使用模拟对象。

facilitator/THREAT-MODEL.md 列出了审计结论。 contracts/SECURITY.md 介绍了分账合约。

其中一类攻击的结论是存在漏洞。即使你从未使用 Fatstack，也值得读一读，因为这是 x402 本身的特性，而非本实现的问题。

跨资源重放

EIP-3009 授权涵盖 (from, to, value, validAfter, validBefore, nonce)。它不涵盖购买的内容。因此，为某个工具支付而签署的授权，被同一提供方的另一个价格更高的工具接受了——收款方相同、资产相同、签名有效，而且签名材料中没有任何信息能说明所购内容。

该问题已在 Base Sepolia 上复现，并在链上完成结算： 0xd95ea771333c8f33f346c316fad30a64585156831d09e298d501c5b1e17e5659

已在 @fatstack/x402 0.2.0 中修复（当前版本为 0.2.1，代码相同，仅修正了 MIT 许可证元数据）。现在，中间件会将支付绑定到报价对应的资源；若不匹配，则会在调用支付协调方之前以 resource_mismatch 拒绝，因此不匹配的支付无需花费任何费用，也绝不会结算。向 Agent 报价的 402 内容没有任何变化。

如果你基于 x402 构建，但没有检查收到的支付是否针对当前资源报价，请立即检查。

促成合约设计的发现

早期版本的分账合约会将提供方作为调用参数。但该参数也不在付款人的签名涵盖范围内，因此任何观察到待处理授权的人，都可以提交该授权并填入自己的地址，从而拿走提供方的 98%。现在，提供方地址在部署时固定——每个提供方对应一个分账合约，其地址可通过 CREATE2 预先推导——因此移除了该参数，也消除了这类攻击。

请参阅 contracts/SECURITY.md 中的 改变设计的发现。

报告问题

发现了什么问题？对于已公开的问题，请提交 issue。对于支付流程中尚未披露的漏洞，请通过此代码库的 GitHub 安全公告私下报告，而不要在公开 issue 中报告。

---

合约未经审计

分账合约小巧、不可变，没有所有者、暂停功能、代理或升级路径。它通过了 34 项测试，其中包括一项针对 Base 上真实 USDC 的分叉测试；其费用计算也会与 TypeScript 实现使用同一份 vectors.json 进行断言，因此链上分账金额与报价不会出现偏差。

尚无第三方审查过该合约。在依赖它之前，请自行阅读——它只有约 15 行负责转移资金的代码，以及 100 行解释其设计依据的代码。

为此代码库做贡献

由于移除了运营相关细节，这里的部分文件与闭源代码库中的对应文件有所不同。.redactions 列出了这些文件，scripts/check-redactions.sh 会阻止将这些内容重新加入。推送前请运行该脚本。

许可证

MIT。请参阅 LICENSE。