x402

Metaplex x402 API 参考

Last updated September 8, 2026

Metaplex x402 API 部署在 https://api.metaplex.com/x402,提供三项付费服务、两个免费发现端点和四条 Agent 委托路由。本页是端点、定价和客户端导出的参考;构建付费端点所需的支持支付 fetch 的方法见支付模式指南。

摘要

每个付费端点都会对未付费请求返回 HTTP 402,并附带 PAYMENT-REQUIRED 头,精确说明需要支付什么,客户端随后携带支付证明重试。标准钱包模式,以及 Core 资产或 Agent 直接支付的模式,都会在本地为每笔支付签名;而委托 Agent 则通过一次消息签名完成认证,由服务从 Agent 钱包构建支付。发现端点无需支付也无需签名者。

  • 基础 URL — API 为 https://api.metaplex.com/x402,Solana JSON-RPC 为 https://api.metaplex.com/x402/rpc
  • 传输格式 — 聊天与图像使用标准 OpenAI 请求/响应体,RPC 使用标准 Solana JSON-RPC
  • 结算 — Solana 主网上的 USDC,x402 协议版本 2,exact 方案
  • 客户端版本 — @metaplex-foundation/x402 0.1.0,Node.js 20.18+,仅 ESM

基础 URL 与常量

客户端导出了两个基础 URL,因此应用无需硬编码。

常量值
METAPLEX_X402_BASE_URLhttps://api.metaplex.com/x402
METAPLEX_X402_RPC_URLhttps://api.metaplex.com/x402/rpc

端点

付费端点需要支持支付的 fetch,免费端点则不需要。

方法路径支付说明
GET/x402/models免费可用的模型 ID
GET/x402/pricing免费模型费率、请求最低金额、RPC 方法价格、法律条款 URL
POST/x402/chat/completions付费OpenAI 兼容的聊天补全
POST/x402/images/generations付费OpenAI 兼容的图像生成
POST/x402/rpc付费Solana JSON-RPC 与 DAS,仅限 HTTP
GET/x402/core-execute-delegate/status免费Core 资产的委托状态
POST/x402/core-execute-delegate/approve免费批准执行委托
POST/x402/core-execute-delegate/revoke免费撤销执行委托
POST/x402/core-execute-delegate/auth免费用 Sign-In-With-X 签名换取 24 小时有效的 bearer 令牌

委托路由已由客户端导出中列出的 SDK 辅助函数封装;请调用这些函数,而不要直接调用路由。

发现端点

发现端点可免费调用,并通过客户端辅助函数返回带类型的数据。

无需支付即可读取模型与定价
import { getModels, getPricing } from '@metaplex-foundation/x402';
// Available model IDs, e.g. 'openai/gpt-5.4-mini'.
const models = await getModels();
// Per-model token rates, request minimums, RPC method prices, and legal URLs.
const pricing = await getPricing();

GET /x402/models 返回 OpenAI 格式的模型列表:

GET /x402/models 响应(节选)
{
"object": "list",
"data": [
{ "id": "anthropic/claude-opus-4.8", "object": "model", "created": 0, "owned_by": "anthropic" },
{ "id": "openai/gpt-5.4-mini", "object": "model", "created": 0, "owned_by": "openai" }
]
}

聊天补全端点

POST /x402/chat/completions 接受并返回标准的 OpenAI 聊天补全请求体,模型以 <provider>/<model> 形式指定。

通过 OpenAI SDK 进行聊天补全
import { METAPLEX_X402_BASE_URL } from '@metaplex-foundation/x402';
import OpenAI from 'openai';
const openai = new OpenAI({
// The OpenAI SDK requires a value, but this gateway authenticates by payment.
apiKey: 'x402',
baseURL: METAPLEX_X402_BASE_URL,
fetch: fetchWithPayment,
});
const completion = await openai.chat.completions.create({
model: 'openai/gpt-5.4-mini',
messages: [{ role: 'user', content: 'Say hi in one word.' }],
});

Vercel AI SDK 通过其 OpenAI 兼容提供商访问同一端点:

通过 Vercel AI SDK 进行聊天补全
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { METAPLEX_X402_BASE_URL } from '@metaplex-foundation/x402';
import { generateText } from 'ai';
const metaplex = createOpenAICompatible({
name: 'metaplex-x402',
apiKey: 'x402',
baseURL: METAPLEX_X402_BASE_URL,
fetch: fetchWithPayment,
});
const { text } = await generateText({
model: metaplex.chatModel('openai/gpt-5.4-mini'),
prompt: 'Say hi in one word.',
});

