Metaplex x402 API 레퍼런스

Metaplex x402 API는 https://api.metaplex.com/x402에서 제공되며 세 가지 유료 서비스, 두 가지 무료 디스커버리 엔드포인트, 네 개의 에이전트 위임 라우트를 노출합니다. 이 페이지는 엔드포인트, 가격, 클라이언트 익스포트 레퍼런스이며, 유료 엔드포인트에 필요한 결제 지원 fetch를 구성하는 방법은 결제 모드 가이드에서 다룹니다.

요약

모든 유료 엔드포인트는 결제되지 않은 요청에 대해 HTTP 402와 무엇을 얼마나 결제해야 하는지 정확히 기술한 PAYMENT-REQUIRED 헤더로 응답하며, 클라이언트는 결제 증명과 함께 재시도합니다. 표준 지갑 모드와 Core 자산 또는 에이전트가 직접 결제하는 모드는 결제마다 로컬에서 서명합니다. 위임된 에이전트는 대신 메시지 서명으로 한 번 인증하고, 서비스가 에이전트 지갑에서 결제를 구성합니다. 디스커버리 엔드포인트에는 결제도 서명자도 필요 없습니다.

• 베이스 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을 모두 익스포트하므로 애플리케이션에서 하드코딩할 필요가 없습니다.

엔드포인트

유료 엔드포인트에는 결제 지원 fetch가 필요하고, 무료 엔드포인트에는 필요하지 않습니다.

위임 라우트는 클라이언트 익스포트에 나열된 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 형식의 모델 목록을 반환합니다.

{
  "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> 형식으로 지정합니다.

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 호환 프로바이더를 통해 동일한 엔드포인트에 도달합니다.

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 이미지 생성 바디를 받습니다.

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 엔드포인트

POST /x402/rpc는 표준 Solana JSON-RPC 요청을 받고 DAS 메서드를 패스스루하며, 각 요청을 개별적으로 과금하고 결제합니다.

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

결제 챌린지 필드

유료 엔드포인트에 결제 없이 요청하면 base64로 인코딩된 PAYMENT-REQUIRED 헤더와 함께 HTTP 402가 반환됩니다. @metaplex-foundation/x402로 만든 클라이언트는 이를 자동으로 파싱하며, 아래 필드는 디버깅 용도와 JavaScript 이외의 클라이언트를 위한 문서입니다.

채팅 완성 가격

채팅 모델은 100만 토큰당 요율로 과금되며 입력, 캐시된 입력, 출력에 각각 별도 요율이 적용되고 요청당 $0.001의 최소 금액이 적용됩니다. 아래 요율은 2026-09-08에 GET /x402/pricing에서 읽은 값입니다.

openai/gpt-5.5와 openai/gpt-5.4는 입력 272,000 토큰을 초과하면 더 높은 롱 컨텍스트 요율이 적용됩니다 — gpt-5.5는 입력 $10.00·출력 $45.00, gpt-5.4는 입력 $5.00·출력 $22.50입니다.

이미지 생성 가격

이미지 모델은 네 가지 구분에 대해 100만 토큰당 과금되며 동일한 요청당 $0.001 최소 금액이 적용됩니다.

Solana RPC 가격

RPC 호출은 기본적으로 요청당 $0.00001이며 무거운 메서드에는 더 높은 요율이 적용됩니다.

MetaplexSvmExactScheme 옵션

MetaplexSvmExactScheme는 Core 에셋 및 에이전트 결제에 사용하는 결제 스킴입니다.

이 스킴은 Umi 서명자와 Solana Kit 부분 트랜잭션 서명자를 허용하지만 sign-and-send 서명자는 허용하지 않습니다. Kit 서명자는 내부적으로 변환됩니다.

클라이언트 익스포트

@metaplex-foundation/x402는 공개 API를 패키지 루트에 집약합니다.

옵션 및 결과 타입, 프로토콜 상수, 위임 라우트 스키마도 패키지 루트에서 익스포트됩니다.

환경 변수

x402 저장소의 실행 가능한 예제는 다음 변수를 읽습니다.

참고 사항

• 이 레퍼런스의 가격은 2026-09-08에 읽은 스냅샷입니다. 유효한 가격표는 라이브 서비스의 GET /x402/pricing이며 무료로 호출할 수 있습니다.
• 결제는 클래식 SPL Token 연관 토큰 계정에서 USDC로 정산됩니다. Token-2022 결제 민트는 현재 지원되지 않습니다.
• Core 에셋 및 에이전트 결제 모드에서는 Core execute 수수료를 위해 에셋 서명자 PDA에 SOL이 필요합니다. 표준 지갑 결제에는 필요하지 않습니다.
• 호스팅 서버는 오픈소스가 아닙니다. 클라이언트, 예제, 프로토콜 타입은 Apache-2.0으로 공개되어 있습니다.
• API 이용은 Metaplex.com 이용약관 및 개인정보 처리방침에 동의하는 것을 의미합니다.

빠른 참조

Metaplex Foundation 관리. 최종 검증: 2026-09-08. 클라이언트 버전: @metaplex-foundation/x402 0.1.0. GitHub에서 소스 보기.