Sign in

v1

latestOpenAPI 3.1.02026-07-2619047.9 KB

Transfer SPL Tokens

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.

post/v1/spl/transfer

Request body

fromstring required

Sender wallet pubkey.

tostring 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.

mintstring required

SPL mint pubkey.

amountinteger 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.

exactOutboolean

Optional. When true, treats amount as the exact amount the recipient should receive (relevant when fees are deducted).

validatorstring

Optional. When this transfer route needs a validator and none is provided, the API resolves it from the selected ephemeral RPC via getIdentity.

initIfMissingboolean

Optional. Initialize the transfer queue if missing.

initAtasIfMissingboolean

Optional. Initialize associated token accounts if missing.

initVaultIfMissingboolean

Optional. Initialize the vault if missing. Defaults to false.

memostring

Optional. Appends a final Memo Program instruction with this UTF-8 message.

minDelayMsstring

Optional. Private transfer only. Defaults to 0. Earliest (ms) the queued transfer may settle.

maxDelayMsstring

Optional. Private transfer only. Defaults to 0 when omitted, or to minDelayMs when only minDelayMs is set. Must be >= minDelayMs.

clientRefIdstring

Optional. Private transfer only. Encrypted client reference ID that can be used to confirm a payment.

splitinteger

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.

gaslessboolean

Optional. When true, the API uses the configured sponsor as transaction fee payer and prepends a relay-fee token transfer to the sponsor ATA.

legacyboolean

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.

Example request

{
  "from": "3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE",
  "to": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": 1000000,
  "visibility": "private",
  "fromBalance": "base",
  "toBalance": "base",
  "exactOut": false,
  "initIfMissing": true,
  "initAtasIfMissing": true,
  "initVaultIfMissing": false,
  "memo": "Order #1042",
  "minDelayMs": "0",
  "maxDelayMs": "0",
  "clientRefId": "42",
  "split": 1,
  "gasless": true
}

Response

Unsigned serialized transaction

kind'transfer' required
version'legacy' | 'v0' required
transactionBase64string required
sendTo'base' | 'ephemeral' required
from'base' | 'ephemeral'

Mirrors the request fromBalance.

recentBlockhashstring required
lastValidBlockHeightinteger required
instructionCountinteger required
requiredSignersstring[] required
validatorstring