使用 x402 协议构建付费 API 服务器 | 通过 USDC 按请求收费

monetize-service by coinbase/agentic-wallet-skills

1,500 周安装量

86 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/coinbase/agentic-wallet-skills --skill monetize-service

开发区块链

🇨🇳中文介绍

构建 x402 支付服务器

创建一个使用 x402 支付协议、通过 USDC 收取 API 访问费用的 Express 服务器。调用方在 Base 网络上按请求支付 USDC —— 无需账户、API 密钥或订阅。其他代理可以通过 x402 Bazaar 自动发现您的服务。

工作原理

x402 是一种原生 HTTP 支付协议。当客户端访问受保护的端点但未支付时，服务器会返回 HTTP 402 状态码并附带支付要求。客户端签署一笔 USDC 支付，并在重试时附带支付头信息。协调者验证并结算支付，然后服务器返回响应。服务在 x402 Bazaar 注册，以便其他代理能够自动发现并为它们付费。

确认钱包已初始化并授权

npx awal@2.0.3 status

如果钱包未通过身份验证，请参考 authenticate-wallet 技能。

步骤 1：获取支付地址

运行以下命令以获取将接收付款的钱包地址：

npx awal@2.0.3 address

将此地址用作 payTo 的值。

步骤 2：设置项目

mkdir x402-server && cd x402-server
npm init -y
npm install express @x402/express @x402/core @x402/evm @x402/extensions

创建 index.js：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 3：运行服务器

使用 curl 进行测试 —— 您应该会收到一个包含支付要求的 402 响应：

curl -i http://localhost:3000/api/example

paymentMiddleware(routes, server)

创建强制执行 x402 支付的 Express 中间件。

参数	类型	描述
`routes`	object	将路由模式映射到支付配置的路由配置对象
`server`	x402ResourceServer	预配置的 x402 资源服务器实例

使用协调者客户端创建。在传递给中间件之前，注册支付方案和扩展。

const { x402ResourceServer, HTTPFacilitatorClient } = require("@x402/core/server");
const { ExactEvmScheme } = require("@x402/evm/exact/server");

const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org" });
const server = new x402ResourceServer(facilitator);
server.register("eip155:8453", new ExactEvmScheme());

方法	描述
`register(network, scheme)`	为 CAIP-2 网络标识符注册支付方案

路由对象中的每个键是 "METHOD /path" 格式。其值是一个配置对象：

{
  "GET /api/data": {
    accepts: {
      scheme: "exact",
      price: "$0.05",
      network: "eip155:8453",
      payTo: "0x...",
    },
    description: "端点的人类可读描述",
    mimeType: "application/json",
    extensions: {
      ...declareDiscoveryExtension({
        output: {
          example: { result: "example response" },
          schema: {
            properties: {
              result: { type: "string" },
            },
          },
        },
      }),
    },
  },
}

Accepts 配置字段

accepts 字段可以是单个对象或数组（用于多个支付选项）：

字段	类型	描述
`scheme`	string	支付方案：`"exact"`
`price`	string	USDC 价格（例如 `"$0.01"`、`"$1.00"`）
`network`	string	CAIP-2 网络标识符（例如 `"eip155:8453"`）
`payTo`	string	接收 USDC 支付的以太坊地址（0x...）

字段	类型	描述
`accepts`	object or array	支付要求（单个或多个）
`description`	string?	此端点的功能（展示给客户端）
`mimeType`	string?	响应的 MIME 类型
`extensions`	object?	扩展配置（例如 Bazaar 发现）

declareDiscoveryExtension 函数将您的端点注册到 x402 Bazaar，以便其他代理可以发现它：

const { declareDiscoveryExtension } = require("@x402/extensions/bazaar");

extensions: {
  ...declareDiscoveryExtension({
    output: {
      example: { /* 示例响应体 */ },
      schema: {
        properties: {
          /* 响应格式的 JSON 模式 */
        },
      },
    },
  }),
}

字段	类型	描述
`output.example`	object	端点的示例响应体
`output.schema`	object	描述响应格式的 JSON 模式

网络	描述
`eip155:8453`	Base 主网（真实 USDC）
`eip155:84532`	Base Sepolia 测试网（测试 USDC）

具有不同价格的多个端点

