Metaplex x402 支付模式

Metaplex x402 支持三种支付模式 — 标准 Solana 钱包、Core 资产或 Agent 直接支付，以及无需逐次签名即可支付的委托 Agent。每种模式产出的东西都相同：一个支持支付的 fetch，交给您已经在用的任意 HTTP 客户端即可。

摘要

选择支付模式，就是决定由哪个账户的 USDC 支付请求，以及其所有者签名的频率。前两种模式的差异只在于注册哪个支付方案；委托 Agent 还需要一个认证令牌存储，以及客户端扩展或 fetch 包装器之一。一旦拿到 fetchWithPayment，之后的请求代码在三种模式下完全一致。

• 标准钱包 — 使用 ExactSvmScheme 的原生 x402；所有者对每次支付签名，且无需 SOL
• Core 资产或 Agent（直接） — 带 coreExecute 目标的 MetaplexSvmExactScheme；资金来自资产的签名者 PDA，但所有者仍需对每次支付签名
• 委托 Agent（即时） — 一次性链上授权让 Mech 可以从 Agent 的钱包批准支付；客户端改用消息签名进行认证
• 可随时撤销 — 委托是一项链上授权，撤销它会在链上停止支付，而不是依赖某种策略

前置条件

Metaplex x402 需要一个有资金的 Solana 账户，以及一个能够构建支付交易的签名者。

• Node.js 20.18+ 与 ESM 项目
• 一个 Solana 签名者 — Solana Kit 密钥对签名者或 Umi 签名者
• 支付账户的经典 SPL Token 关联代币账户中持有 USDC
• 对于 Core 资产和 Agent 模式，需要一个由该签名者拥有的 Core 资产，以及其签名者 PDA 中的 SOL
• 对于委托 Agent 模式，需要一个已注册的 Agent 身份 — 铸造新 Agent 或注册现有的 Core 资产

快速开始

安装客户端，为支付账户充值，然后注册所选模式的方案。

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

然后添加您计划使用的客户端：

跳转到对应模式：标准钱包 · Core 资产或 Agent · 委托 Agent。

各支付模式的资金要求

每种模式从不同账户扣取 USDC，只有使用 Core execute 的模式才需要 SOL。

支付来源始终是经典 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 资产或 Agent 直接支付

若希望在所有者仍对每次支付签名的前提下，由 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 资产或 Agent 的地址。

使用委托 Agent 即时支付

将 Agent 一次性委托给 Mech，服务端便可在无需逐次获得所有者签名的情况下，从 Agent 的钱包批准支付。这是适用于自主 Agent 和高频负载的模式。

该 Agent 必须是由批准签名者所拥有的已注册 Agent 身份。委托之后，客户端通过 Sign-In-With-X 消息签名进行认证并获得 24 小时有效的 bearer 令牌，服务端则从 Agent 的钱包构建支付。您始终保有控制权：该委托是一项可随时撤销的链上授权。

一次性批准委托

在批准前先检查当前状态，避免重复运行时再次提交交易。

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

由于该授权存在于链上，撤销后服务端将无法再从 Agent 的钱包构建支付 — 这并不是服务方选择遵守的一项策略。

常见错误

支付构建失败几乎总能归结为资金、网络不匹配或委托状态三者之一。

已验证的配置

注意事项

• MetaplexSvmExactScheme 接受 Umi 签名者和 Solana Kit 的部分交易签名者，但不接受 sign-and-send 签名者。Kit 签名者会在内部完成适配。
• 服务、客户端与支付模式的每种组合都有可运行示例，位于 x402 仓库，可通过 pnpm example:<name> 执行。
• 委托 Agent 示例首次运行时可能会提交一笔授权交易。
• 委托赋予 Mech 从 Agent 钱包中转出 USDC 以支付请求的权限。请在签名者 PDA 中只保留运营所需的余额，并在 Agent 闲置时撤销委托。

快速参考

FAQ

关于 Metaplex x402 支付模式的常见问题。

我应该使用 Metaplex x402 的哪种支付模式？

当应用以自身身份付费时使用标准钱包；当您希望资产在所有者监督下拥有独立预算时使用 Core 资产或 Agent 直接支付；当自主 Agent 必须在无人逐次签名的情况下付费时使用委托 Agent。

支付 Metaplex x402 请求需要 SOL 吗？

只有 Core 资产和 Agent 支付模式需要，此时资产签名者 PDA 需要 SOL 来支付 Core execute 的交易费用。标准钱包支付无需 SOL，因为支付交易的网络费用由服务方的费用支付者承担。

委托 Agent 的认证令牌有效期多长？

授权 JWT 在 24 小时后过期。过期令牌会被丢弃并自动替换，替换只需一次消息签名，无需再次进行链上委托授权。

可以同时使用响应式扩展和主动式 fetch 包装器吗？

不可以。两者是二选一的方案，组合使用会破坏流程。如果您已经在运行 x402Client，或希望可选地回退到直接支付，请使用响应式客户端扩展；如果只针对 Metaplex 端点、希望接线最简单，请使用主动式 fetch 包装器。

如何停止委托 Agent 继续付费？

使用与授权时相同的签名者、资产和 RPC 选项调用 revokeMetaplexCoreExecuteDelegate。委托是一项链上授权，因此撤销会在链上生效，服务端将无法再从该 Agent 的钱包构建支付。

可以用 Token-2022 的 USDC 或其他稳定币支付吗？

不可以。支付来源始终是经典 SPL Token 的关联代币账户，目前不支持 Token-2022 支付铸币。

由 Metaplex Foundation 维护。最后验证日期：2026-09-08。客户端版本：@metaplex-foundation/x402 0.1.0。在 GitHub 上查看源码。