Metaplex x402 API Reference

The Metaplex x402 API is served at https://api.metaplex.com/x402 and exposes three paid services, two free discovery endpoints, and four agent delegation routes. This page is the endpoint, pricing, and client-export reference; the payment modes guide covers how to build the payment-aware fetch that paid endpoints require.

Summary

Every paid endpoint answers an unpaid request with HTTP 402 and a PAYMENT-REQUIRED header describing exactly what to pay, and the client retries with a payment proof. Standard-wallet and direct Core asset or agent modes sign each payment locally; a delegated agent instead authenticates once with a message signature and lets the service build payments from the agent's wallet. Discovery endpoints need no payment and no signer.

• Base URLs — https://api.metaplex.com/x402 for the API, https://api.metaplex.com/x402/rpc for Solana JSON-RPC
• Wire format — canonical OpenAI request and response bodies for chat and images, standard Solana JSON-RPC for RPC
• Settlement — USDC on Solana mainnet, x402 protocol version 2, exact scheme
• Client version — @metaplex-foundation/x402 0.1.0, Node.js 20.18+, ESM only

Base URLs and Constants

The client exports both base URLs so applications do not hardcode them.

Endpoints

Paid endpoints require a payment-aware fetch; free endpoints do not.

The delegation routes are wrapped by the SDK helpers listed under client exports; call those rather than the routes directly.

Discovery Endpoints

Discovery endpoints are free to call and return typed data through the client's helpers.

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 returns an OpenAI-shaped model list:

{
  "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" }
  ]
}

Chat Completions Endpoint

POST /x402/chat/completions accepts and returns canonical OpenAI chat completion bodies, with models addressed as <provider>/<model>.

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

The Vercel AI SDK reaches the same endpoint through its OpenAI-compatible provider:

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

Image Generation Endpoint

POST /x402/images/generations accepts canonical OpenAI image generation bodies.

const image = await openai.images.generate({
  model: 'openai/gpt-image-1.5',
  prompt: 'A yellow square.',
  size: '1024x1024',
});

import { generateImage } from 'ai';

const { image } = await generateImage({
  model: metaplex.imageModel('openai/gpt-image-1.5'),
  prompt: 'A yellow square.',
  size: '1024x1024',
});

Solana RPC Endpoint

POST /x402/rpc accepts standard Solana JSON-RPC requests and passes DAS methods through, pricing and paying for each request independently.

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

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

Payment Challenge Fields

An unpaid request to a paid endpoint returns HTTP 402 with a base64 PAYMENT-REQUIRED header. Clients built with @metaplex-foundation/x402 parse this automatically; the fields are documented here for debugging and for non-JavaScript clients.

Chat Completion Pricing

Chat models are priced per million tokens with separate input, cached-input, and output rates, subject to a $0.001 per-request minimum. The rates below were read from GET /x402/pricing on 2026-09-08.

openai/gpt-5.5 and openai/gpt-5.4 carry higher long-context rates above 272,000 input tokens — $10.00 input and $45.00 output for gpt-5.5, and $5.00 input and $22.50 output for gpt-5.4.

Image Generation Pricing

Image models are priced per million tokens across four categories, with the same $0.001 per-request minimum.

Solana RPC Pricing

RPC calls are priced per request at $0.00001 by default, with higher rates for heavier methods.

MetaplexSvmExactScheme Options

MetaplexSvmExactScheme is the payment scheme used for Core asset and agent payments.

The scheme accepts Umi signers and Solana Kit partial transaction signers, but not sign-and-send signers. Kit signers are adapted internally.

Client Exports

@metaplex-foundation/x402 centralizes its public API in the package root.

Option and result types, protocol constants, and delegate route schemas are exported from the package root as well.

Environment Variables

The runnable examples in the x402 repository read the following variables.

Notes

• Prices in this reference are a snapshot read on 2026-09-08. GET /x402/pricing on the live service is the operative price list and is free to call.
• Payments settle in USDC from a classic SPL Token associated token account. Token-2022 payment mints are not currently supported.
• Core asset and agent payment modes require SOL in the asset signer PDA to cover Core execute fees; standard wallet payments do not.
• The hosted server is not open source. The client, its examples, and the protocol types are published under Apache-2.0.
• Using the API means agreeing to the Metaplex.com Terms of Use and Privacy Policy.

Quick Reference

Maintained by Metaplex Foundation. Last verified: 2026-09-08. Client version: @metaplex-foundation/x402 0.1.0. View source on GitHub.