图像生成端点

POST /x402/images/generations 接受标准的 OpenAI 图像生成请求体。

通过 OpenAI SDK 生成图像
const image = await openai.images.generate({
model: 'openai/gpt-image-1.5',
prompt: 'A yellow square.',
size: '1024x1024',
});
通过 Vercel AI SDK 生成图像
import { generateImage } from 'ai';
const { image } = await generateImage({
model: metaplex.imageModel('openai/gpt-image-1.5'),
prompt: 'A yellow square.',
size: '1024x1024',
});

Solana RPC 端点

POST /x402/rpc 接受标准的 Solana JSON-RPC 请求并透传 DAS 方法,每个请求单独定价与支付。

通过 Solana Kit 使用 Solana RPC
import { createSolanaRpcFromTransport, type RpcTransport } from '@solana/kit';
import { METAPLEX_X402_RPC_URL } from '@metaplex-foundation/x402';
const rpcTransport: RpcTransport = async ({ payload, signal }) => {
const response = await fetchWithPayment(METAPLEX_X402_RPC_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
signal: signal ?? null,
});
return response.json();
};
const rpc = createSolanaRpcFromTransport(rpcTransport);
const slot = await rpc.getSlot().send();
通过 web3.js 使用 Solana RPC
import { METAPLEX_X402_RPC_URL } from '@metaplex-foundation/x402';
import { Connection } from '@solana/web3.js';
const connection = new Connection(METAPLEX_X402_RPC_URL, {
fetch: fetchWithPayment,
});
const slot = await connection.getSlot();

x402 的 RPC 端点仅支持 HTTP

不支持 WebSocket 连接和订阅。accountSubscribe、logsSubscribe 等订阅方法请使用常规 RPC 提供商。

支付质询字段

对付费端点发起未付费请求会返回 HTTP 402,并附带 base64 编码的 PAYMENT-REQUIRED 头。使用 @metaplex-foundation/x402 构建的客户端会自动解析该头;下列字段供调试以及非 JavaScript 客户端参考。

字段示例值含义
x402Version2协议版本
accepts[].schemeexact支付方案
accepts[].networksolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpSolana 主网的 CAIP-2 网络标识符
accepts[].assetEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1vUSDC 铸币地址
accepts[].amount1000以该资产最小单位计的金额 — 1000 即 $0.001
accepts[].payTo9AYgwvWMhZuir6rZoto13jrU1oZA1XxRDhqPznxyomHv收款账户
accepts[].maxTimeoutSeconds300必须提交支付的时间窗口
accepts[].extra.quoteIdUUID标识本次支付对应的报价
accepts[].extra.usageOpenAI usage 对象报价所依据的实测 token 用量
accepts[].extra.memometaplex:x402:chat.completions随结算一并写入的 Memo
accepts[].extra.feePayer公钥承担支付交易网络费用的账户
extensions["metaplex-core-execute-delegate"]对象委托认证信息 — sign-in-with-x、bearer 令牌、令牌端点,以及用于指明付款资产的 X-METAPLEX-CORE-ASSET 头

报价基于实测用量计算

推理请求的 402 质询会携带 quoteId 和已填充的 usage 对象,因此金额反映的是该请求实际消耗的 token,而非估算值。响应头 PAYMENT-REQUIRED 和 PAYMENT-RESPONSE 均已通过 CORS 暴露。

聊天补全定价

聊天模型按每百万 token 计价,输入、缓存输入和输出各有独立费率,并适用每次请求 $0.001 的最低金额。以下费率读取自 2026-09-08 的 GET /x402/pricing。

模型输入缓存输入输出
anthropic/claude-opus-4.8$5.00$0.50$25.00
anthropic/claude-opus-4.7$5.00$0.50$25.00
anthropic/claude-opus-4.6$5.00$0.50$25.00
anthropic/claude-opus-4.5$5.00$0.50$25.00
anthropic/claude-sonnet-4.6$3.00$0.30$15.00
anthropic/claude-sonnet-4.5$3.00$0.30$15.00
anthropic/claude-haiku-4.5$1.00$0.10$5.00
openai/gpt-5.5$5.00$0.50$30.00
openai/gpt-5.4$2.50$0.25$15.00
openai/gpt-5.4-mini$0.75$0.075$4.50
openai/gpt-5.4-nano$0.20$0.02$1.25

