本课程将带你全面了解 x402 —— 一个开放的支付标准，专为网络服务的 API 和内容付费设计。通过本课程，你将学会如何利用 x402 实现 程序化支付，无需账户、会话或复杂的凭证管理即可收取或支付费用。
作者
经验值
阅读时间
Ken
本指南将帮助你了解 x402 —— 一个开放的支付标准，并帮助你开始使用 x402 构建或集成相关服务。
x402 是一种开放的支付标准，使服务能够通过 HTTP 直接为其 API 和内容访问收费。
它基于 HTTP 的 402 Payment Required（需要付款） 状态码构建，允许客户端在无需账户、会话或凭证管理的情况下，以编程方式为资源进行支付。
通过 x402，任何网络服务都可以在返回响应之前要求付款，并使用 加密原生支付（crypto-native payments） 来实现更高的速度、隐私性和效率。
x402 解决了现有支付系统中的关键限制问题：
卖家和买家都通过 HTTP 请求 直接交互，支付过程通过协议透明地处理。
x402 支持多种使用场景，包括：
数字内容付费墙
通过微交易实现货币化的微服务和工具
聚合并转售 API 功能的代理服务
从高层次来看，流程非常简单
买家向服务器请求资源。
如果需要付款，服务器返回 402 Payment Required 响应，并包含支付指引。
买家准备并提交支付数据。
服务器使用 x402 facilitator 的 /verify 和 /settle 接口验证并结算支付。
如果支付有效，服务器提供请求的资源。
欲了解更多详细信息，请参见：
客户端 / 服务器（Client / Server）
中介（Facilitator）
HTTP 402
x402 被设计为一个开放标准，我们很高兴能与社区一起构建 x402。 在路线图中，我们特别期待实现的一些项目包括：
为代理服务器和工具提供解决方案指南与模板，让 x402 集成尽可能简单
在 Solana（SVM）上提供完整方案支持
支持至 EVM & SVM 方案
使用 Permit 作为 transferWithAuthorization 的替代方法，为任意代币提供更简便的语义（可能通过 Permit 实现并支持至方案级别）
任意代币支持
面向 x402 兼容端点的生产就绪市场与信誉系统
我们的目标是让程序化商业（programmatic commerce）变得可访问、无需许可且对开发者友好。
本指南将引导你如何使用 x402 与需要支付的服务进行交互。完成本指南后，你将能够以编程方式发现支付要求、完成支付，并访问付费资源。
在开始之前，请确保你已经具备以下条件：
一只持有 USDC 的加密钱包（任意兼容 EVM 的钱包）
Node.js 和 npm，或 Python 和 pip
一个需要通过 x402 支付的服务
我们在仓库中提供了预先配置好的示例，包括 fetch、Axios 和 MCP 的示例。
npm install x402-axios
# or
npm install x402-fetch
该社区包展示了 AI 代理如何在 x402 中使用模型上下文协议（MCP）。我们正在努力将官方 MCP 规范尽快纳入 x402。
安装 MCP 支持所需的依赖包：
npm install x402-mcp ai @modelcontextprotocol/sdk
pip install x402
npm install viem
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";
// Create a wallet client (using your private key)
const account = privateKeyToAccount("0xYourPrivateKey"); // we recommend using an environment variable for this
pip install eth_account
from eth_account import Account
account = Account.from_key("your_private_key") # we recommend using an environment variable for this
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";
// 64-byte base58 secret key (private + public)
const signer = await createKeyPairSignerFromBytes(
base58.decode(process.env.SOLANA_PRIVATE_KEY!)
);
你可以使用 x402-fetch 或 x402-axios 自动处理 402 ‘需要付款’ 响应，并完成支付流程。
x402-fetch 扩展了原生的 fetch API，帮你处理 402 响应和支付相关的请求头。完整示例见此处。
import { wrapFetchWithPayment, decodeXPaymentResponse } from "x402-fetch";
// other imports...
// wallet creation logic...
const fetchWithPayment = wrapFetchWithPayment(fetch, account);
fetchWithPayment(url, { //url should be something like https://api.example.com/paid-endpoint
method: "GET",
})
.then(async response => {
const body = await response.json();
console.log(body);
const paymentResponse = decodeXPaymentResponse(response.headers.get("x-payment-response")!);
console.log(paymentResponse);
})
.catch(error => {
console.error(error.response?.data?.error);
});
x402-axios 为 Axios 添加了支付拦截器，因此你的请求会自动带上支付请求头并重试。
import { withPaymentInterceptor, decodeXPaymentResponse } from "x402-axios";
import axios from "axios";
// other imports...
// wallet creation logic...
// Create an Axios instance with payment handling
const api = withPaymentInterceptor(
axios.create({
baseURL, // e.g. https://api.example.com
}),
account,
);
api
.get(endpointPath) // e.g. /paid-endpoint
.then(response => {
console.log(response.data);
const paymentResponse = decodeXPaymentResponse(response.headers["x-payment-response"]);
console.log(paymentResponse);
})
.catch(error => {
console.error(error.response?.data?.error);
});
x402-mcp 为 MCP 客户端提供支付处理功能，使 AI 代理能够自动为工具支付费用。
import { convertToModelMessages, stepCountIs, streamText } from "ai";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { experimental_createMCPClient as createMCPClient } from "ai";
import { withPayment } from "x402-mcp";
// Create MCP client with payment capabilities
const mcpClient = await createMCPClient({
transport: new StreamableHTTPClientTransport(mcpServerUrl), // URL of your MCP server
}).then((client) => withPayment(client, {
account, // Your wallet account from step 2
network: "base" // or "base-sepolia" for testnet
}));
// Get available tools (both paid and free)
const tools = await mcpClient.tools();
// Use the tools with your AI model
const result = streamText({
model: "gpt-4", // or any AI model
tools,
messages: convertToModelMessages(messages),
stopWhen: stepCountIs(5), // Limit tool calls for safety
onFinish: async () => {
await mcpClient.close();
},
system: "ALWAYS prompt the user to confirm before authorizing payments",
});
特性:
自动检测 MCP 工具何时需要支付
透明处理 x402 支付流程
支持来自同一服务器的付费和免费工具
与 Vercel AI SDK 无缝集成
withPayment 包装器为任意 MCP 客户端添加支付功能。当调用某个工具需要支付时，它会使用你配置的钱包自动处理 x402 支付流程。
你可以使用 httpx 或 Requests 自动处理 402 ‘需要付款’ 响应，并完成支付流程。
两者都支持简单且可扩展的方式。简单方式会返回一个预配置的客户端，能够自动处理支付；可扩展方式则允许你使用已有的 session/客户端。这里讲解的是简单方式，可扩展方式请参考下方完整示例的 README。
from x402.clients.httpx import x402HttpxClient
# Other imports...
# Wallet creation logic ...
# Create client and make request
async with x402HttpxClient(account=account, base_url="https://api.example.com") as client:
response = await client.get("/protected-endpoint")
print(await response.aread())
from x402.clients.httpx import x402HttpxClient
# Other imports...
# Wallet creation logic ...
# Create client and make request
async with x402HttpxClient(account=account, base_url="https://api.example.com") as client:
response = await client.get("/protected-endpoint")
print(await response.aread())
在以下情况下，客户端会抛出错误：
请求配置缺失
该请求已尝试过支付
创建支付请求头时发生错误
安装 x402 客户端包
创建钱包客户端
使用提供的包装器/拦截器发起付费 API 请求
支付流程将自动为你处理
本指南将带你一步步完成与 x402 的集成，以便为你的 API 或服务启用支付功能。完成后，你的 API 将能够向买家和 AI 代理收取访问费用。
在开始之前，请确保你已经具备以下条件：
一个用于接收资金的加密钱包（任何 EVM 兼容钱包 均可）
已安装 Node.js 与 npm（或 Python 与 pip）
一个已经存在的 API 或服务器
我们在代码仓库中提供了 Node.js 和 Python 的预配置示例。
此外，我们还提供了一个 高级示例，展示如何使用 x402 SDK 来构建更复杂的支付流程。
安装 x402 Express 中间件（middleware） 包
npm install x402-express
npm install @coinbase/x402 # for the mainnet facilitator
安装 x402 Next.js 中间件（middleware） 包
npm install x402-next
npm install @coinbase/x402 # for the mainnet facilitator
安装 x402 Hono 中间件（middleware） 包
npm install x402-hono
npm install @coinbase/x402 # for the mainnet facilitator
这个社区包展示了如何将 MCP（Model Context Protocol） 与 x402 结合使用。
我们正在努力将 官方版 MCP 规范 纳入 x402，并将在不久后发布。
安装 x402-mcp 包：
npm install x402-mcp
npm install @coinbase/x402 # for the mainnet facilitator
安装 x402 Python 包：
pip install x402
pip install cdp # for the mainnet facilitator
将支付中间件集成到你的应用中。你需要提供：
完整示例请参见代码仓库（repo）中的示例。
import express from "express";
import { paymentMiddleware, Network } from "x402-express";
const app = express();
app.use(paymentMiddleware(
"0xYourAddress", // your receiving wallet address
{ // Route configurations for protected endpoints
"GET /weather": {
// USDC amount in dollars
price: "$0.001",
network: "base-sepolia",
},
},
{
url: "https://x402.org/facilitator", // Facilitator URL for Base Sepolia testnet.
}
));
// Implement your route
app.get("/weather", (req, res) => {
res.send({
report: {
weather: "sunny",
temperature: 70,
},
});
});
app.listen(4021, () => {
console.log(`Server listening at http://localhost:4021`);
});
完整示例请参见代码仓库中的示例。
由于这是一个 全栈（fullstack）示例，我们建议你基于该示例自行构建，并将下面的代码片段仅作为参考。
import { paymentMiddleware, Network } from 'x402-next';
// Configure the payment middleware
export const middleware = paymentMiddleware(
"0xYourAddress", // your receiving wallet address
{ // Route configurations for protected endpoints
'/protected': {
price: '$0.01',
network: "base-sepolia",
config: {
description: 'Access to protected content'
}
},
}
{
url: "https://x402.org/facilitator", // Facilitator URL for Base Sepolia testnet.
}
);
// Configure which paths the middleware should run on
export const config = {
matcher: [
'/protected/:path*',
]
};
完整示例请参见代码仓库（repo）中的示例。
import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { paymentMiddleware, Network } from "x402-hono";
const app = new Hono();
// Configure the payment middleware
app.use(paymentMiddleware(
"0xYourAddress", // your receiving wallet address
{ // Route configurations for protected endpoints
"/protected-route": {
price: "$0.10",
network: "base-sepolia",
config: {
description: "Access to premium content",
}
}
},
{
url: "https://x402.org/facilitator", // Facilitator URL for Base Sepolia testnet.
}
));
// Implement your route
app.get("/protected-route", (c) => {
return c.json({ message: "This content is behind a paywall" });
});
serve({
fetch: app.fetch,
port: 3000
});
这将创建一个 MCP 服务器端点，用于向 AI 代理（AI agents） 暴露付费工具。
这些工具在被调用时，会自动处理 x402 的支付要求。
import { createPaidMcpHandler } from "x402-mcp";
import z from "zod";
// import { facilitator } from "@coinbase/x402"; // For mainnet
const handler = createPaidMcpHandler(
(server) => {
server.paidTool(
"get_random_number",
"Get a random number between two numbers",
{ price: 0.001 }, // Price in USD
{
min: z.number().int().describe("Minimum value"),
max: z.number().int().describe("Maximum value"),
},
{},
async (args) => {
const randomNumber =
Math.floor(Math.random() * (args.max - args.min + 1)) + args.min;
return {
content: [{ type: "text", text: randomNumber.toString() }],
};
}
);
// Add more paid tools as needed
server.paidTool(
"premium_feature",
"Access premium functionality",
{ price: 0.01 },
{
input: z.string(),
},
{},
async (args) => {
// Your premium feature logic
return {
content: [{ type: "text", text: "Premium result" }],
};
}
);
},
{
serverInfo: {
name: "your-mcp-server",
version: "1.0.0",
},
},
{
recipient: "0xYourAddress", // Your receiving wallet address
facilitator,
// network: "base-sepolia", // For testnet, "base" for mainnet
}
);
export { handler as GET, handler as POST };
完整示例请参见代码仓库（repo）中的示例。
import os
from typing import Any, Dict
from dotenv import load_dotenv
from fastapi import FastAPI
from x402.fastapi.middleware import require_payment
from x402.types import EIP712Domain, TokenAmount, TokenAsset
# Load environment variables
load_dotenv()
app = FastAPI()
# Apply payment middleware to specific routes
app.middleware("http")(
require_payment(
path="/weather",
price="$0.001",
pay_to_address="0xAddress",
network="base-sepolia",
)
)
@app.get("/weather")
async def get_weather() -> Dict[str, Any]:
return {
"report": {
"weather": "sunny",
"temperature": 70,
}
}
完整示例请参见代码仓库（repo）中的示例。
import os
from flask import Flask, jsonify
from dotenv import load_dotenv
from x402.flask.middleware import PaymentMiddleware
from x402.types import EIP712Domain, TokenAmount, TokenAsset
app = Flask(__name__)
# Initialize payment middleware
payment_middleware = PaymentMiddleware(app)
# Apply payment middleware to specific routes
payment_middleware.add(
path="/weather",
price="$0.001",
pay_to_address="0xAddress",
network="base-sepolia",
)
以下是支付中间件配置的接口定义：
interface PaymentMiddlewareConfig {
description?: string; // Description of the payment
mimeType?: string; // MIME type of the resource
maxTimeoutSeconds?: number; // Maximum time for payment (default: 60)
outputSchema?: Record; // JSON schema for the response
customPaywallHtml?: string; // Custom HTML for the paywall
resource?: string; // Resource URL (defaults to request URL)
}
当请求在未付款的情况下访问此路由时，你的服务器将返回 HTTP 402 Payment Required 状态码，并附带支付说明。
进行验证时，请确保以下几点：
向你的端点发起请求（例如：curl http://localhost:3000/your-endpoint）。
服务器返回 402 Payment Required，并在响应体中包含支付说明。
使用兼容的客户端、钱包或自动化代理完成支付。
通常这需要签署一个 支付负载（payment payload），该过程由买家快速入门指南（Quickstart for Buyers）中介绍的客户端 SDK 处理。
再次发起请求，这次在请求头中包含 X-PAYMENT，其内容为加密的支付凭证（即 payment payload）。
服务器通过 facilitator 验证支付；若验证通过，则返回你的实际 API 响应，例如：
{ "data": "Your paid API response." }
如果出现以下错误：
Cannot find module 'x402-hono/express' or its corresponding type declarations.
请将 Hono 示例项目 中的 tsconfig.json 文件添加到你的项目中。
同时，请在每个示例项目中运行以下命令以安装依赖：
npm install
本快速入门指南介绍了以下内容：
安装 x402 SDK 及相关中间件
将支付中间件添加到你的 API 并进行配置
测试你的集成
你的 API 现在已经可以通过 x402 接收加密货币支付了。
数十年来，HTTP 402 Payment Required 一直被保留为“未来使用”。
而 x402 的出现，解锁了这一潜能——让互联网摆脱了它的“原罪”。
HTTP 402 是一种标准但很少被使用的 HTTP 响应状态码，表示 访问某个资源前需要支付费用（Payment Required）。
在 x402 协议中，这个状态码被激活，用于以下目的：
通知客户端（买家或代理）当前请求的资源需要支付费用。
传达支付的详细信息，例如金额、币种和目标地址。
提供完成程序化支付所需的信息，使客户端能够自动完成支付流程。
HTTP 402 的主要目的，是为访问网络资源提供一种 无摩擦、API 原生的支付机制，特别适用于以下场景：
机器对机器（M2M）支付（例如 AI 代理之间的交易）
按次付费模式，如 API 调用或付费内容访问（paywalled content）
无需注册账户或传统支付渠道的微支付（Micropayments）
使用 402 状态码 让 x402 协议 保持对 Web 的原生兼容性，并且可以轻松集成到任何基于 HTTP 的服务中。
HTTP 402 是 x402 协议的核心基础，它使服务能够在 HTTP 响应中直接声明支付要求。它的作用包括：
指示需要支付（Signals payment is required）
传达必要的支付详情（Communicates necessary payment details）
无缝集成于标准 HTTP 工作流程中（Integrates seamlessly with standard HTTP workflows）
本页将说明 x402 协议 中客户端与服务器的角色和职责。
理解这些角色对于设计、构建或集成使用 x402 进行 程序化支付 的服务至关重要。
注意
Client（客户端） 指的是发起 HTTP 请求的技术组件，在实际应用中，它通常代表 资源的购买方（Buyer）。
Server（服务器） 指的是响应 HTTP 请求的技术组件，在实际应用中，它通常代表 资源的销售方（Seller）。
客户端是发起请求以访问付费资源的实体。
客户端可以包括：
人工操作的应用程序
自主代理
代表用户或系统执行操作的程序化服务
发起请求：向资源服务器发送 HTTP 请求。
处理支付要求：读取返回的 402 Payment Required 响应，并提取其中的支付详情。
准备支付负载：根据提供的支付要求构建一个有效的 支付负载（payment payload）。
携带支付信息重新请求：在请求头中加入包含已签名支付负载的 X-PAYMENT，重新发起请求。
客户端除了自身的 加密钱包 外，无需管理任何账户、凭证或会话令牌。
所有交互都是 无状态（stateless） 的，并通过标准的 HTTP 请求 完成。
服务器是负责提供资源并执行访问付费要求的实体。
服务器可以包括：
API 服务
内容提供者
任何需要实现变现的可通过 HTTP 访问的资源
服务器无需管理客户端身份或维护会话状态。
每个请求的 验证（verification） 和 结算（settlement） 都是独立处理的。
在 x402 协议 中，客户端与服务器之间的典型交互流程如下：
客户端发起请求：客户端向服务器请求访问一个付费资源。
服务器返回支付请求：服务器以 402 Payment Required 状态码响应，并在响应体中包含支付要求。
客户端生成并提交支付负载：客户端根据支付要求准备并提交一个 支付负载（payment payload）。
服务器验证支付：服务器验证该支付负载，可以在本地进行，也可以通过 facilitator 服务 验证。
服务器结算支付：验证成功后，服务器完成支付结算并确认交易。
服务器返回资源：若支付成功，服务器将请求的资源返回给客户端。
在 x402 协议 中：
客户端 负责请求资源，并提供已签名的 支付负载（payment payload）。
服务器 负责执行支付要求，验证交易，并在支付成功后提供所请求的资源。
这种交互是 无状态（stateless） 的、HTTP 原生（HTTP-native） 的，并且同时兼容 人工应用程序 和 自动化代理（automated agents）。
本页将说明 x402 协议 中 撮合方（Facilitator） 的角色。
撮合方 是一个可选但强烈推荐的服务，用于简化客户端（买家）与服务器（卖家）之间的 支付验证与结算流程。
撮合方是一种服务，用于：
验证客户端提交的支付负载。
代表服务器在区块链上完成支付结算。
通过使用 撮合方（Facilitator），服务器无需自行维护与区块链的直接连接，也不必实现复杂的支付验证逻辑。
这不仅降低了操作复杂度，还能确保交易得到 准确且实时的验证。
验证支付：确认客户端的 支付负载（payment payload） 是否符合服务器声明的支付要求。
结算支付：将已验证的支付提交到区块链，并监控交易确认状态。
返回结果：向服务器返回验证与结算结果，供服务器决定是否向客户端提供所请求的资源。
撮合方 不托管资金，也不充当保管人角色。它仅根据客户端提供的已签名支付负载，执行 链上交易的验证与执行。
使用 撮合方可以带来以下优势：
降低操作复杂度：服务器无需直接与区块链节点交互。
协议一致性：在不同服务间实现标准化的验证与结算流程。
更快的集成速度：服务可在几乎无需区块链相关开发的情况下开始接受支付。
虽然可以在本地实现验证与结算逻辑，但使用 撮合方（Facilitator） 能更快地推进集成落地，并确保协议行为的正确性。
CDP 的撮合方：在 Base 主网上提供 免手续费的 USDC 结算。
PayAI 的撮合方：部署于 Solana、Base、Polygon 等多个网络，更多信息与文档可参考
🔗 https://docs.payai.network/x402。
客户端向资源服务器发起 HTTP 请求。
资源服务器 返回 402 Payment Required 状态码，并在响应体中包含一个 Payment Required Response JSON 对象。
客户端 从服务器响应的 accepts 字段中选择一个 paymentDetails，并根据所选方案的结构创建一个 支付负载（Payment Payload）。
客户端 在后续请求中，将 Payment Payload 放入 X-PAYMENT 请求头中，再次向资源服务器发送 HTTP 请求。
资源服务器 验证支付负载的有效性，可以通过 本地验证，或通过向 撮合方服务器（Facilitator Server） 的 /verify 端点发送 Payment Payload 和 Payment Details 来完成。
撮合方服务器 根据 Payment Payload 的 scheme 与 networkId 执行验证，并返回 Verification Response（验证响应）。
若 验证响应有效，资源服务器继续处理请求；若 验证无效，则返回 402 Payment Required 和新的 Payment Required Response JSON 对象。
资源服务器 可选择自行与区块链交互完成结算，或通过向 撮合方服务器 的 /settle 端点发送 Payment Payload 与 Payment Details 来完成支付。
撮合方服务器 根据 scheme 与 networkId 将支付提交至区块链。
撮合方服务器 等待区块链上支付确认完成。
撮合方服务器 向资源服务器返回 Payment Execution Response（支付执行响应）。
资源服务器 向客户端返回 200 OK 响应，在响应体中包含所请求的资源；若支付成功，还会在响应头中附加 X-PAYMENT-RESPONSE，其内容为以 Base64 编码的 结算响应（Settlement Response）JSON。
撮合方（Facilitator） 在 x402 协议 中充当一个 独立的验证与结算层。它帮助服务器在无需维护区块链基础设施的情况下，完成 支付验证 与 链上交易提交。
在 x402 协议 中，钱包（Wallet） 既是支付机制，也是买家与卖家的 唯一身份标识。
钱包地址用于 发送、接收和验证支付，同时也在协议内部充当 身份标识符（identifier） 的作用。
买家使用钱包来：
存储 USDC 或其他加密货币
签署支付负载（payment payloads）
以程序化方式授权链上支付（onchain payments）
钱包使买家（包括 AI 代理）能够在 无需创建账户或管理凭证 的情况下完成交易。
卖家使用钱包来：
接收 USDC 或其他加密货币支付
在服务器配置中定义其支付接收地址（payment destination）
卖家的钱包地址会包含在提供给买家的 支付要求（payment requirements） 中。
我们推荐使用 CDP 的 Wallet API，以实现 程序化支付（programmatic payments） 和 安全的密钥管理（secure key management）。
买家（Buyers） 使用钱包来支付服务费用。
卖家（Sellers） 使用钱包来接收付款。
钱包地址 同时也是协议中的 唯一身份标识符（unique identifier）。
x402 Bazaar 是 x402 生态系统的发现层（Discovery Layer），它是一个 可被机器读取的目录（machine-readable catalog），帮助开发者和 AI 代理发现并集成 兼容 x402 的 API 端点。你可以把它理解为一个 可支付 API 的搜索索引（search index for payable APIs）， 使得服务的发现与调用可以实现 自动化与自主化（autonomous discovery and consumption）。
x402 Bazaar 目前仍处于 早期开发阶段。我们的愿景是将其打造为 “智能代理端点的 Google”，但目前它更像是 “Yahoo 搜索” —— 已具备基本功能，但仍在不断完善中。随着我们收集用户反馈并扩展功能，相关的 特性与 API 可能会有所调整。
Bazaar 解决了 x402 生态系统中的关键问题——可发现性（discoverability）。没有它，兼容 x402 的端点就像是隐藏在巨大集市中的摊位，难以被找到。
Bazaar 提供以下功能：
对于买家（API 使用者）：可通过程序化方式发现可用的 x402 启用服务，并了解其功能、定价与数据结构（schemas）。
对于卖家（API 提供者）：你的 x402 启用服务 将自动对全球的开发者与 AI 代理可见，提升曝光度与接入率。
对于 AI 代理（AI Agents）：无需预先集成，即可动态发现服务 —— 查询、发现、支付并使用。
Bazaar 当前的工作方式如下：
Bazaar 目前提供一个简单的 /list 端点，用于返回所有已在 CDP 撮合方（facilitator） 注册的 x402 兼容服务。
当服务使用 CDP 撮合方时，会被自动加入该列表，因此卖家几乎无需额外操作即可实现 无摩擦式的服务发现（frictionless discovery）。
虽然目前 CDP 撮合方（Facilitator） 已经上线了一个可用的 发现层（Discovery Layer），但 市场项目（marketplace items） 的规范是 开放的，并且属于 x402 协议方案（x402 scheme） 的一部分。这意味着 —— 任何撮合方 都可以根据该规范 创建自己的发现层（Discovery Layer）。
发现（Discovery）：客户端通过查询 /list 端点，获取可用的服务列表。
选择（Selection）：根据价格、功能与需求选择合适的服务。
执行（Execution）：使用 x402 协议 进行支付并访问所选服务。
零人工设置（No Manual Setup）：无需 API 密钥、无需创建账户，只需 发现并支付 即可使用。
获取所有可用的 x402 兼容端点：
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources
推荐的使用方式是按照下方说明，通过 useFacilitator 钩子（hook）来调用该端点。
列表中的每个端点包含以下字段：
{
"accepts": [
{
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // ERC-20 token contract address accepted for payment (here, USDC on Base)
"description": "", // Optional description of the accepted payment
"extra": {
"name": "USD Coin", // Human-readable name of the asset
"version": "2" // Version of the asset, if applicable
},
"maxAmountRequired": "200", // Maximum amount (in atomic units, e.g USDC has 6 decimals) required for the service
"maxTimeoutSeconds": 60, // Maximum time (in seconds) the service will wait for payment before expiring
"mimeType": "", // Expected MIME type for the response (optional/empty if not specified)
"network": "base", // network where payment is accepted (e.g., 'base' for Base L2)
"outputSchema": {
"input": {
"method": "GET", // HTTP method to use when calling the resource
"type": "http" // Type of resource (e.g., 'http' endpoint)
},
"output": null // Output schema (null if not specified)
},
"payTo": "0xa2477E16dCB42E2AD80f03FE97D7F1a1646cd1c0", // Address to which payment should be sent
"resource": "https://api.example.com/x402/last_sold", // The actual API endpoint/resource URL
"scheme": "exact" // Payment scheme (e.g., 'exact' means exact amount required)
}
],
"lastUpdated": "2025-08-09T01:07:04.005Z",
"metadata": {}, // Additional metadata about the service (empty object if none)
"resource": "https://api.prixe.io/x402/last_sold", // The main resource URL for this service
"type": "http",
"x402Version": 1 // Version of the x402 protocol supported
},
请在此处查看 Python 和 Node.js 的完整示例。
使用 撮合方客户端（facilitator client） 获取可用的 x402 服务列表：
Typescript:
import { useFacilitator } from "x402/verify";
import { facilitator } from "@coinbase/x402";
const { list } = useFacilitator(facilitator);
// Fetch all available services
const services = await list();
// NOTE: in an MCP context, you can see the full list then decide which service to use
// Find services under $0.10
const usdcAsset = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
const maxPrice = 100000;
const affordableServices = services.items.filter(item => item.accepts.find(paymentRequirements => paymentRequirements.asset == usdcAsset && Number(paymentRequirements.maxAmountRequired) < maxPrice));
Python:
from x402.facilitator import FacilitatorClient, FacilitatorConfig
from cdp.x402 import create_facilitator_config
# Set up facilitator client
facilitator_config = create_facilitator_config()
facilitator = FacilitatorClient(facilitator_config)
# Fetch all available services
services = await facilitator.list()
# NOTE: in an MCP context, you can see the full list then decide which service to use
# Find services under $0.10
usdc_asset = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
max_price = 100000
affordable_services = [
item
for item in services.items
if any(
payment_req.asset == usdc_asset
and int(payment_req.max_amount_required) < max_price
for payment_req in item.accepts
)
]
找到合适的服务后，使用 x402 客户端（x402 client） 调用该服务：
Typescript:
import { withPaymentInterceptor } from 'x402-axios';
import axios from 'axios';
import { privateKeyToAccount } from 'viem/accounts';
// Set up your payment account
const account = privateKeyToAccount('0xYourPrivateKey');
// Select a service from discovery
const selectedService = affordableServices[0];
// Create a payment-enabled client for that service
const client = withPaymentInterceptor(
axios.create({ baseURL: selectedService.endpoint }),
account
);
// Select the payment method of your choice
const selectedPaymentRequirements = selectedService.accepts[0];
const inputSchema = selectedPaymentRequirements.outputSchema.input;
// Build the request using the service's schema
const response = await client.request({
method: inputSchema.method,
url: inputSchema.resource,
params: { location: 'San Francisco' } // Based on inputSchema
});
console.log('Response data:', response.data);
Python:
from x402.client import X402Client
from eth_account import Account
# Set up your payment account
account = Account.from_key('0xYourPrivateKey')
client = X402Client(account)
# Select a service from discovery
selected_service = affordable_services[0]
# Select the payment method of your choice
selected_payment_requirements = selected_service.accepts[0]
input_schema = selected_payment_requirements.output_schema.input
# Make the request
response = client.request({
method=input_schema.method,
url=input_schema.resource,
params={ "location": "San Francisco" } # Based on input_schema
})
print(f"Response data: {response}")
ChatGPT said: 如果你的 API 使用了最新版的 CDP 撮合方（facilitator） 来处理 x402 支付，并且在输入架构（input schema）中将 discoverable 标志 设为 true，那么该 API 将会被自动收录进 Bazaar（发现层）。
为了让你的服务在列表中展示得更完善，你可以在设置 x402 中间件（middleware） 时添加 描述（descriptions） 和 数据结构（schemas）。建议为每个参数编写清晰的说明，以便 AI 代理（agent） 能正确理解并调用你的端点：
Typescript:
// Next.js / Express / Hono
import { require402Payment } from 'x402-express';
app.use(require402Payment({
routes: {
"/api/weather": {
price: "$0.001",
network: "base",
config: {
discoverable: true, // make your endpoint discoverable
description: "Get current weather data for any location",
inputSchema: {
queryParams: {
location: {
type: string,
description: "City name or coordinates",
required: true
}
}
},
outputSchema: {
type: "object",
properties: {
temperature: { type: "number" },
conditions: { type: "string" },
humidity: { type: "number" }
}
}
}
}
}
}));
Python
# FastAPI / Flask
from x402 import require_payment
app.middleware("http")(
require_payment(
path="/weather",
price="$0.001",
pay_to_address=WALLET_ADDRESS,
network="base",
description="Get current weather data for any location",
discoverable=true, # make your endpoint discoverable <----
input_schema={
"queryParams": {
"location": {
"type": string,
"description": "City name or coordinates",
"required": true
}
}
},
output_schema={
"type": "object",
"properties": {
"temperature": {"type": "number"},
"conditions": {"type": "string"},
"humidity": {"type": "number"}
}
}
)
)
```
GitHub： github.com/coinbase/x402
Discord：加入 #x402 频道参与讨论
文档：参见 x402 概览（x402 Overview）
问：如何让我的服务出现在列表中？ 答： 如果你使用了 CDP 撮合方（facilitator），只需在配置中启用 discoverable 标志，你的服务就会自动被收录。
问：如何让端点调用更准确？ 答： 请为每个参数编写清晰的描述，说明其作用及调用方式，但应尽量简洁明了。
问：定价是如何运作的？ 答： 上架是免费的。每个服务可自行设定 每次 API 调用的价格，并通过 x402 支付。
问：目前支持哪些网络？ 答： 目前支持 Base 主网（Base mainnet），支付方式为 USDC。
问：可以上架非 x402 服务吗？ 答： 不可以。只有 兼容 x402 的端点 才能上架。 请参阅我们的 卖家快速入门指南（Seller Quickstart），了解如何让你的 API 支持 x402。
本页将说明 x402 当前支持的 区块链网络与代币（tokens），以及如何扩展以支持更多网络。
ChatGPT said: x402 被设计为可在 多条区块链网络 上运行，具体支持范围取决于所使用的 撮合方（facilitator）。协议本身对网络是 中立的（network-agnostic），但各个撮合方需要针对不同网络实现 支付验证与结算的专用逻辑。
x402 对网络的支持取决于所使用的 撮合方（facilitator）。
以下是当前可用的撮合方及其支持的网络：
支持网络（Supports）：Base Sepolia、Solana Devnet
备注（Notes）：推荐用于测试与开发环境。这是 x402 软件包中的默认撮合方，无需额外设置。
支持网络（Supports）：Base、Base Sepolia、Solana、Solana Devnet
备注（Notes）：适用于主网支付的生产环境，支持 KYT/OFAC 合规检查。
也可用于 Base Sepolia 测试网络。
需要使用 CDP API 密钥（API keys），并通过 facilitator 对象（facilitator object） 而非 URL 进行集成。
前置要求（Requirements）：需拥有 CDP 账户 和来自 cdp.coinbase.com 的 API 密钥。
详情请参考 《卖家快速入门指南：在主网上运行（Quickstart for Sellers: Running on Mainnet）》。
支持网络（Supports）：Solana、Base、Polygon、Avalanche、Sei、Peaq、IoTeX，以及以上网络的所有测试网。
备注（Notes）：适用于主网支付的生产环境。
支持 Solana 上的所有代币，并支持 EVM 链上符合 EIP-3009 标准的代币。
支持网络（Supports）：任意 EVM 网络
备注（Notes）：可自行运行 撮合方（Facilitator），以获得完整的控制权与自定义能力。
支持的网络包括 Avalanche、Polygon、Arbitrum 以及其他所有 EVM 兼容链。
设置（Setup）：请参阅下方章节 《为新网络添加支持（Adding Support for New Networks）》。
可能会有更多由 外部提供商 运营的撮合方可供使用。请加入 x402 Discord 社区，以获取最新的 撮合方（Facilitator） 资讯与可用列表。
x402 同时支持 EVM 网络 与 Solana 网络 上的代币：
EVM 网络：支持所有实现了 EIP-3009 标准 的 ERC-20 代币
Solana 网络：支持所有 SPL 代币 以及 Token-2022 标准代币
重要说明：
撮合方（Facilitator）支持的是 区块链网络，而非特定的代币。
在支持的网络中：
任何符合 EIP-3009 标准的代币都可在 EVM 网络 上使用；
任何 SPL 或 Token-2022 代币都可在 Solana 网络 上使用。
代币必须实现 EIP-3009 标准 中的 transferWithAuthorization 函数。
这使得系统能够：
免燃料费转账（Gasless transfers）：由撮合方代付 Gas 费用。
基于签名的授权（Signature-based authorization）：用户在链下签署转账授权。
安全支付（Secure payments）：转账由加密签名授权，确保交易安全可靠。
在配置支付要求时，你有两种方式可选择：
价格字符串（Price String）（例如："$0.01"）
系统会自动推断使用 USDC 作为代币单位。
TokenAmount 格式
可指定任意符合 EIP-3009 标准 的代币的 精确原子单位（atomic units） 数量。
要在 x402 中使用自定义的 EIP-3009 代币，你需要准备以下三项关键信息：
Token Address（代币地址）：你的 EIP-3009 代币合约地址。
EIP-712 Name（EIP-712 名称）：用于 EIP-712 签名 的代币名称（通常与代币的 name() 一致）。
EIP-712 Version（EIP-712 版本）：用于 EIP-712 签名 的代币版本号（通常为 "1" 或代币合约中定义的版本）。
在BaseScan上查找代币信息
你可以从任何区块浏览器中获取所需的 EIP-712 参数值。
名称（Name）：在 Basescan 上查看 name() 函数的读取结果。
版本（Version）：在 Basescan 上查看 version() 函数的读取结果。
这些数值会在配置 TokenAmount 时，用于 EIP-712 嵌套对象（nested object） 中。
{
eip712: {
name: "USD Coin", // From name() function
version: "2" // From version() function
}
}
在 Solana 上，x402 支持所有 SPL 代币 和 Token 2022 代币。当使用支持 Solana 或 Solana Devnet 的撮合方（facilitator）时，可以使用任意 SPL 或 Token 2022 代币 进行支付，包括 USDC（SPL）。在 Solana 上 不需要进行 EIP-712 配置。
状态（Status）：默认在所有网络中均受支持。
原因（Why）：USDC 实现了 EIP-3009 标准，并且在各网络中广泛可用。
网络（Networks）：可在 Base、Base Sepolia 以及所有受支持的网络上使用。
EIP-3009 标准对 x402 至关重要，因为它实现了以下功能：
Gas 抽象（Gas abstraction）：买家无需持有原生代币（如 ETH、MATIC 等）即可完成支付。
一键式支付（One-step payments）：不需要单独的授权（approval）交易，签名一次即可完成转账。
通用撮合方支持（Universal facilitator support）：任何符合 EIP-3009 标准的代币，都可以与任意撮合方（facilitator）配合使用。
| 撮合方 | 支持的网络 | 生产可用性 | 使用要求 |
| x402.org | base-sepolia, solana-devnet | ❌ 仅测试用 | 无 |
| CDP 撮合方 | base, base-sepolia, solana, solana-devnet | ✅ | CDP API 密钥 |
| x402.rs | base-sepolia, base, xdc | ✅ | 无 |
| PayAI 撮合方 | solana, solana-devnet, base, base-sepolia, polygon, polygon-amoy, avalanche, avalanche-fuji, sei, sei-testnet, peaq, iotex | ✅ | 无 |
| 自托管 | 任意EVM网络 | ✅ | 技术设置 |
在 EVM 网络 上，撮合方支持任何符合 EIP-3009 标准的代币；在 Solana 上，撮合方支持任何 SPL / Token-2022 代币。
在 x402 中为新的 EVM 网络添加支持有两种方式：
你可以通过向 x402 仓库提交 PR（Pull Request） 来添加官方网络支持。 这样，你的网络将对所有 x402 用户开放使用。
需要修改的文件
添加你网络的 Chain ID（链 ID） 和 USDC 地址（合约地址）：
// Example: Adding Avalanche networks
"43113": { // Avalanche Fuji testnet chain ID
usdcAddress: "0x5425890298aed601595a70AB815c96711a31Bc65",
usdcName: "USD Coin",
},
"43114": { // Avalanche mainnet chain ID
usdcAddress: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
usdcName: "USDC",
},
将你的网络添加到 schema（模式） 和 mappings（映射） 中。
// Update the NetworkSchema enum
export const NetworkSchema = z.enum(["base-sepolia", "base", "avalanche-fuji", "avalanche"]);
// Add to SupportedEVMNetworks array
export const SupportedEVMNetworks: Network[] = [
"base-sepolia",
"base",
"avalanche-fuji",
"avalanche",
];
// Add to EvmNetworkToChainId mapping
["avalanche-fuji", 43113],
["avalanche", 43114],
将你的网络添加到 getChainFromNetwork 函数中，以便将网络字符串映射到 viem 的链对象（chain object）。
import { avalanche, avalancheFuji } from "viem/chains";
// Add your network to the switch statement in getChainFromNetwork
case "avalanche":
return avalanche;
case "avalanche-fuji":
return avalancheFuji;
关键要求
Network key（网络键名）：在所有文件中使用一致的网络标识符，例如 avalanche-fuji。
Viem chain（Viem 链定义）：你的网络必须在 viem/chains 中可用，否则需要手动定义。
USDC address（USDC 地址）：必须兼容 EIP-3009，即合约中包含 transferWithAuthorization 函数。
Chain ID（链 ID）：在配置中使用你网络的官方 Chain ID。
Consistency（一致性）：确保网络名称在以下部分保持一致：
NetworkSchema
SupportedEVMNetworks
EvmNetworkToChainId
getChainFromNetwork 的 switch 语句
如果你需要立即获得支持，或想在提交贡献之前进行测试，你可以运行你自己的撮合方（Facilitator）
访问目标网络的 RPC 接口（RPC endpoint）
拥有一个带有原生代币的 钱包（用于 Gas 赞助）
x402 撮合方（facilitator）代码
x402 生态系统正在积极扩展可支持的网络。
计划新增的网络包括：
更多的 二层网络（L2 networks）
更多的 非 EVM 链支持（non-EVM chain support）
跨链支付功能（cross-chain payment capabilities）
如需网络集成方面的帮助：
加入 x402 Discord 社区
查看 x402 GitHub 仓库
x402 的网络支持在设计上兼顾了可扩展性与安全性、可靠性。
无论你是使用默认的 Base Sepolia 测试环境，还是为自定义网络运行你自己的 Facilitator（撮合方），该协议都能为多种应用场景提供灵活的解决方案。
关键要点
Base 与 Base Sepolia 提供了最佳的开箱即用支持。
任何 EVM 网络 都可以通过自定义 Facilitator（撮合方） 来实现支持。
任何带有 transferWithAuthorization 函数的 EIP-3009 代币 都可在任意撮合方上使用。
对于 USDC，请使用 price strings（价格字符串）；对于自定义代币，请使用 TokenAmount。
网络选择 会影响 Gas 成本 与 支付经济性（payment economics）。
模型上下文协议（Model Context Protocol，简称 MCP） 是一种用于在 大型语言模型（LLM） 与其他 AI 代理 之间传递上下文信息的协议。
本指南将介绍如何将 x402 支付协议 与 MCP 结合使用，通过 MCP 服务器发起付费 API 请求，以及如何将其连接到 Claude Desktop。
本指南将带你一步步运行一个 MCP 服务器，该服务器可以使用 x402 协议 访问付费 API。
MCP 服务器在其中充当桥梁，连接 Claude Desktop（或任何兼容 MCP 的客户端） 与 付费 API（例如 x402 仓库中的示例天气 API）。
当 Claude（或其他智能代理）调用某个工具时，MCP 服务器将会：
检测该 API 是否需要付款（通过 HTTP 402 响应）
使用你的钱包自动完成支付
将已付费的数据返回给客户端（例如 Claude）
这使你（或你的智能代理）能够以编程方式访问付费 API，而无需任何手动付款步骤。
Node.js（v20 或更高版本）
可连接的 x402 兼容服务器（本演示使用 x402 仓库中的示例 Express 服务器及天气数据，或任意外部 x402 API）
钱包与 USDC：
以太坊钱包（Base Sepolia 或 Base 主网上的 USDC），或
Solana 钱包（Solana Devnet 或 Solana 主网上的 USDC）
支持 MCP 的 Claude Desktop
你可以在 x402 的代码仓库（repo） 中找到这段代码的现成可用版本。
下面我们将逐步解释每个步骤，帮助你理解它的工作原理，并让你能够根据自己的需求进行调整。
npm install @modelcontextprotocol/sdk axios viem x402-axios dotenv
在项目根目录中创建一个 .env 文件：
PRIVATE_KEY=0xYourTestnetPrivateKey
RESOURCE_SERVER_URL=http://localhost:4021
ENDPOINT_PATH=/weather
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { withPaymentInterceptor } from "x402-axios";
import { config } from "dotenv";
// Load environment variables and throw an error if any are missing
config();
const privateKey = process.env.PRIVATE_KEY as Hex;
const baseURL = process.env.RESOURCE_SERVER_URL as string; // e.g. https://example.com
const endpointPath = process.env.ENDPOINT_PATH as string; // e.g. /weather
if (!privateKey || !baseURL || !endpointPath) {
throw new Error("Missing environment variables");
}
// Create a wallet client to handle payments
const account = privateKeyToAccount(privateKey);
// Create an axios client with payment interceptor using x402-axios
const client = withPaymentInterceptor(axios.create({ baseURL }), account);
// Create an MCP server
const server = new McpServer({
name: "x402 MCP Client Demo",
version: "1.0.0",
});
// Add an addition tool
server.tool(
"get-data-from-resource-server",
"Get data from the resource server (in this example, the weather)", //change this description to change when the client calls the tool
{},
async () => {
const res = await client.get(endpointPath);
return {
content: [{ type: "text", text: JSON.stringify(res.data) }],
};
},
);
const transport = new StdioServerTransport();
await server.connect(transport);
工作原理
MCP 服务器会提供一个工具，当被调用时，它会从付费 API 接口获取数据。
如果该接口需要付款，x402-axios 拦截器会使用你的钱包处理支付交互。
一旦付款完成，数据就会返回给 MCP 客户端（例如 Claude Desktop）。
要在 Claude Desktop 中使用此集成：
打开 Claude Desktop 并进入 MCP 设置。
添加一个新的 MCP 服务器，使用以下配置（根据需要调整路径）： {
确保你的 x402 兼容服务器（例如示例的 Express 服务器）正在运行，并且可以通过你提供的 URL 访问。
启动 MCP 客户端（例如，在客户端目录中运行 pnpm dev）。
现在 Claude 就可以调用该工具并获取付费数据了！
x402 兼容服务器：托管付费 API（例如天气数据）。如果需要付款，会返回 HTTP 402。
MCP 服务器（本实现）：作为桥梁，处理支付并向 MCP 客户端提供工具。
Claude Desktop：调用 MCP 工具，接收付费数据，并展示给用户。