Metaplex x402の支払いモード

Metaplex x402は3つの支払いモード — 標準Solanaウォレット、Coreアセットまたはエージェントによる直接支払い、リクエストごとの署名なしで支払う委任エージェント — をサポートします。どのモードでも生成されるものは同じで、すでに使っているHTTPクライアントに渡せる支払い対応のfetchです。

概要

支払いモードを選ぶということは、どのアカウントのUSDCでリクエストを支払い、その所有者がどの頻度で署名するかを決めることです。最初の2つのモードは登録する支払いスキームが違うだけですが、委任されたエージェントではさらに認証トークンストアと、クライアント拡張またはfetchラッパーのいずれかが必要です。fetchWithPaymentさえ用意できれば、その後のリクエストコードは3つのモードすべてで同一です。

• 標準ウォレット — ExactSvmSchemeを使う素のx402。所有者が支払いごとに署名し、SOLは不要です
• Coreアセットまたはエージェント（直接） — coreExecuteターゲットを指定したMetaplexSvmExactScheme。資金はアセットのシグナーPDAから出ますが、所有者は引き続き支払いごとに署名します
• 委任エージェント（即時） — 1回限りのオンチェーン許可により、Mechがエージェントのウォレットから支払いを承認できるようになります。クライアントはメッセージ署名で認証します
• いつでも取り消し可能 — 委任はオンチェーンの許可なので、取り消しはポリシーではなくオンチェーンで支払いを停止します

前提条件

Metaplex x402には、資金を入れたSolanaアカウントと、支払いトランザクションを構築できる署名者が必要です。

• Node.js 20.18+ とESMプロジェクト
• Solanaの署名者 — Solana Kitのキーペア署名者またはUmiの署名者
• 支払い元アカウントのクラシックなSPL Token関連トークンアカウントにあるUSDC
• Coreアセットおよびエージェントのモードでは、その署名者が所有するCoreアセットと、そのシグナーPDA内のSOL
• 委任エージェントのモードでは、登録済みのエージェントアイデンティティ — 新しいエージェントをミントするか、既存のCoreアセットを登録します

クイックスタート

クライアントをインストールし、支払い元アカウントに入金してから、選択したモードのスキームを登録します。

pnpm add @metaplex-foundation/x402 \
  @metaplex-foundation/umi \
  @solana/kit \
  @x402/core \
  @x402/fetch \
  @x402/svm

続いて、使用するクライアントを追加します。

各モードへ移動: 標準ウォレット · Coreアセットまたはエージェント · 委任エージェント。

支払いモード別の資金要件

各モードは異なるアカウントからUSDCを引き出し、SOLが必要なのはCore executeを使うモードだけです。

支払い元は常にクラシックなSPL Tokenの関連トークンアカウントです。Token-2022の支払いミントは現在サポートされていません。

標準Solanaウォレットで支払う

自分が直接管理するウォレットから支払うには、@x402/svmのExactSvmSchemeを登録します。これは素のx402であり、Metaplexのクライアントが加えているのはエンドポイント定数とディスカバリーヘルパーだけです。

import { createKeyPairSignerFromBytes, getBase58Encoder } from '@solana/kit';
import { x402Client } from '@x402/core/client';
import { wrapFetchWithPayment } from '@x402/fetch';
import { ExactSvmScheme } from '@x402/svm/exact/client';

const svmSigner = await createKeyPairSignerFromBytes(
  getBase58Encoder().encode(process.env.SVM_PRIVATE_KEY!),
);

const paymentClient = new x402Client();
paymentClient.register('solana:*', new ExactSvmScheme(svmSigner));

const fetchWithPayment = wrapFetchWithPayment(fetch, paymentClient);

Coreアセットまたはエージェントで直接支払う

所有者が引き続き支払いごとに署名しつつ、Coreアセット自身のウォレットから資金を出すには、coreExecuteターゲットを指定したMetaplexSvmExactSchemeを登録します。すべてのCoreアセットは組み込みのウォレット — Asset Signer PDA — を持っているため、そのウォレットに入金すればメインウォレットと支出を分離でき、所有権が移転すれば予算もアセットとともに移動します。

