Introduction

Ephemeral SPL Token API documentation

Ephemeral SPL Token Program

The on-chain Ephemeral SPL Token program

Private Payment Example

Explore the example private payments application and API flow

Overview

The Ephemeral SPL Token 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, stealth pools, 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
• Send Transaction - Submit a signed transaction to the base layer or ephemeral RPC

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
• Undelegate Ephemeral ATA - Build an unsigned transaction that undelegates a wallet’s eATA for a mint
• Initialize Mint - Build an unsigned transaction that initializes a validator-scoped transfer queue for a mint
• Ensure Transfer Queue Crank - Verify a mint’s transfer queue and force one crank attempt
• 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

Stealth Pools

• Create Stealth Pool - Map a handle to destination keys for private transfers (auth required)
• Get Stealth Pool Status - Check whether a handle’s stealth pool exists

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")