메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.magicblock.gg/llms.txt

Use this file to discover all available pages before exploring further.

Ephemeral SPL Token Program

프라이빗 SPL 토큰 흐름용 참조 프로그램

프라이빗 결제 예제

프라이빗 결제 애플리케이션과 API 흐름 예제를 살펴보세요

​
개요

Private Payments API는 Solana와 MagicBlock ephemeral rollups 전반에서 입금, 전송, 출금, swap, mint 초기화를 위한 미서명 SPL 토큰 트랜잭션을 생성합니다. 잔액 조회, mint 초기화 상태 조회, 그리고 프라이빗 데이터를 읽기 위한 bearer 토큰을 발급하는 지갑 challenge/login 흐름도 제공합니다. 공식 공개 레퍼런스는 payments.magicblock.app/reference에서 확인할 수 있습니다.

​
메타

  • Health - API 상태와 가용성을 확인합니다

​
인증

  • Challenge - 지갑이 서명할 challenge 문자열을 생성합니다
  • Login - 서명된 challenge를 bearer 토큰으로 교환합니다

​
SPL

  • Deposit SPL Tokens - Solana에서 ephemeral rollup으로 들어가는 미서명 입금 트랜잭션을 생성합니다
  • Transfer SPL Tokens - 미서명 공개 또는 비공개 SPL 전송을 생성합니다
  • Withdraw SPL Tokens - Solana로 되돌리는 미서명 출금 트랜잭션을 생성합니다
  • Initialize Mint - mint용 validator-scoped transfer queue를 초기화하는 미서명 트랜잭션을 생성합니다
  • Balance - 주소의 base-chain SPL 토큰 잔액을 가져옵니다
  • Private Balance - 주소의 ephemeral-rollup SPL 토큰 잔액을 가져옵니다 (인증 필요)
  • Is Mint Initialized - mint가 ephemeral RPC에 validator-scoped transfer queue를 가지고 있는지 확인합니다

​
Swap

  • Swap Quote - 두 SPL mint 사이의 swap 견적을 가져옵니다
  • Swap - 미서명 swap 트랜잭션을 생성합니다 (공개 패스스루 또는 예약 전송이 포함된 비공개 모드)

​
MCP

  • MCP - stateless Streamable HTTP MCP endpoint에 접근합니다
┌────────────────────────────────────────────┐
│ 1. Deposit                                │
├────────────────────────────────────────────┤
│ • 미서명 입금 트랜잭션 생성               │
│ • Solana base balance → ephemeral rollup  │
└────────────────────────────────────────────┘
                     ↓
┌────────────────────────────────────────────┐
│ 2. Transfer / Swap                        │
├────────────────────────────────────────────┤
│ • SPL 전송 또는 swap 생성                 │
│ • base/ephemeral → base/ephemeral         │
│ • 공개 또는 비공개 (지연 + 분할)          │
└────────────────────────────────────────────┘
                     ↓
┌────────────────────────────────────────────┐
│ 3. Withdraw                               │
├────────────────────────────────────────────┤
│ • 미서명 출금 트랜잭션 생성               │
│ • ephemeral rollup → Solana base balance  │
└────────────────────────────────────────────┘

​
인증 흐름

Private Ephemeral Rollup 내부의 프라이빗 데이터를 읽는 엔드포인트는 bearer 토큰이 필요합니다:
  1. GET /v1/spl/challenge?pubkey=<wallet>이 challenge 문자열을 반환합니다
  2. 지갑이 challenge에 서명합니다
  3. POST /v1/spl/login에 { pubkey, challenge, signature }를 보내면 token이 반환됩니다
  4. /v1/spl/private-balance (필수)와 Private Ephemeral Rollup 연결이 필요한 /v1/spl/transfer 요청 (선택)에 Authorization: Bearer <token>을 전달합니다

​
응답 형식

트랜잭션 생성 엔드포인트가 성공하면 미서명 트랜잭션 페이로드를 반환합니다: 
{
  "kind": "deposit",
  "version": "legacy",
  "transactionBase64": "base64-encoded-transaction",
  "sendTo": "base",
  "recentBlockhash": "blockhash",
  "lastValidBlockHeight": 284512337,
  "instructionCount": 3,
  "requiredSigners": ["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"]
}
클라이언트 흐름:
  1. API를 호출합니다
  2. transactionBase64를 디코딩합니다
  3. 필요하면 클라이언트가 트랜잭션을 조정합니다
  4. 필요한 지갑으로 서명합니다
  5. sendTo가 가리키는 RPC ("base" 또는 "ephemeral")로 전송합니다