import { MetaplexSvmExactScheme } from '@metaplex-foundation/x402';
import { x402Client } from '@x402/core/client';
import { wrapFetchWithPayment } from '@x402/fetch';

const paymentClient = new x402Client();
paymentClient.register(
  'solana:*',
  new MetaplexSvmExactScheme(svmSigner, {
    rpcUrl: svmRpcUrl,
    coreExecute: {
      asset: coreAssetAddress,
    },
  }),
);

const fetchWithPayment = wrapFetchWithPayment(fetch, paymentClient);

svmSignerはアセットを管理する署名者、svmRpcUrlは支払いトランザクションの構築に使うSolana RPCエンドポイント、coreAssetAddressはCoreアセットまたはエージェントのアドレスです。

委任エージェントで即時に支払う

エージェントをMechに1回委任しておけば、サーバーはリクエストごとの所有者署名なしにエージェントのウォレットから支払いを承認できます。自律エージェントや高頻度のワークロードに適したモードです。

エージェントは、承認する署名者が所有する登録済みのエージェントアイデンティティである必要があります。委任後、クライアントはSign-In-With-Xのメッセージ署名で認証して24時間有効なベアラートークンを受け取り、サーバーがエージェントのウォレットから支払いを構築します。この委任はいつでも取り消せるオンチェーンの許可です。

委任を1回だけ承認する

繰り返し実行してもトランザクションを再送しないよう、承認前に現在のステータスを確認します。

import {
  approveMetaplexCoreExecuteDelegate,
  fetchMetaplexCoreExecuteDelegateStatus,
} from '@metaplex-foundation/x402';

const status = await fetchMetaplexCoreExecuteDelegateStatus(coreAssetAddress);

if (!status.isDelegated) {
  await approveMetaplexCoreExecuteDelegate(svmSigner, coreAssetAddress, {
    rpcUrl: svmRpcUrl,
  });
}

リアクティブとプロアクティブの統合スタイルを選ぶ

リアクティブとプロアクティブの統合は代替関係にあります — どちらか一方だけを使い、併用しないでください。

以下のどちらのスニペットでも、solanaSignerは認証に使うメッセージ署名可能なSolana署名者です。Solana Kitのキーペア署名者が使えます。

import {
  createMetaplexCoreExecuteDelegateClientExtension,
  InMemoryMetaplexCoreExecuteDelegateAuthTokenStore,
  MetaplexSvmExactScheme,
} from '@metaplex-foundation/x402';
import { x402Client } from '@x402/core/client';
import { wrapFetchWithPayment } from '@x402/fetch';

const authTokenStore = new InMemoryMetaplexCoreExecuteDelegateAuthTokenStore();
const paymentClient = new x402Client();

paymentClient.register(
  'solana:*',
  new MetaplexSvmExactScheme(svmSigner, { rpcUrl: svmRpcUrl }),
);
paymentClient.registerExtension(
  createMetaplexCoreExecuteDelegateClientExtension({
    signer: solanaSigner,
    asset: coreAssetAddress,
    authTokenStore,
  }),
);

const fetchWithPayment = wrapFetchWithPayment(fetch, paymentClient);

import {
  InMemoryMetaplexCoreExecuteDelegateAuthTokenStore,
  wrapFetchWithMetaplexCoreExecuteDelegate,
} from '@metaplex-foundation/x402';

const authTokenStore = new InMemoryMetaplexCoreExecuteDelegateAuthTokenStore();

const fetchWithPayment = wrapFetchWithMetaplexCoreExecuteDelegate(fetch, {
  signer: solanaSigner,
  asset: coreAssetAddress,
  authTokenStore,
});

プロアクティブなスタイルでも委任の承認は必要で、他のオリジンへのリクエストはそのまま素通りします。

認証トークンの保存と失効の扱い

認可JWTは24時間で失効し、クライアントはオンチェーンの再承認ではなくメッセージ署名によって自動的に置き換えます。

