> ## 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 API 文档

<CardGroup cols={2}>
  <Card title="Ephemeral SPL Token Program" icon="github" href="https://github.com/magicblock-labs/ephemeral-spl-token" iconType="duotone">
    链上 Ephemeral SPL Token 程序
  </Card>

  <Card title="私密支付示例" icon="shield-check" href="https://one.magicblock.app/" iconType="duotone">
    查看私密支付示例应用及其 API 流程
  </Card>
</CardGroup>

## 概述

Ephemeral SPL Token API 用于在 Solana 与 MagicBlock ephemeral rollups 之间构建未签名的 SPL token 存入、转账、提取、swap 与 mint 初始化交易。它还提供余额查询、mint 初始化状态、stealth pool，以及为读取私密数据签发 bearer token 的钱包 challenge/login 流程。官方公开参考可见 [payments.magicblock.app/reference](https://payments.magicblock.app/reference)。

### 元信息

* [**健康状态**](/cn/pages/ephemeral-spl-token/api-reference/health) - 检查 API 健康状态与可用性
* [**发送交易**](/cn/pages/ephemeral-spl-token/api-reference/transaction-send) - 将已签名交易提交到 base layer 或 ephemeral RPC

### 认证

* [**挑战**](/cn/pages/ephemeral-spl-token/api-reference/challenge) - 生成需由钱包签名的 challenge 字符串
* [**登录**](/cn/pages/ephemeral-spl-token/api-reference/login) - 用已签名的 challenge 换取 bearer token

### SPL

* [**存入 SPL Token**](/cn/pages/ephemeral-spl-token/api-reference/deposit) - 构建从 Solana 进入 ephemeral rollup 的未签名存入交易
* [**转移 SPL Token**](/cn/pages/ephemeral-spl-token/api-reference/transfer) - 构建未签名的公开或私密 SPL 转账
* [**提取 SPL Token**](/cn/pages/ephemeral-spl-token/api-reference/withdraw) - 构建返回 Solana 的未签名提取交易
* [**取消委托 Ephemeral ATA**](/cn/pages/ephemeral-spl-token/api-reference/undelegate-ephemeral-ata) - 构建未签名交易，为某个 mint 取消委托钱包的 eATA
* [**初始化 Mint**](/cn/pages/ephemeral-spl-token/api-reference/initialize-mint) - 构建未签名交易，为某个 mint 初始化 validator-scoped transfer queue
* [**确保 Transfer Queue Crank 运行**](/cn/pages/ephemeral-spl-token/api-reference/transfer-queue-ensure-crank) - 验证 mint 的 transfer queue 并强制尝试运行一次 crank
* [**余额**](/cn/pages/ephemeral-spl-token/api-reference/balance) - 获取某地址在基础链上的 SPL token 余额
* [**私密余额**](/cn/pages/ephemeral-spl-token/api-reference/private-balance) - 获取某地址在 ephemeral rollup 上的 SPL token 余额（需认证）
* [**Mint 是否已初始化**](/cn/pages/ephemeral-spl-token/api-reference/is-mint-initialized) - 检查某个 mint 是否已在 ephemeral RPC 上拥有 validator-scoped transfer queue

### Stealth Pool

* [**创建 Stealth Pool**](/cn/pages/ephemeral-spl-token/api-reference/stealth-pool) - 将 handle 映射到私密转账的目标 key（需认证）
* [**获取 Stealth Pool 状态**](/cn/pages/ephemeral-spl-token/api-reference/stealth-pool-status) - 检查某个 handle 的 stealth pool 是否存在

### Swap

* [**Swap 报价**](/cn/pages/ephemeral-spl-token/api-reference/quote) - 获取两个 SPL mint 之间的 swap 报价
* [**兑换**](/cn/pages/ephemeral-spl-token/api-reference/swap) - 构建未签名的 swap 交易（公开直通或带定时转账的私密模式）

### MCP

* [**MCP**](/cn/pages/ephemeral-spl-token/api-reference/mcp) - 访问无状态的 Streamable HTTP MCP 端点

```
┌────────────────────────────────────────────┐
│ 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  │
└────────────────────────────────────────────┘
```

## 认证流程

读取 Private Ephemeral Rollup 内私密数据的端点需要 bearer token:

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>`

## 响应格式

交易构建端点成功时会返回一个未签名交易载荷:

```json theme={null}
{
  "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"`)