Skip to main content

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

Reference program for private SPL token flows

Private Payment Example

Explore the example private payments application and API flow

​
Overview

The Private Payments API builds unsigned SPL token transactions for deposits, transfers, withdrawals, swaps, and mint initialization across Solana and MagicBlock ephemeral rollups. It also exposes balance queries, mint-initialization status, and a wallet challenge/login flow that issues bearer tokens for reading private data. The canonical public reference is available at payments.magicblock.app/reference.

​
Meta

  • Health - Check API health and availability

​
Auth

  • Challenge - Generate a challenge string for the wallet to sign
  • Login - Exchange a signed challenge for a bearer token

​
SPL

  • Deposit SPL Tokens - Build an unsigned deposit transaction from Solana into an ephemeral rollup
  • Transfer SPL Tokens - Build an unsigned public or private SPL transfer
  • Withdraw SPL Tokens - Build an unsigned withdrawal transaction back to Solana
  • Initialize Mint - Build an unsigned transaction that initializes a validator-scoped transfer queue for a mint
  • Balance - Get the base-chain SPL token balance for an address
  • Private Balance - Get the ephemeral-rollup SPL token balance for an address (auth required)
  • Is Mint Initialized - Check whether a mint has a validator-scoped transfer queue on the ephemeral RPC

​
Swap

  • Swap Quote - Get a swap quote between two SPL mints
  • Swap - Build an unsigned swap transaction (public pass-through or private with scheduled transfer)

​
MCP

  • MCP - Access the stateless Streamable HTTP MCP endpoint
┌────────────────────────────────────────────┐
│ 1. Deposit                                │
├────────────────────────────────────────────┤
│ • Build an unsigned deposit transaction   │
│ • Solana base balance → ephemeral rollup  │
└────────────────────────────────────────────┘
                     ↓
┌────────────────────────────────────────────┐
│ 2. Transfer / Swap                        │
├────────────────────────────────────────────┤
│ • Build SPL transfer or swap              │
│ • base/ephemeral → base/ephemeral         │
│ • public or private (delayed + split)     │
└────────────────────────────────────────────┘
                     ↓
┌────────────────────────────────────────────┐
│ 3. Withdraw                               │
├────────────────────────────────────────────┤
│ • Build an unsigned withdrawal            │
│ • ephemeral rollup → Solana base balance  │
└────────────────────────────────────────────┘

​
Auth Flow

Endpoints that read private data inside the Private Ephemeral Rollup require a bearer token:
  1. GET /v1/spl/challenge?pubkey=<wallet> returns a challenge string
  2. The wallet signs the challenge
  3. POST /v1/spl/login with { pubkey, challenge, signature } returns a token
  4. Pass Authorization: Bearer <token> on /v1/spl/private-balance (required) and on /v1/spl/transfer requests that need to connect to the Private Ephemeral Rollup (optional)

​
Response Format

Successful transaction-building endpoints return an unsigned transaction payload: 
{
  "kind": "deposit",
  "version": "legacy",
  "transactionBase64": "base64-encoded-transaction",
  "sendTo": "base",
  "recentBlockhash": "blockhash",
  "lastValidBlockHeight": 284512337,
  "instructionCount": 3,
  "requiredSigners": ["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"]
}
The expected client flow is:
  1. Call the API
  2. Decode transactionBase64
  3. Optionally adjust the transaction if the client needs to
  4. Sign with the required wallet(s)
  5. Send to the RPC indicated by sendTo ("base" or "ephemeral")