---
title: "Transfer SPL Tokens"
method: POST
path: "/v1/spl/transfer"
---

# Transfer SPL Tokens

`POST /v1/spl/transfer`

Transfer SPL tokens publicly or privately through an ephemeral rollup. Accepts an optional `Authorization: Bearer <token>` header obtained from the `/v1/spl/login` flow when the request needs to read or write data inside the Private Ephemeral Rollup.

## Request body

- object
  - `from` string, required — Sender wallet pubkey.
  - `to` string, required — Recipient wallet pubkey, or an initialized stealth handle (e.g. `alice@magicblock.id`). When a non-pubkey handle is provided it is resolved via its stealth pool and requires `visibility: private`, `fromBalance: base`, `toBalance: base`.
  - `cluster` union — Optional. Use `mainnet` for BASE_RPC_URL and EPHEMERAL_RPC_URL, `devnet` for BASE_DEVNET_RPC_URL and EPHEMERAL_DEVNET_RPC_URL, or provide a custom http(s) RPC URL to override the base RPC while keeping the configured ephemeral RPC.
    - 'mainnet' | 'devnet'
    - string
  - `mint` string, required — SPL mint pubkey.
  - `amount` integer, required — Base-unit amount as an integer JSON value with minimum 1.
  - `visibility` 'public' | 'private' — Optional. Defaults to `private`. Use `public` for a transparent SPL transfer or `private` to route through the Private Ephemeral Rollup.
  - `fromBalance` 'base' | 'ephemeral' — Optional. Defaults to `base`. Where the sender's balance is held. Drives which RPC the API uses for blockhash and where the client should submit.
  - `toBalance` 'base' | 'ephemeral' — Optional. Defaults to `base`. Where the recipient should receive the funds.
  - `exactOut` boolean — Optional. When `true`, treats `amount` as the exact amount the recipient should receive (relevant when fees are deducted).
  - `validator` string — Optional. When this transfer route needs a validator and none is provided, the API resolves it from the selected ephemeral RPC via `getIdentity`.
  - `initIfMissing` boolean — Optional. Initialize the transfer queue if missing.
  - `initAtasIfMissing` boolean — Optional. Initialize associated token accounts if missing.
  - `initVaultIfMissing` boolean — Optional. Initialize the vault if missing. Defaults to `false`.
  - `memo` string — Optional. Appends a final Memo Program instruction with this UTF-8 message.
  - `minDelayMs` string — Optional. Private transfer only. Defaults to `0`. Earliest (ms) the queued transfer may settle.
  - `maxDelayMs` string — Optional. Private transfer only. Defaults to `0` when omitted, or to `minDelayMs` when only `minDelayMs` is set. Must be >= `minDelayMs`.
  - `clientRefId` string — Optional. Private transfer only. Encrypted client reference ID that can be used to confirm a payment.
  - `split` integer — Optional. Private transfer only. Defaults to `1`. Number of queue entries to split the transfer across. Must be between 1 and 15 and cannot exceed `amount`.
  - `gasless` boolean — Optional. When `true`, the API uses the configured sponsor as transaction fee payer and prepends a relay-fee token transfer to the sponsor ATA.
  - `legacy` boolean — Optional. Defaults to `false`. When `true`, skips lookup-table compilation and returns a legacy transaction. Private `base -> base` transfers may otherwise return a v0 transaction when a useful lookup table is configured.

## Response `200`

Unsigned serialized transaction

- object
  - `kind` 'transfer', required
  - `version` 'legacy' | 'v0', required
  - `transactionBase64` string, required
  - `sendTo` 'base' | 'ephemeral', required
  - `from` 'base' | 'ephemeral' — Mirrors the request `fromBalance`.
  - `recentBlockhash` string, required
  - `lastValidBlockHeight` integer, required
  - `instructionCount` integer, required
  - `requiredSigners` string[], required
  - `validator` string
  - `fees` object — Fees applied to the transfer, in base units.
    - `lamports` string, required
    - `tokens` string, required

## Other responses

- `400` — Build error or unsupported transfer route (`UNSUPPORTED_TRANSFER_ROUTE`)
- `422` — Validation error

---

[API](https://skmtc.dev/magicblock/apis/magicblock-router-api.md) · [All operations](https://skmtc.dev/magicblock/apis/magicblock-router-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/magicblock/magicblock-router-api/revisions/f024efa907c6/schema)