• Node.jsではInMemoryMetaplexCoreExecuteDelegateAuthTokenStoreを、ブラウザ専用のコードではLocalStorageMetaplexCoreExecuteDelegateAuthTokenStoreを使ってください
• それ以外のストレージバックエンドを使う場合はMetaplexCoreExecuteDelegateAuthTokenStoreインターフェースを実装します
• リアクティブな直接支払いフォールバックは既定で無効です。登録済みの支払いスキームに委任失敗を処理させたい場合にのみfallback: trueを設定してください
• 認証、キャッシュ、フォールバックの挙動を観察するにはonEventを渡します

委任を取り消す

承認時と同じ署名者、アセット、RPCオプションでrevokeMetaplexCoreExecuteDelegateを呼び出します。

import { revokeMetaplexCoreExecuteDelegate } from '@metaplex-foundation/x402';

await revokeMetaplexCoreExecuteDelegate(svmSigner, coreAssetAddress, {
  rpcUrl: svmRpcUrl,
});

この許可はオンチェーンに存在するため、取り消すとサーバーはエージェントのウォレットから支払いを構築できなくなります — サービス側が善意で従うポリシーではありません。

よくあるエラー

支払いの構築に失敗する原因は、ほぼ必ず資金、ネットワークの不一致、委任の状態のいずれかに行き着きます。

検証済みの構成

注意事項

• MetaplexSvmExactSchemeはUmiの署名者とSolana Kitのパーシャルトランザクション署名者を受け付けますが、sign-and-send署名者は受け付けません。Kitの署名者は内部で変換されます。
• サービス・クライアント・支払いモードのすべての組み合わせについて、実行可能なサンプルがx402リポジトリにあり、pnpm example:<name>で実行できます。
• 委任エージェントのサンプルは、初回実行時に承認トランザクションを送信する場合があります。
• 委任は、リクエストの支払いのためにエージェントのウォレットからUSDCを動かす権限をMechに与えます。シグナーPDAには運用に必要な残高だけを置き、エージェントを使わないときは取り消してください。

クイックリファレンス

FAQ

Metaplex x402の支払いモードに関するよくある質問。

Metaplex x402ではどの支払いモードを使うべきですか？

アプリが自分自身として支払う場合は標準ウォレット、所有者の監督下でアセットに独自の予算を持たせたい場合はCoreアセットまたはエージェントの直接支払い、自律エージェントが人間の署名なしにリクエストごとに支払う必要がある場合は委任エージェントを使います。

Metaplex x402のリクエストを支払うのにSOLは必要ですか？

必要なのはCoreアセットおよびエージェントの支払いモードだけで、その場合はCore executeのトランザクション手数料をまかなうためにアセットシグナーPDAにSOLが必要です。標準ウォレットの支払いにSOLは不要で、支払いトランザクションのネットワーク手数料はサービス側のフィーペイヤーが負担します。

委任エージェントの認証トークンの有効期間はどれくらいですか？

認可JWTは24時間で失効します。失効したトークンは破棄され自動的に置き換えられます。置き換えに必要なのはメッセージ署名だけで、オンチェーンの委任承認を再度行う必要はありません。

リアクティブ拡張とプロアクティブなfetchラッパーは併用できますか？

いいえ。両者は代替関係にあり、組み合わせるとフローが壊れます。すでにx402Clientを運用している場合や直接支払いへのフォールバックを任意で使いたい場合はリアクティブなクライアント拡張を、Metaplexのエンドポイントのみを対象に最もシンプルに配線したい場合はプロアクティブなfetchラッパーを使ってください。

委任エージェントによる支払いを止めるにはどうすればいいですか？

承認時と同じ署名者、アセット、RPCオプションでrevokeMetaplexCoreExecuteDelegateを呼び出します。委任はオンチェーンの許可なので、取り消しはオンチェーンで有効になり、サーバーはエージェントのウォレットから支払いを構築できなくなります。

Token-2022のUSDCや他のステーブルコインで支払えますか？

いいえ。支払い元は常にクラシックなSPL Tokenの関連トークンアカウントであり、Token-2022の支払いミントは現在サポートされていません。

Metaplex Foundationが管理。最終確認日: 2026-09-08。クライアントバージョン: @metaplex-foundation/x402 0.1.0。GitHubでソースを見る。