x402 ペイメントサーバーの構築

x402 ペイメントプロトコルを使用して、USDC での API アクセスに課金する Express サーバーを作成します。呼び出し元は Base 上の USDC をリクエストごとに支払います — アカウント、API キー、またはサブスクリプションは不要です。あなたのサービスは x402 Bazaar を通じて他のエージェントから自動的に検出可能になります。

仕組み

x402 は HTTP ネイティブのペイメントプロトコルです。クライアントが支払いなしで保護されたエンドポイントにアクセスすると、サーバーは HTTP 402 と支払い要件を返します。クライアントは USDC の支払いに署名し、支払いヘッダーを付けて再試行します。ファシリテータが支払いを確認して決済し、サーバーがレスポンスを返します。サービスは x402 Bazaar に登録され、他のエージェントが自動的に検出して支払うことができます。

ウォレットが初期化され、認証されていることを確認する

npx awal@2.10.0 status

ウォレットが認証されていない場合は、authenticate-wallet スキルを参照してください。

ステップ 1: ペイメントアドレスを取得する

これを実行して、支払いを受け取るウォレットアドレスを取得します:

npx awal@2.10.0 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 を作成します:

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"));

ステップ 3: 実行する

node index.js

curl でテストします — HTTP 402 レスポンスと支払い要件を取得する必要があります:

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

API リファレンス

paymentMiddleware(routes, server)

x402 支払いを実施する Express ミドルウェアを作成します。

パラメータ	型	説明
routes	object	ルートパターンを支払い設定にマッピングするルート設定
server	x402ResourceServer	事前設定済みの x402 リソースサーバーインスタンス

x402ResourceServer

ファシリテータクライアントで作成されます。ミドルウェアに渡す前に、支払いスキームと拡張機能を登録します。

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 ネットワーク識別子の支払いスキームを登録する

ルート設定

routes オブジェクトの各キーは "METHOD /path" です。値は設定オブジェクトです:

{
  "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 設定フィールド

accepts フィールドは単一のオブジェクトまたは配列 (複数の支払いオプションの場合) にできます:

フィールド	型	説明
scheme	string	支払いスキーム: "exact"
price	string	USDC 価格 (例: "$0.01", "$1.00")
network	string	CAIP-2 ネットワーク識別子 (例: "eip155:8453")
payTo	string	USDC 支払いを受け取る Ethereum アドレス (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: { /* example response body */ },
      schema: {
        properties: {
          /* JSON schema of the response */
        },
      },
    },
  }),
}

フィールド	型	説明
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: "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) => { /* ... */ });

ワイルドカードルート

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) => { /* ... */ });

ヘルスチェック (支払いなし)

支払いミドルウェアの前に無料エンドポイントを登録します:

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 とボディおよびディスカバリー拡張機能

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 });
});

エンドポイントごとの複数の支払いオプション

同じエンドポイントで複数のネットワークでの支払いを受け入れます:

"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",
}

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 スキルを使用して支払いをテストします:

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

# Make a paid request
npx awal@2.10.0 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.10.0 address でウォレットアドレスを取得する
• express, @x402/express, @x402/core, @x402/evm, @x402/extensions をインストールする
• ファシリテータクライアントで x402ResourceServer を作成し、eip155:8453 の ExactEvmScheme を登録する
• 価格、説明、ディスカバリー拡張機能を含むルートを定義する (ルートが宣言されると Bazaar が自動登録される)
• 保護されたルートの前に支払いミドルウェアを登録する
• ヘルス/ステータスエンドポイントを支払いミドルウェアの前に保つ
• curl (HTTP 402 を取得する必要があります) と npx awal@2.10.0 x402 pay (HTTP 200 を取得する必要があります) でテストする
• 他のエージェントがサービスを検出して使用できるようにアナウンスする