当输入 token 超过 272,000 时,openai/gpt-5.5 和 openai/gpt-5.4 适用更高的长上下文费率 — gpt-5.5 为输入 $10.00、输出 $45.00,gpt-5.4 为输入 $5.00、输出 $22.50。

图像生成定价

图像模型按四个类别以每百万 token 计价,同样适用每次请求 $0.001 的最低金额。

模型输入文本输入图像输出图像输出文本
openai/gpt-image-1.5$5.00$8.00$32.00$10.00
openai/gpt-image-2$5.00$8.00$30.00$10.00

Solana RPC 定价

RPC 调用默认每次请求 $0.00001,较重的方法费率更高。

方法每次请求价格
默认(未列出的所有方法)$0.00001
getBlockTime$0.00001
getTransaction$0.00002
getBlocks$0.00002
getBlocksWithLimit$0.00002
getConfirmedTransaction$0.00002
getBlock$0.00005
getConfirmedBlock$0.00005
getSignaturesForAddress$0.00010

MetaplexSvmExactScheme 选项

MetaplexSvmExactScheme 是用于 Core 资产和 Agent 支付的支付方案。

选项是否必填说明
rpcUrl是用于构建支付交易的 RPC 端点
coreExecute.assetCore 资产支付时必填由其签名者 PDA 出资的 Core 资产或 Agent
coreExecute.collection资产属于合集时必填该资产所属的 Core 合集
coreExecute.executionDelegateRecord否进阶:覆盖执行委托记录
commitment否获取区块哈希时的 commitment,默认 confirmed
computeUnitLimit否Core execute 支付默认 200,000,其他情况为 20,000

该方案接受 Umi 签名者和 Solana Kit 的部分交易签名者,但不接受 sign-and-send 签名者。Kit 签名者会在内部完成适配。

客户端导出

@metaplex-foundation/x402 将其公开 API 集中在包根目录。

类别导出
支付MetaplexSvmExactScheme、MetaplexSvmSigner、kitPartialTransactionSignerToUmiSigner
Agent 委托fetchMetaplexCoreExecuteDelegateStatus、approveMetaplexCoreExecuteDelegate、revokeMetaplexCoreExecuteDelegate、authorizeMetaplexCoreExecuteDelegate
Agent 支付传输层createMetaplexCoreExecuteDelegateClientExtension、wrapFetchWithMetaplexCoreExecuteDelegate 以及各令牌存储实现
发现getModels、getPricing、METAPLEX_X402_BASE_URL、METAPLEX_X402_RPC_URL

选项与结果类型、协议常量以及委托路由的 schema 同样从包根目录导出。

环境变量

x402 仓库中的可运行示例会读取以下变量。

变量是否必填说明
SVM_PRIVATE_KEY是Base58 编码的 64 字节开发用密钥对
CORE_ASSET_ADDRESSCore 资产与 Agent 示例由该密钥对拥有的 Metaplex Core 资产
SVM_RPC_URL否x402 SVM 方案使用的自定义 Solana RPC URL
METAPLEX_X402_BASE_URL否API 基础 URL,默认 https://api.metaplex.com/x402
METAPLEX_X402_RPC_URL否RPC URL,默认 https://api.metaplex.com/x402/rpc
METAPLEX_API_BASE_URL否本地开发用的 API 根地址覆盖,例如 http://localhost:3000/api

注意事项

  • 本参考中的价格是 2026-09-08 读取的快照。线上服务的 GET /x402/pricing 才是实际生效的价目表,且可免费调用。
  • 支付以 USDC 从经典 SPL Token 的关联代币账户结算。目前不支持 Token-2022 支付铸币。
  • Core 资产和 Agent 支付模式需要在资产签名者 PDA 中保留 SOL 以支付 Core execute 费用;标准钱包支付则不需要。
  • 托管服务端不是开源的。客户端、示例和协议类型以 Apache-2.0 发布。
  • 使用本 API 即表示同意 Metaplex.com 使用条款和隐私政策。

快速参考

项目值
API 基础 URLhttps://api.metaplex.com/x402
RPC URLhttps://api.metaplex.com/x402/rpc
JS 客户端@metaplex-foundation/x402(0.1.0)
运行时Node.js 20.18+、ESM
协议x402 版本 2,exact 方案
网络solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp(Solana 主网)
支付铸币EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v(USDC)
运营 AgentMECHjj31U1hBapoVeJtZo5U5WGRd2293JEwRErvPTuF
源代码GitHub(Apache-2.0)

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