Metaplex

소개

Metaplex API

Last updated August 1, 2026

Metaplex API는 api.metaplex.com의 공개 REST API입니다. Genesis 런칭 데이터를 제공하고, 런칭 생성 트랜잭션을 빌드하며, Metaplex Agent Registry를 노출합니다 — 에이전트 탐색, A2A AgentCard 제공, 에이전트 지갑 트랜잭션 빌드가 가능합니다. metaplex.com 런칭 플랫폼을 구동하는 것도 바로 이 API이며, 여기에 문서화된 엔드포인트는 사이트 자체가 사용하는 것과 동일합니다.

Summary

Metaplex API는 Genesis 런칭 데이터, 런칭 생성, 에이전트 레지스트리에 대한 공개 HTTP 액세스를 제공합니다 — SDK나 인증이 필요 없습니다.

  • Genesis 주소, 토큰 민트로 런칭을 조회하거나 모든 활성 런칭 탐색
  • 새 Genesis 런칭 생성 및 등록
  • 에이전트 레지스트리 탐색 및 검색, 에이전트별 A2A AgentCard 조회
  • 에이전트 민팅, 자금 지원(fund), 출금(withdraw) 트랜잭션 빌드
  • https://api.metaplex.com/v1의 공개 REST API — 인증 불필요
  • metaplex.com 런칭 플랫폼을 구동하는 API — 통합 개발자는 플랫폼과 동일한 엔드포인트를 사용
  • network 쿼리 파라미터를 통해 Solana 메인넷(기본값) 및 데브넷 지원
  • 기계 판독 가능한 OpenAPI 3.1 명세: YAML(표준) / JSON, RFC 9727 API 카탈로그를 통해 검색 가능

기본 URL

https://api.metaplex.com/v1

네트워크 선택

기본적으로 API는 Solana 메인넷의 데이터를 반환합니다. 데브넷 런칭을 조회하려면 network 쿼리 파라미터를 추가하세요:

?network=solana-devnet

예시:

# Mainnet (default)

curl https://api.metaplex.com/v1/launches/7nE9GvcwsqzYcPUYfm5gxzCKfmPqi68FM7gPaSfG6EQN



# Devnet

curl "https://api.metaplex.com/v1/launches/7nE9GvcwsqzYcPUYfm5gxzCKfmPqi68FM7gPaSfG6EQN?network=solana-devnet"

인증

인증이 필요하지 않습니다. API는 속도 제한이 있는 공개 API입니다.

런칭 엔드포인트

메서드엔드포인트설명
GET/launches/{genesis_pubkey}Genesis 주소로 런칭 데이터 조회
GET/tokens/{mint}토큰 민트의 모든 런칭 조회
GET/launches필터를 사용하여 런칭 목록 조회
GET/launches?spotlight=true추천 스포트라이트 런칭 조회
POST/launches/create새 런칭을 위한 온체인 트랜잭션 빌드
POST/launches/register확인된 런칭을 목록에 등록
POST/twitter/verify런칭 등록을 위한 Twitter 계정 소유권 인증
POST/creator-rewards/claim크리에이터 보상 청구 트랜잭션 빌드

POST 엔드포인트(/launches/create 및 /launches/register)는 새 토큰 런칭을 생성하기 위해 함께 사용됩니다. 대부분의 사용 사례에서는 두 엔드포인트를 래핑하는 SDK API 클라이언트가 더 간단한 인터페이스를 제공합니다. 실시간 온체인 런칭 상태는 SDK 체인 메서드 fetchBucketState 및 fetchDepositState로 직접 읽을 수 있습니다.

에이전트 엔드포인트

메서드엔드포인트설명
GET/agents등록된 에이전트 목록 및 검색 (페이지네이션)
GET/agents/{address}토큰 및 메타데이터를 포함한 단일 에이전트 조회
GET/agents/{address}/agent-card.json호스팅된 A2A AgentCard 조회
POST/agents/mint에이전트 민팅 + 등록 트랜잭션 빌드
POST/agents/{address}/fund에이전트 지갑으로의 SOL 전송 빌드
POST/agents/{address}/withdraw에이전트 지갑에서 출금 빌드 (소유자 전용)

단계별 안내와 함께 에이전트를 민팅하려면 에이전트 민팅하기를 참조하세요.

트랜잭션 빌드 엔드포인트

트랜잭션을 빌드하는 POST 엔드포인트는 사용자 키를 보관하지 않으며 트랜잭션을 제출하지도 않습니다. 각 엔드포인트는 base64로 직렬화된 하나 이상의 트랜잭션과 빌드에 사용된 블록해시를 반환합니다. 애플리케이션이 이를 역직렬화하고, 사용자의 지갑으로 서명한 후 네트워크에 제출합니다.

오류 코드

코드설명
400잘못된 요청 - 유효하지 않은 파라미터
403해당 작업에 대한 권한 없음 (예: 소유하지 않은 에이전트에서 출금 시도)
404런칭, 토큰 또는 에이전트를 찾을 수 없음
429속도 제한 초과
500내부 서버 오류

응답 엔벨로프

API의 발전 과정을 반영하여 두 가지 엔벨로프 규약이 사용됩니다:

