セラー向けクイックスタート

APIまたはサービスにx402決済を統合し、バイヤーやAIエージェントからの支払いを受け付けられるようにします。

このガイドはテストネット設定から始めます。本番環境への移行については、後述の「メインネットへの移行」をご参照ください。

フレームワークを選択：

前提条件

資金を受け取るためのクリプトウォレット（EVM・SVM互換）
Node.js と npm がインストールされていること
既存のAPIまたはサーバー

x402リポジトリには各フレームワーク向けの設定済みサンプルが用意されています。GitHubで確認する

1. 依存関係のインストール

npm install @x402/express @x402/core @x402/evm @x402/svm

2. 支払いミドルウェアの追加

以下の情報を用意してミドルウェアを設定します：

ファシリテーターURL（テスト用は https://x402.org/facilitator）
保護するルート
受け取りウォレットアドレス

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const app = express();

const evmAddress = "0xYourEvmAddress";
const svmAddress = "YourSolanaAddress";

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://x402.org/facilitator"
});

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.001",
            network: "eip155:84532", // Base Sepolia
            payTo: evmAddress,
          },
          {
            scheme: "exact",
            price: "$0.001",
            network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", // Solana Devnet
            payTo: svmAddress,
          },
        ],
        description: "Weather data",
        mimeType: "application/json",
      },
    },
    new x402ResourceServer(facilitatorClient)
      .register("eip155:84532", new ExactEvmScheme())
      .register("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", new ExactSvmScheme()),
  ),
);

app.get("/weather", (req, res) => {
  res.send({ report: { weather: "sunny", temperature: 70 } });
});

app.listen(4021, () => {
  console.log(`Server listening at http://localhost:4021`);
});

ルート設定インターフェース

interface RouteConfig {
  accepts: Array<{
    scheme: string;   // "exact" または "upto"
    price: string;    // exact: 固定価格 / upto: 最大認可額
    network: string;  // CAIP-2形式 (例: "eip155:84532")
    payTo: string;    // 受け取りウォレットアドレス
  }>;
  description?: string;  // リソースの説明
  mimeType?: string;     // レスポンスのMIMEタイプ
  extensions?: object;   // オプション拡張 (例: Bazaar)
}

支払いスキーム：exact と upto

exact（デフォルト）

クライアントは表示された正確な金額を支払います。全ネットワーク・全SDK対応。固定価格のエンドポイントに最適。

upto

クライアントは最大額を承認し、サーバーは実際の使用量のみ決済します。従量課金（LLMトークン数、計算時間など）に対応。現在EVM（TypeScript・Go）のみ対応。

3. 統合のテスト

1エンドポイントにリクエストを送信（例：curl http://localhost:4021/weather）
2サーバーが402 Payment Requiredを返し、PAYMENT-REQUIREDヘッダーに支払い指示が含まれていることを確認
3バイヤー向けSDKを使って支払いを完了する
4今度はPAYMENT-SIGNATUREヘッダーを含めてリクエストをリトライ
5サーバーが支払いを検証し、実際のAPIレスポンスを返すことを確認

4. Bazaarによるサービス検索の有効化（推奨）

Bazaarエクステンションに対応したファシリテーターを使用すると、バイヤーやAIエージェントがあなたのサービスを発見できるようになります。

{
  "GET /weather": {
    accepts: [
      { scheme: "exact", price: "$0.001", network: "eip155:8453", payTo: "0xYourAddress" },
      { scheme: "exact", price: "$0.001", network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", payTo: "YourSolanaAddress" },
    ],
    description: "リアルタイムの気象データ（気温・天候・湿度）",
    mimeType: "application/json",
    extensions: {
      bazaar: {
        discoverable: true,
        category: "weather",
        tags: ["forecast", "real-time"],
      },
    },
  },
}

5. エラーハンドリング

問題が発生した場合は、リポジトリ内のサンプルを参照してください。より詳しいコンテキストと完全なコード例が用意されています。依存関係のインストールには npm install（Node.js）または go mod tidy（Go）を実行してください。

メインネットへの移行

注意

メインネットのトランザクションには実際の資金が関わります。必ずテストネットで十分にテストを行い、メインネットでは少額から始めてください。

1. ファシリテーターURLを更新

本番環境では本番ファシリテーターを使用します。利用可能なオプションはx402エコシステムで確認できます。

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://api.cdp.coinbase.com/platform/v2/x402"
});

2. ネットワーク識別子を更新

// Base Mainnet
network: "eip155:8453"   // (テストネット: eip155:84532)

// Solana Mainnet
network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"   // (テストネット: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1)

3. EVMとSolanaの両方を登録

EVM・SolanaのどちらもサポートするためにEVMスキームとSVMスキームの両方をメインネット識別子で登録します：

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://api.cdp.coinbase.com/platform/x402/v1"
});

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.001",
            network: "eip155:8453", // Base Mainnet
            payTo: "0xYourEvmAddress",
          },
          {
            scheme: "exact",
            price: "$0.001",
            network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", // Solana Mainnet
            payTo: "YourSolanaAddress",
          },
        ],
      },
    },
    new x402ResourceServer(facilitatorClient)
      .register("eip155:8453", new ExactEvmScheme())
      .register("solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", new ExactSvmScheme()),
  ),
);

4. ウォレットアドレスを更新

メインネット用のウォレットアドレスを設定します。USDC決済を受け取るためのEVM対応ウォレット（例：MetaMask・Coinbase Wallet）が必要です。

5. 実際の支払いでテスト

少額のトランザクションから始め、ファシリテーターのレスポンスを監視しながら動作を確認してください。問題が発生した場合は、テストネットに戻って原因を特定してから再度メインネットに移行します。

ネットワーク識別子（CAIP-2）

ネットワーク	CAIP-2識別子
Base Mainnet	eip155:8453
Base Sepolia	eip155:84532
Solana Mainnet	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
Solana Devnet	solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1

次のステップ

まとめ

このクイックスタートでは以下を学びました：

x402 SDKのインストールと設定
支払いミドルウェアの追加とルート保護
支払いスキーム（exact・upto）の選択
統合のテスト方法
標準化されたネットワーク識別子（CAIP-2）を使ったメインネットへのデプロイ

← バイヤー向けクイックスタート HTTP 402 →