Transfer SPL Tokens
curl --request POST \
--url https://payments.magicblock.app/v1/spl/transfer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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
}
'import requests
url = "https://payments.magicblock.app/v1/spl/transfer"
payload = {
"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
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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
})
};
fetch('https://payments.magicblock.app/v1/spl/transfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://payments.magicblock.app/v1/spl/transfer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://payments.magicblock.app/v1/spl/transfer"
payload := strings.NewReader("{\n \"from\": \"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE\",\n \"to\": \"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L\",\n \"mint\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n \"amount\": 1000000,\n \"visibility\": \"private\",\n \"fromBalance\": \"base\",\n \"toBalance\": \"base\",\n \"exactOut\": false,\n \"initIfMissing\": true,\n \"initAtasIfMissing\": true,\n \"initVaultIfMissing\": false,\n \"memo\": \"Order #1042\",\n \"minDelayMs\": \"0\",\n \"maxDelayMs\": \"0\",\n \"clientRefId\": \"42\",\n \"split\": 1,\n \"gasless\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://payments.magicblock.app/v1/spl/transfer")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from\": \"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE\",\n \"to\": \"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L\",\n \"mint\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n \"amount\": 1000000,\n \"visibility\": \"private\",\n \"fromBalance\": \"base\",\n \"toBalance\": \"base\",\n \"exactOut\": false,\n \"initIfMissing\": true,\n \"initAtasIfMissing\": true,\n \"initVaultIfMissing\": false,\n \"memo\": \"Order #1042\",\n \"minDelayMs\": \"0\",\n \"maxDelayMs\": \"0\",\n \"clientRefId\": \"42\",\n \"split\": 1,\n \"gasless\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://payments.magicblock.app/v1/spl/transfer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from\": \"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE\",\n \"to\": \"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L\",\n \"mint\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n \"amount\": 1000000,\n \"visibility\": \"private\",\n \"fromBalance\": \"base\",\n \"toBalance\": \"base\",\n \"exactOut\": false,\n \"initIfMissing\": true,\n \"initAtasIfMissing\": true,\n \"initVaultIfMissing\": false,\n \"memo\": \"Order #1042\",\n \"minDelayMs\": \"0\",\n \"maxDelayMs\": \"0\",\n \"clientRefId\": \"42\",\n \"split\": 1,\n \"gasless\": true\n}"
response = http.request(request)
puts response.read_body{
"kind": "transfer",
"version": "legacy",
"transactionBase64": "<string>",
"sendTo": "base",
"recentBlockhash": "<string>",
"lastValidBlockHeight": 123,
"instructionCount": 1,
"requiredSigners": [
"<string>"
],
"from": "base",
"validator": "<string>",
"fees": {
"lamports": "<string>",
"tokens": "<string>"
}
}Core Token API
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
Transfer SPL Tokens
curl --request POST \
--url https://payments.magicblock.app/v1/spl/transfer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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
}
'import requests
url = "https://payments.magicblock.app/v1/spl/transfer"
payload = {
"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
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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
})
};
fetch('https://payments.magicblock.app/v1/spl/transfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://payments.magicblock.app/v1/spl/transfer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://payments.magicblock.app/v1/spl/transfer"
payload := strings.NewReader("{\n \"from\": \"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE\",\n \"to\": \"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L\",\n \"mint\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n \"amount\": 1000000,\n \"visibility\": \"private\",\n \"fromBalance\": \"base\",\n \"toBalance\": \"base\",\n \"exactOut\": false,\n \"initIfMissing\": true,\n \"initAtasIfMissing\": true,\n \"initVaultIfMissing\": false,\n \"memo\": \"Order #1042\",\n \"minDelayMs\": \"0\",\n \"maxDelayMs\": \"0\",\n \"clientRefId\": \"42\",\n \"split\": 1,\n \"gasless\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://payments.magicblock.app/v1/spl/transfer")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from\": \"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE\",\n \"to\": \"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L\",\n \"mint\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n \"amount\": 1000000,\n \"visibility\": \"private\",\n \"fromBalance\": \"base\",\n \"toBalance\": \"base\",\n \"exactOut\": false,\n \"initIfMissing\": true,\n \"initAtasIfMissing\": true,\n \"initVaultIfMissing\": false,\n \"memo\": \"Order #1042\",\n \"minDelayMs\": \"0\",\n \"maxDelayMs\": \"0\",\n \"clientRefId\": \"42\",\n \"split\": 1,\n \"gasless\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://payments.magicblock.app/v1/spl/transfer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from\": \"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE\",\n \"to\": \"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L\",\n \"mint\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\",\n \"amount\": 1000000,\n \"visibility\": \"private\",\n \"fromBalance\": \"base\",\n \"toBalance\": \"base\",\n \"exactOut\": false,\n \"initIfMissing\": true,\n \"initAtasIfMissing\": true,\n \"initVaultIfMissing\": false,\n \"memo\": \"Order #1042\",\n \"minDelayMs\": \"0\",\n \"maxDelayMs\": \"0\",\n \"clientRefId\": \"42\",\n \"split\": 1,\n \"gasless\": true\n}"
response = http.request(request)
puts response.read_body{
"kind": "transfer",
"version": "legacy",
"transactionBase64": "<string>",
"sendTo": "base",
"recentBlockhash": "<string>",
"lastValidBlockHeight": 123,
"instructionCount": 1,
"requiredSigners": [
"<string>"
],
"from": "base",
"validator": "<string>",
"fees": {
"lamports": "<string>",
"tokens": "<string>"
}
}Authorizations
Token obtained from the /v1/spl/login flow.
Body
application/json
Sender wallet pubkey.
Example:
"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"
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.
Example:
"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L"
SPL mint pubkey.
Example:
"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
Base-unit amount as an integer JSON value with minimum 1.
Required range:
x >= 1Example:
1000000
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.
Available options:
mainnet, devnet Example:
"mainnet"
Optional. Defaults to private. Use public for a transparent SPL transfer or private to route through the Private Ephemeral Rollup.
Available options:
public, private 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.
Available options:
base, ephemeral Optional. Defaults to base. Where the recipient should receive the funds.
Available options:
base, ephemeral Optional. When true, treats amount as the exact amount the recipient should receive (relevant when fees are deducted).
Optional. When this transfer route needs a validator and none is provided, the API resolves it from the selected ephemeral RPC via getIdentity.
Example:
"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"
Optional. Initialize the transfer queue if missing.
Optional. Initialize associated token accounts if missing.
Optional. Initialize the vault if missing. Defaults to false.
Optional. Appends a final Memo Program instruction with this UTF-8 message.
Example:
"Order #1042"
Optional. Private transfer only. Defaults to 0. Earliest (ms) the queued transfer may settle.
Pattern:
^\d+$Example:
"0"
Optional. Private transfer only. Defaults to 0 when omitted, or to minDelayMs when only minDelayMs is set. Must be >= minDelayMs.
Pattern:
^\d+$Example:
"0"
Optional. Private transfer only. Encrypted client reference ID that can be used to confirm a payment.
Pattern:
^\d+$Example:
"42"
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.
Required range:
x <= 15Example:
1
Optional. When true, the API uses the configured sponsor as transaction fee payer and prepends a relay-fee token transfer to the sponsor ATA.
Example:
true
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
Unsigned serialized transaction
Available options:
transfer Available options:
legacy, v0 Available options:
base, ephemeral Required range:
x >= 0Mirrors the request fromBalance.
Available options:
base, ephemeral Fees applied to the transfer, in base units.
Show child attributes
Show child attributes
Was this page helpful?