런칭 읽기 엔드포인트 (/launches*, /tokens/*, /creator-rewards/claim)는 결과를 data로, 오류를 error.message로 래핑합니다:

{ "data": { "…": "…" } }

{ "error": { "message": "Launch not found" } }

**에이전트 엔드포인트, 런칭 쓰기 엔드포인트, /twitter/verify**는 success 판별자(discriminator)를 사용합니다:

{ "success": true, "…": "…" }

{ "success": false, "error": "Agent not found" }

예외는 /agents/{address}/agent-card.json입니다. A2A 클라이언트가 직접 사용할 수 있도록 엔벨로프 없이 원시 AgentCard JSON을 반환합니다. 각 엔드포인트 페이지와 OpenAPI 명세에 정확한 형태가 문서화되어 있습니다.

기계 판독 가능한 명세

전체 API 계약은 OpenAPI 3.1 문서로 게시되며, API의 요청 유효성 검사기(request validator)로부터 직접 생성되므로 구현과 어긋날 수 없습니다:

형식URL
YAML (표준)https://api.metaplex.com/v1/openapi.yaml
JSONhttps://api.metaplex.com/v1/openapi.json
현재 버전 별칭https://api.metaplex.com/openapi.json / openapi.yaml
RFC 9727 API 카탈로그https://api.metaplex.com/.well-known/api-catalog

명세를 Postman, Swagger UI, 코드 생성기 또는 에이전트 프레임워크로 가져오면 모든 엔드포인트에 대한 타입이 지정된 클라이언트와 호출 가능한 도구를 얻을 수 있습니다.

Notes

  • API에는 속도 제한이 있습니다. 429 응답을 받으면 요청 빈도를 줄이세요.
  • 모든 날짜 필드(startTime, endTime, graduatedAt, lastActivityAt)는 ISO 8601 문자열로 반환됩니다. 본딩 커브 런칭은 종료 시간이 없으므로 endTime이 null입니다.
  • 기본 네트워크는 solana-mainnet입니다. 데브넷 데이터는 ?network=solana-devnet으로 이용 가능합니다.
  • POST 엔드포인트의 경우 SDK API 클라이언트를 사용하는 것이 권장됩니다. /launches/create와 /launches/register를 래핑합니다.

공유 타입

TypeScript

interface Launch {

  launchPage: string;

  mechanic: string;

  genesisAddress: string;

  spotlight: boolean;

  startTime: string;

  endTime: string | null;

  status: 'upcoming' | 'live' | 'graduated' | 'ended';

  heroUrl: string | null;

  graduatedAt: string | null;

  lastActivityAt: string;

  type: 'launchpool' | 'presale' | 'bondingCurve' | 'auction' | 'custom';

}



interface BaseToken {

  address: string;

  name: string;

  symbol: string;

  image: string;

  description: string;

}



interface Socials {

  x?: string;

  telegram?: string;

  discord?: string;

}



interface ErrorResponse {

  error: {

    message: string;

  };

}

Rust

use serde::{Deserialize, Serialize};



#[derive(Debug, Serialize, Deserialize)]

#[serde(rename_all = "camelCase")]

pub struct Launch {

    pub launch_page: String,

    pub mechanic: String,

    pub genesis_address: String,

    pub spotlight: bool,

    pub start_time: String,

    pub end_time: Option<String>,

    pub status: String,

    pub hero_url: Option<String>,

    pub graduated_at: Option<String>,

    pub last_activity_at: String,

    #[serde(rename = "type")]

    pub launch_type: String,

}



#[derive(Debug, Serialize, Deserialize)]

#[serde(rename_all = "camelCase")]

pub struct BaseToken {

    pub address: String,

    pub name: String,

    pub symbol: String,

    pub image: String,

    pub description: String,

}



#[derive(Debug, Serialize, Deserialize)]

pub struct Socials {

    pub x: Option<String>,

    pub telegram: Option<String>,

    pub discord: Option<String>,

}



#[derive(Debug, Serialize, Deserialize)]

pub struct ApiError {

    pub message: String,

}



#[derive(Debug, Serialize, Deserialize)]

pub struct ErrorResponse {

    pub error: ApiError,

}

Cargo.toml에 다음 의존성을 추가하세요:

[dependencies]

reqwest = { version = "0.12", features = ["json"] }

tokio = { version = "1", features = ["full"] }

serde = { version = "1", features = ["derive"] }

Glossary

용어정의
Genesis Address특정 런칭 캠페인을 고유하게 식별하는 PDA (Program Derived Address)
Base Token민트 주소로 식별되는 런칭 대상 토큰
Launch Page사용자가 런칭에 참여할 수 있는 URL
Mechanic런칭에 사용되는 할당 메커니즘 (예: launchpoolV2, presaleV2, bondingCurveV2)
Launch Type런칭의 기본 메커니즘: launchpool, presale 또는 bondingCurve
Spotlight플랫폼에서 큐레이팅한 주요 런칭을 나타내는 플래그
Status런칭의 현재 상태: upcoming, live, graduated, ended
Socials토큰과 관련된 소셜 미디어 링크 (X/Twitter, Telegram, Discord)
LaunchDatalaunch, baseToken, website, socials를 포함하는 응답 래퍼
TokenData토큰 쿼리용 응답 래퍼. launches 배열과 baseToken, website, socials 포함
Next
런치 조회