x402 Trinity

x402-trinity

可直接替换的 fetch，让 AI Agent 能自行付费购买服务——设有严格的支出限额，无需托管钱包服务，也无需修改 Agent 自身代码。

零运行时依赖。压缩后 7 KB。买方和卖方均支持 TypeScript；买方支持 Python。

npm install x402-trinity

复制粘贴即可完成设置

为你的编码 Agent 准备好的说明。粘贴进去，它就会完成安装、配置钱包、设置支出限额、检查价格并购买——你只需说明要买什么，以及允许花多少钱。

→ 标准购买工具包

可购买收费 API、数据集、文件或其他 Agent 的服务——任何通过 HTTP 402 响应的资源。

你还可以在 x402trinity.com 查看更多设置，以及一个可供你通过产品赚钱或从市场购买商品的市场。

为什么

当 Agent 遇到收费资源时，会收到 402 Payment Required。如果没有工具处理这种情况，请求就会失败。

x402-trinity 会处理这一过程：读取质询，根据你设置的限额进行检查、签名并重试。所有操作都在本地完成——无需托管钱包服务或第三方 API，密钥也永远不会离开你的进程。

虽然存在 Gas 费，但付款方无需支付——根据 EIP-3009，由 facilitator 提交转账，因此 Agent 的钱包只需持有 USDC。

---

购买（Agent 付款）

import { createX402Fetch } from 'x402-trinity';

const x402Fetch = createX402Fetch({
  privateKey: process.env.X402_PRIVATE_KEY,   // never hardcode
  policy: {
    maxAmountPerRequest: '5000',              // 0.005 USDC max per call  (REQUIRED)
    totalBudget: '1000000',                   // 1.00 USDC lifetime       (REQUIRED)
    allowHosts: ['api.example.com'],
    allowPayTo: ['0x...'],
  },
});

const r = await x402Fetch('https://api.example.com/data');   // 402 handled, returns 200

或者修补全局对象，让未经修改的代码也能自动付款：

import { installX402 } from 'x402-trinity';
const uninstall = installX402(cfg);   // globalThis.fetch now pays 402s

充值前，请确认将用于付款的钱包：

X402_PRIVATE_KEY=0x... npx x402-trinity-whoami

它会打印地址以及该地址在每条链上的余额，绝不会打印密钥。如果显示的地址不是你预期的钱包，请勿转账。

销售（对资源收费并收款）

import { createX402Seller } from 'x402-trinity/seller';
import { createFileNonceStore } from 'x402-trinity/budget-file';

const seller = createX402Seller({
  payTo: '0xYourWallet',      // 100% of every payment lands here
  price: '10000',             // 0.01 USDC, atomic units
  network: 'base',
  facilitator: 'https://your-facilitator.example',   // REQUIRED — no default exists
  nonceStore: createFileNonceStore('./.x402-nonces.json'),  // REQUIRED — see below
});

// in any fetch-style handler:
const gate = await seller.guard(request);
if (gate.response) return gate.response;          // unpaid or refused — hand back the 402
return new Response(yourData, { headers: seller.receiptHeader(gate.settlement) });

这两个必填字段都是有意设置的。settling 涉及真实资金，因此不会默认指定 facilitator，也不会擅自猜测端点。重放保护必须在进程结束后仍然有效：内存中的重放保护会在重启时忘记所有已结算的付款，因此买方可能会重新提交已使用的授权，再次免费获取资源。构造函数会直接抛出异常，而不会让其中任何一项采用隐式设置。

卖方不会持有私钥，也不会接触资金。它只会报价，并要求 facilitator 验证和结算；资金会直接从买方转到你的链上地址。

此版本仅支持 Base + USDC。 其他任何 EVM 链都可通过 customChains 使用；你的地址在所有链上都相同。

---

功能

协议	x402 v1 和 v2，按响应检测。遇到未知版本和 MPP 质询时会明确说明原因并拒绝处理，绝不猜测
链	默认提供 Base 主网 + USDC。其他任何 EVM 链均可通过 customChains 使用
网络	支持短名称和 CAIP-2（eip155:8453）
密钥管理	可选择 privateKey、累加式 shards 或 remoteSign（HSM/MPC）——由你选择，而非由架构决定
速度	热运行 3.2 µs / 冷运行 1.0 ms（TypeScript）；1.2 µs / 1.7 ms（Python）
运行时	自动检测 Cloudflare Workers 并调整策略；也支持 Node、Bun、Deno
安全性	强制设置限额、允许列表、防止重复付款的对账机制、针对时序攻击强化的签名

添加其他链

Base 是默认链。签名过程与链无关，因此你可以添加所需的任何链，包括用于演练的测试网：

const fetch2 = createX402Fetch({
  privateKey: process.env.X402_PRIVATE_KEY,
  maxAmountPerRequest: '10000',
  totalBudget: '100000',
  customChains: {
    'base-sepolia': { id: 84532, asset: '0x036cbd53842c5426634e7929541ec2318f3dcf7e', name: 'USDC', version: '2' },
  },
});