app.use(
  paymentMiddleware(
    {
      "GET /api/cheap": {
        accepts: {
          scheme: "exact",
          price: "$0.001",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "廉价数据查询",
      },
      "GET /api/expensive": {
        accepts: {
          scheme: "exact",
          price: "$1.00",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "高级数据访问",
      },
      "POST /api/query": {
        accepts: {
          scheme: "exact",
          price: "$0.25",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "运行自定义查询",
      },
    },
    server,
  ),
);

app.get("/api/cheap", (req, res) => { /* ... */ });
app.get("/api/expensive", (req, res) => { /* ... */ });
app.post("/api/query", (req, res) => { /* ... */ });

app.use(
  paymentMiddleware(
    {
      "GET /api/*": {
        accepts: {
          scheme: "exact",
          price: "$0.05",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "API 访问",
      },
    },
    server,
  ),
);

app.get("/api/users", (req, res) => { /* ... */ });
app.get("/api/posts", (req, res) => { /* ... */ });

健康检查（无需支付）

在支付中间件之前注册免费端点：

app.get("/health", (req, res) => res.json({ status: "ok" }));

// 支付中间件仅适用于在其之后注册的路由
app.use(paymentMiddleware({ /* ... */ }, server));
app.get("/api/data", (req, res) => { /* ... */ });

带有请求体和发现扩展的 POST 端点

app.use(
  paymentMiddleware(
    {
      "POST /api/analyze": {
        accepts: {
          scheme: "exact",
          price: "$0.10",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "分析文本情感",
        mimeType: "application/json",
        extensions: {
          ...declareDiscoveryExtension({
            output: {
              example: { sentiment: "positive", score: 0.95 },
              schema: {
                properties: {
                  sentiment: { type: "string" },
                  score: { type: "number" },
                },
              },
            },
          }),
        },
      },
    },
    server,
  ),
);

app.post("/api/analyze", (req, res) => {
  const { text } = req.body;
  // ... 您的逻辑
  res.json({ sentiment: "positive", score: 0.95 });
});

每个端点支持多种支付选项

为同一端点接受多个网络的支付：

"GET /api/data": {
  accepts: [
    {
      scheme: "exact",
      price: "$0.01",
      network: "eip155:8453",
      payTo: EVM_ADDRESS,
    },
    {
      scheme: "exact",
      price: "$0.01",
      network: "eip155:84532",
      payTo: EVM_ADDRESS,
    },
  ],
  description: "接受 Base 主网或测试网支付的数据端点",
}

使用 CDP 协调者（已验证）

用于生产环境，配合 Coinbase 协调者（支持主网）：

npm install @coinbase/x402



const { facilitator } = require("@coinbase/x402");
const { HTTPFacilitatorClient } = require("@x402/core/server");

const facilitatorClient = new HTTPFacilitatorClient(facilitator);
const server = new x402ResourceServer(facilitatorClient);
server.register("eip155:8453", new ExactEvmScheme());

这需要设置 CDP_API_KEY_ID 和 CDP_API_KEY_SECRET 环境变量。请从 https://portal.cdp.coinbase.com 获取。

使用 pay-for-service 技能进行测试

服务器运行后，使用 pay-for-service 技能测试支付：

# 检查端点的支付要求
npx awal@2.0.3 x402 details http://localhost:3000/api/example

# 发起付费请求
npx awal@2.0.3 x402 pay http://localhost:3000/api/example

使用场景	建议价格
简单数据查询	$0.001 - $0.01
API 代理 / 数据增强	$0.01 - $0.10
计算密集型查询	$0.10 - $0.50
AI 推理	$0.05 - $1.00

使用 npx awal@2.0.3 address 获取钱包地址
安装 express、@x402/express、@x402/core、@x402/evm 和 @x402/extensions
使用协调者客户端创建 x402ResourceServer，并为 eip155:8453 注册 ExactEvmScheme
定义包含价格、描述和发现扩展的路由（当路由声明时，Bazaar 会自动注册）
在受保护路由之前注册支付中间件
将健康/状态端点放在支付中间件之前
使用 curl 测试（应收到 402）和 npx awal@2.0.3 x402 pay 测试（应收到 200）
宣布您的服务，以便其他代理可以找到并使用它

🇺🇸English

Build an x402 Payment Server

Create an Express server that charges USDC for API access using the x402 payment protocol. Callers pay per-request in USDC on Base — no accounts, API keys, or subscriptions needed. Your service is automatically discoverable by other agents via the x402 Bazaar.

How It Works

x402 is an HTTP-native payment protocol. When a client hits a protected endpoint without paying, the server returns HTTP 402 with payment requirements. The client signs a USDC payment and retries with a payment header. The facilitator verifies and settles the payment, and the server returns the response. Services register with the x402 Bazaar so other agents can discover and pay for them automatically.

Confirm wallet is initialized and authed

npx awal@2.0.3 status

If the wallet is not authenticated, refer to the authenticate-wallet skill.

Step 1: Get the Payment Address

Run this to get the wallet address that will receive payments:

npx awal@2.0.3 address

Use this address as the payTo value.

Step 2: Set Up the Project

mkdir x402-server && cd x402-server
npm init -y
npm install express @x402/express @x402/core @x402/evm @x402/extensions

Create index.js:

const express = require("express");
const { paymentMiddleware } = require("@x402/express");
const { x402ResourceServer, HTTPFacilitatorClient } = require("@x402/core/server");
const { ExactEvmScheme } = require("@x402/evm/exact/server");

const app = express();
app.use(express.json());

const PAY_TO = "<address from step 1>";

// Create facilitator client and x402 resource server
const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
const server = new x402ResourceServer(facilitator);
server.register("eip155:8453", new ExactEvmScheme());

// x402 payment middleware — protects routes below
app.use(
  paymentMiddleware(
    {
      "GET /api/example": {
        accepts: {
          scheme: "exact",
          price: "$0.01",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "Description of what this endpoint returns",
        mimeType: "application/json",
      },
    },
    server,
  ),
);

// Protected endpoint
app.get("/api/example", (req, res) => {
  res.json({ data: "This costs $0.01 per request" });
});

app.listen(3000, () => console.log("Server running on port 3000"));

Step 3: Run It

node index.js

Test with curl — you should get a 402 response with payment requirements:

curl -i http://localhost:3000/api/example

API Reference

paymentMiddleware(routes, server)

Creates Express middleware that enforces x402 payments.

Parameter	Type	Description
`routes`	object	Route config mapping route patterns to payment config
`server`	x402ResourceServer	Pre-configured x402 resource server instance

x402ResourceServer

Created with a facilitator client. Register payment schemes and extensions before passing to middleware.

const { x402ResourceServer, HTTPFacilitatorClient } = require("@x402/core/server");
const { ExactEvmScheme } = require("@x402/evm/exact/server");

const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org" });
const server = new x402ResourceServer(facilitator);
server.register("eip155:8453", new ExactEvmScheme());

Method	Description
`register(network, scheme)`	Register a payment scheme for a CAIP-2 network identifier

Route Config

Each key in the routes object is "METHOD /path". The value is a config object:

{
  "GET /api/data": {
    accepts: {
      scheme: "exact",
      price: "$0.05",
      network: "eip155:8453",
      payTo: "0x...",
    },
    description: "Human-readable description of the endpoint",
    mimeType: "application/json",
    extensions: {
      ...declareDiscoveryExtension({
        output: {
          example: { result: "example response" },
          schema: {
            properties: {
              result: { type: "string" },
            },
          },
        },
      }),
    },
  },
}

Accepts Config Fields

The accepts field can be a single object or an array (for multiple payment options):

Field	Type	Description
`scheme`	string	Payment scheme: `"exact"`
`price`	string	USDC price (e.g. `"$0.01"`, `"$1.00"`)
`network`	string	CAIP-2 network identifier (e.g. `"eip155:8453"`)

Route-Level Fields

Field	Type	Description
`accepts`	object or array	Payment requirements (single or multiple)
`description`	string?	What this endpoint does (shown to clients)
`mimeType`	string?	MIME type of the response
`extensions`	object?	Extensions config (e.g. Bazaar discovery)

Discovery Extension

The declareDiscoveryExtension function registers your endpoint with the x402 Bazaar so other agents can discover it:

const { declareDiscoveryExtension } = require("@x402/extensions/bazaar");

extensions: {
  ...declareDiscoveryExtension({
    output: {
      example: { /* example response body */ },
      schema: {
        properties: {
          /* JSON schema of the response */
        },
      },
    },
  }),
}

Field	Type	Description
`output.example`	object	Example response body for the endpoint
`output.schema`	object	JSON schema describing the response format

Supported Networks

Network	Description
`eip155:8453`	Base mainnet (real USDC)
`eip155:84532`	Base Sepolia testnet (test USDC)

Patterns

Multiple endpoints with different prices

app.use(
  paymentMiddleware(
    {
      "GET /api/cheap": {
        accepts: {
          scheme: "exact",
          price: "$0.001",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "Inexpensive data lookup",
      },
      "GET /api/expensive": {
        accepts: {
          scheme: "exact",
          price: "$1.00",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "Premium data access",
      },
      "POST /api/query": {
        accepts: {
          scheme: "exact",
          price: "$0.25",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "Run a custom query",
      },
    },
    server,
  ),
);

app.get("/api/cheap", (req, res) => { /* ... */ });
app.get("/api/expensive", (req, res) => { /* ... */ });
app.post("/api/query", (req, res) => { /* ... */ });

Wildcard routes

app.use(
  paymentMiddleware(
    {
      "GET /api/*": {
        accepts: {
          scheme: "exact",
          price: "$0.05",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "API access",
      },
    },
    server,
  ),
);

app.get("/api/users", (req, res) => { /* ... */ });
app.get("/api/posts", (req, res) => { /* ... */ });

Health check (no payment)

app.get("/health", (req, res) => res.json({ status: "ok" }));

// Payment middleware only applies to routes registered after it
app.use(paymentMiddleware({ /* ... */ }, server));
app.get("/api/data", (req, res) => { /* ... */ });

POST with body and discovery extension

app.use(
  paymentMiddleware(
    {
      "POST /api/analyze": {
        accepts: {
          scheme: "exact",
          price: "$0.10",
          network: "eip155:8453",
          payTo: PAY_TO,
        },
        description: "Analyze text sentiment",
        mimeType: "application/json",
        extensions: {
          ...declareDiscoveryExtension({
            output: {
              example: { sentiment: "positive", score: 0.95 },
              schema: {
                properties: {
                  sentiment: { type: "string" },
                  score: { type: "number" },
                },
              },
            },
          }),
        },
      },
    },
    server,
  ),
);

app.post("/api/analyze", (req, res) => {
  const { text } = req.body;
  // ... your logic
  res.json({ sentiment: "positive", score: 0.95 });
});

Multiple payment options per endpoint

Accept payments on multiple networks for the same endpoint:

"GET /api/data": {
  accepts: [
    {
      scheme: "exact",
      price: "$0.01",
      network: "eip155:8453",
      payTo: EVM_ADDRESS,
    },
    {
      scheme: "exact",
      price: "$0.01",
      network: "eip155:84532",
      payTo: EVM_ADDRESS,
    },
  ],
  description: "Data endpoint accepting Base mainnet or testnet",
}

Using the CDP facilitator (authenticated)

For production use with the Coinbase facilitator (supports mainnet):

npm install @coinbase/x402



const { facilitator } = require("@coinbase/x402");
const { HTTPFacilitatorClient } = require("@x402/core/server");

const facilitatorClient = new HTTPFacilitatorClient(facilitator);
const server = new x402ResourceServer(facilitatorClient);
server.register("eip155:8453", new ExactEvmScheme());

This requires CDP_API_KEY_ID and CDP_API_KEY_SECRET environment variables. Get these from https://portal.cdp.coinbase.com.

Testing with the pay-for-service Skill

Once the server is running, use the pay-for-service skill to test payments:

# Check the endpoint's payment requirements
npx awal@2.0.3 x402 details http://localhost:3000/api/example

# Make a paid request
npx awal@2.0.3 x402 pay http://localhost:3000/api/example

Pricing Guidelines

Use Case	Suggested Price
Simple data lookup	$0.001 - $0.01
API proxy / enrichment	$0.01 - $0.10
Compute-heavy query	$0.10 - $0.50
AI inference	$0.05 - $1.00

Checklist

Get wallet address with npx awal@2.0.3 address
Install express, @x402/express, @x402/core, @x402/evm, and @x402/extensions
Create x402ResourceServer with facilitator client and register ExactEvmScheme for eip155:8453
Define routes with prices, descriptions, and discovery extensions (Bazaar auto-registers when routes declare it)
Register payment middleware before protected routes
Keep health/status endpoints before payment middleware
Test with curl (should get 402) and (should get 200)

Weekly Installs

1.5K

Repository

coinbase/agenti…t-skills

GitHub Stars

First Seen

Feb 10, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex1.3K

opencode1.3K

gemini-cli1.3K

github-copilot1.3K

kimi-cli1.2K

amp1.2K

npx awal@2.0.3 x402 pay

Announce your service so other agents can find and use it

使用 x402 协议构建付费 API 服务器 | 通过 USDC 按请求收费

🇨🇳中文介绍

构建 x402 支付服务器

工作原理

确认钱包已初始化并授权

步骤 1：获取支付地址

步骤 2：设置项目

相关 Skills

步骤 3：运行服务器

API 参考

paymentMiddleware(routes, server)

x402ResourceServer

路由配置

Accepts 配置字段

路由级字段

发现扩展

支持的网络

模式

具有不同价格的多个端点

通配符路由

健康检查（无需支付）

带有请求体和发现扩展的 POST 端点

每个端点支持多种支付选项

使用 CDP 协调者（已验证）

使用 pay-for-service 技能进行测试

定价指南

检查清单

🇺🇸English

Build an x402 Payment Server

How It Works

Confirm wallet is initialized and authed

Step 1: Get the Payment Address

Step 2: Set Up the Project

Step 3: Run It

API Reference

paymentMiddleware(routes, server)

x402ResourceServer

Route Config

Accepts Config Fields

Route-Level Fields

Discovery Extension

Supported Networks

Patterns

Multiple endpoints with different prices

Wildcard routes

Health check (no payment)

POST with body and discovery extension

Multiple payment options per endpoint

Using the CDP facilitator (authenticated)

Testing with the pay-for-service Skill

Pricing Guidelines

Checklist