请先对照已部署的合约验证该条目：调用 DOMAIN_SEPARATOR()，并检查其是否与此库计算出的值一致。错误的 name 或 version 会生成看似有效但会被合约拒绝的签名。

明确不会做的事

向链广播 · 持有资金 · 需要 Gas 或 RPC · 从付款中抽成（结构上不可能——EIP-3009 只有一个收款方）· 要求使用托管签名器 · 不设限额就付款 · 猜测它不支持的协议。

---

安全 — 使用真实资金前请阅读

必须设置上限。 maxAmountPerRequest 和 totalBudget 没有默认值；不设置它们，包装器就会拒绝构建。没有限额的自动付款器会造成资金泄漏，控制权在运行服务的人手中。

totalBudget 仅对单个实例有效。 这是一个内存计数器，会在重启、新客户端连接，以及每个 Cloudflare Worker 隔离环境中重置——而每个请求都会使用独立的隔离环境。在主网上，这会让终身限额变成单次请求限额。因此，主网需要持久化的 budgetStore，或显式设置 acknowledgeEphemeralBudget: true：

import { createFileBudgetStore } from 'x402-trinity/budget-file';

createX402Fetch({
  ...,
  budgetStore: createFileBudgetStore('./.x402-budget.json'),   // survives restarts
});

密钥存在进程中。 这是无需托管式签名器所要付出的代价。请做好限制：使用专用钱包，里面只存放你能接受损失的资金；设置 allowPayTo，确保即使密钥被窃取，也无法通过此包装器向陌生人付款；如果需要达到安全 enclave 级别的密钥托管，请使用 remoteSign。

时序加固是加固措施，不是证明。 秘密标量使用盲化以及始终执行加法和倍点，将时序差异从 99.6% 降至 12%（Python：从 99.9% 降至 1.1%）。BigInt 运算本身的耗时也会变化，纯 JavaScript 实现无法消除这一点。

---

MCP 服务 — 为 Agent 提供钱包

MCP 是助手获取工具的方式。此处提供三个工具：

tool
check_price	查看资源价格，无需付款
pay_and_fetch	获取资源，如果价格在限额内则付款
wallet_status	地址、余额、已支出金额、剩余金额

{
  "mcpServers": {
    "x402-trinity": {
      "command": "npx",
      "args": ["-y", "x402-trinity-mcp"],
      "env": {
        "X402_PRIVATE_KEY": "0x...",
        "X402_MAX_PER_REQUEST": "50000",
        "X402_TOTAL_BUDGET": "1000000",
        "X402_BUDGET_FILE": "./.x402-budget.json",
        "X402_ALLOW_HOSTS": "api.example.com",
        "X402_NETWORKS": "base"
      }
    }
  }
}

模型会决定何时运行这些工具。 无法与模型讨论预算，而且带付费墙的页面可以声称价格任意。因此，模型不能设置这些限额参数——限额来自环境，并且缺少 X402_PRIVATE_KEY、X402_MAX_PER_REQUEST 和 X402_TOTAL_BUDGET 时，服务会拒绝启动。

还要设置 X402_BUDGET_FILE，否则每次重启都会重置终身限额。设置 X402_ALLOW_HOSTS，这样无论付款请求看起来多么有说服力，其他内容都无法获得付款。使用只存放你能接受损失资金的钱包。

---

Python

使用相同的协议，且仅依赖标准库。仅支持付款——要对资源收费，请使用 TypeScript 卖家。适用于长时间运行的进程：设备端 Agent、机器人控制器、数据采集脚本。

from x402_trinity import X402Client, Policy

client = X402Client(
    private_key=os.environ["X402_PRIVATE_KEY"],
    policy=Policy(max_amount_per_request=5000, total_budget=1_000_000,
                  allow_hosts=["api.example.com"]),
)
body = client.urlopen("https://api.example.com/data").read()

也可以使用装饰器，让不了解付款的代码也能直接运行：

from x402_trinity import x402_telemetry

@x402_telemetry(private_key=KEY, policy=Policy(...))
def harvest():
    return urllib.request.urlopen("https://sensor.local/v1/lidar").read()

热路径耗时为 1.1 µs——长时间运行的控制器在首次付款后就会进入热状态。

---

开发

npm install
npm run build        # dist/*.js + *.min.js + *.d.ts

esbuild、typescript 和 wrangler 仅作为开发依赖，用于构建。发布的软件包没有任何运行时依赖。

许可证

Business Source License 1.1。源代码可供阅读、修改和非商业用途；生产用途已获许可，但不得以托管或管理服务的形式向第三方提供其功能。该许可证将于 2029-08-25 转为 MIT。请参阅 LICENSE。

本软件会转移资金——请阅读其中的附加声明，并设置支出上限。

便利费：每笔交易收取 0.1%，每 100 笔交易收取 1 美分。