Transfer Tokens

Transfer tokens between wallets using Crossmint’s APIs

Prerequisites

• Wallet: Create a wallet to transfer from.
• Signer: The signing wallet must be registered as a signer on the wallet. You can do this at wallet creation by passing signers, or afterward by adding a signer.
• Test Tokens: Fund your wallet with USDXM testnet tokens before transferring.
• API Key: Get an API key with the wallets:transactions.create scope. In staging, all scopes are included by default.

What is a token transfer?

A token transfer moves a token from one wallet address to another onchain. This creates an onchain transaction that costs gas, which Crossmint handles for you. Once the blockchain confirms the transaction, the transfer is final and cannot be reversed.

Sending tokens

React

import { useWallet } from '@crossmint/client-sdk-react-ui';

const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";
const { wallet } = useWallet();

const { hash, explorerLink } = await wallet.send(RECIPIENT_ADDRESS, "usdxm", "3.14");

See the React SDK reference for more details.

Node.js

import {
    CrossmintWallets,
    createCrossmint,
} from "@crossmint/wallets-sdk";

const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";

const crossmint = createCrossmint({
    apiKey: "YOUR_SERVER_API_KEY",
});

const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.getWallet(
    "WALLET_ADDRESS_OR_ALIAS",
    { chain: "base-sepolia" }
);

await wallet.useSigner({
    type: "server",
    secret: process.env.SIGNER_SECRET!,
});

const { hash, explorerLink } = await wallet.send(
    RECIPIENT_ADDRESS,
    "usdxm",
    "3.14"
);

console.log("Transaction hash:", hash);
console.log("Explorer:", explorerLink);

See the SDK reference for all parameters and return types.

React Native

import { useWallet } from '@crossmint/client-sdk-react-native-ui';

const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";
const { wallet } = useWallet();

const { hash, explorerLink } = await wallet.send(RECIPIENT_ADDRESS, "usdxm", "3.14");

See the React Native SDK reference for more details.

Kotlin

import com.crossmint.kotlin.CrossmintSDK
import com.crossmint.kotlin.types.EVMChain
import com.crossmint.kotlin.types.getOrThrow

CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
val sdk = CrossmintSDK.shared
val wallet = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()

val transaction = wallet.send(
    recipient = "RECIPIENT_WALLET_ADDRESS",
    tokenLocator = "base-sepolia:usdxm",
    amount = 3.14
).getOrThrow()
println("Transaction ID: ${transaction.id}")

Swift

import CrossmintClient
import Wallet

let recipientAddress = "RECIPIENT_WALLET_ADDRESS"
CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
let sdk = CrossmintSDK.shared

guard let wallet = try await sdk.crossmintWallets.getWallet(
    chain: .baseSepolia
) else {
    return
}

let result = try await wallet.send(recipientAddress, "base-sepolia:usdxm", 3.14)

Flutter

import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

const recipientAddress = 'RECIPIENT_WALLET_ADDRESS';
final controller = CrossmintWalletContext.of(context).requireWalletController;
final wallet = controller.createEvmWallet();

final tx = await wallet.sendToken(recipientAddress, 'base-sepolia:usdxm', '3.14');
print('Transaction: ${tx.id}');

See the Flutter SDK reference for more details.

REST

Transfers must be approved by one of the wallet’s signers. The SDK handles this automatically, but with the REST API you may need to craft, sign, and submit the approval manually.

1. Create the transaction

   Call the transfer token endpoint.

   cURL

   curl --request POST \
       --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/tokens/base-sepolia:usdxm/transfers \
       --header 'Content-Type: application/json' \
       --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
       --data '{
           "recipient": "RECIPIENT_WALLET_ADDRESS",
           "amount": "3.14",
           "signer": "external-wallet:YOUR_EXTERNAL_WALLET_ADDRESS"
       }'
   

   See the API reference for more details.

2. Choose your signer type

   The next steps depend on which signer type you specified in the previous step.

   Server Signer

   Server signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

   When using the SDK, signing and approval are handled automatically — no additional steps are needed.

   When using the REST API directly, you must:

   1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the derive-server-signer helper for a reference implementation.
   2. Sign the approval message returned from the transaction creation step.
   3. Submit the signature via the approve transaction endpoint.

   Crossmint recommends using the Wallets SDK for server signer flows. The SDK handles key derivation and signing automatically.

   See the Server Signer guide for full configuration and setup details.

   Device Signer

   Device signers generate a P256 keypair inside the device’s secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are client-side only and cannot be used directly with the REST API.

   Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.

   See the Device Signer guide for setup instructions.

   External Wallet

   For External Wallet signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a message field that must be signed exactly as returned.

   From the previous step’s response, extract:

   • id - The transaction ID (used in the next step)
   • approvals.pending[0].message - The hex message to sign

   Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here’s an example using an EVM wallet with Viem:

   import { privateKeyToAccount } from "viem/accounts";
   
   // The message from tx.approvals.pending[0].message
   const messageToSign = "<messageFromResponse>";
   
   // Sign the message exactly as returned (raw hex)
   const account = privateKeyToAccount(`0x${"<privateKey>"}`);
   const signature = await account.signMessage({
       message: { raw: messageToSign },
   });
   

   Email and Phone

   Email and phone signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

   Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.

   Passkey

   Passkey signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

   Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.

3. Submit the approval

   Skip this step if using the SDK with a server signer — the SDK handles signing and approval automatically.

   Call the approve transaction endpoint with the signature from Step 2 and the transaction ID from Step 1. Set approvals[].signer to the locator of the signer or recovery method that produced the signature.

   cURL

   curl --request POST \
       --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
       --header 'Content-Type: application/json' \
       --header 'X-API-KEY: <x-api-key>' \
       --data '{
           "approvals": [{
               "signer": "external-wallet:<externalWalletAddress>",
               "signature": "<signature>"
           }]
       }'
   

   See the API reference for more details.

4. (Optional) Check transaction status

   You can poll the transaction status to confirm it completed successfully.

   cURL

   curl --request GET \
       --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId> \
       --header 'X-API-KEY: YOUR_SERVER_API_KEY'
   

Complete example

Here’s a complete, copy-pastable example for the external-wallet signer flow using Viem:

import { privateKeyToAccount } from "viem/accounts";

// ============================
// Config (replace placeholders)
// ============================
const API_BASE_URL = "https://staging.crossmint.com";
const API_VERSION = "2025-06-09";

const API_KEY = "YOUR_SERVER_API_KEY";
const WALLET_ADDRESS = "YOUR_WALLET_ADDRESS";
const CHAIN = "base-sepolia";
const TOKEN = "usdxm";

// The externally-owned address that will sign the approval message:
const EXTERNAL_WALLET_ADDRESS = "YOUR_EXTERNAL_WALLET_ADDRESS";

const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";

const AMOUNT = "0.69";

const headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json",
};

// ============================
// STEP 1: Create the transaction
// ============================
const createTransferUrl =
    `${API_BASE_URL}/api/${API_VERSION}` +
    `/wallets/${WALLET_ADDRESS}/tokens/${CHAIN}:${TOKEN}/transfers`;

const createTransferPayload = {
    recipient: RECIPIENT_ADDRESS,
    amount: AMOUNT,
    signer: `external-wallet:${EXTERNAL_WALLET_ADDRESS}`,
};

const createTransferRes = await fetch(createTransferUrl, {
    method: "POST",
    headers,
    body: JSON.stringify(createTransferPayload),
});

if (!createTransferRes.ok) {
    throw new Error(
        `Failed to create transfer: ${createTransferRes.status} ${await createTransferRes.text()}`
    );
}

const tx = await createTransferRes.json();
const txId = tx.id;
const messageToSign = tx?.approvals?.pending?.[0]?.message;

if (!messageToSign) {
    throw new Error(
        "No approval message found. Ensure signer is external-wallet and that an approval is pending."
    );
}

console.log("txId:", txId);
console.log("messageToSign:", messageToSign);

// ============================
// STEP 2: Sign the approval message (Viem)
// ============================
// IMPORTANT: sign the message EXACTLY as returned (a raw hex string).
const account = privateKeyToAccount(`0x${"YOUR_PRIVATE_KEY"}`);

const signature = await account.signMessage({
    message: { raw: messageToSign },
});

console.log("signature:", signature);

// ============================
// STEP 3: Submit the signature
// ============================
const submitApprovalUrl =
    `${API_BASE_URL}/api/${API_VERSION}` +
    `/wallets/${WALLET_ADDRESS}/transactions/${txId}/approvals`;

const submitApprovalPayload = {
    approvals: [
        {
            signer: `external-wallet:${EXTERNAL_WALLET_ADDRESS}`,
            signature,
        },
    ],
};

const submitApprovalRes = await fetch(submitApprovalUrl, {
    method: "POST",
    headers,
    body: JSON.stringify(submitApprovalPayload),
});

if (!submitApprovalRes.ok) {
    throw new Error(
        `Failed to submit approval: ${submitApprovalRes.status} ${await submitApprovalRes.text()}`
    );
}

const approvalResult = await submitApprovalRes.json();
console.log("approvalResult:", approvalResult);

// ============================
// STEP 4 (optional): Check transaction status
// ============================
const getTxUrl =
    `${API_BASE_URL}/api/${API_VERSION}` +
    `/wallets/${WALLET_ADDRESS}/transactions/${txId}`;

const getTxRes = await fetch(getTxUrl, { method: "GET", headers });

if (!getTxRes.ok) {
    throw new Error(
        `Failed to fetch transaction: ${getTxRes.status} ${await getTxRes.text()}`
    );
}

const txStatus = await getTxRes.json();
console.log("txStatus:", txStatus);

See the API reference for all supported locator formats.

Verify your transfer

Once the transfer completes, you can verify it in two ways:

1. View the onchain transaction using the explorerLink returned by the send method:

console.log("View transaction:", explorerLink);
// Example: https://sepolia.basescan.org/tx/0xe5844116732d6cd21127bfc100ba29aee02b82cc4ab51e134d44e719ca8d0b48

2. Check the recipient’s balance programmatically using the check balances API.

Retry Transfers Safely

Add an x-idempotency-key header when you create a transfer from your server. If you retry the request with the same key, Crossmint returns the original transaction instead of creating a second one. The key identifies your request. It is not the transaction ID.

1. Create a key

   Create a new UUID for each transfer and store it with the transfer in your system. Send it with the request.

   cURL

   curl --request POST \
       --url https://staging.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/tokens/base-sepolia:usdxm/transfers \
       --header 'Content-Type: application/json' \
       --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
       --header 'x-idempotency-key: payout-1042' \
       --data '{
           "recipient": "RECIPIENT_ADDRESS",
           "amount": "10"
       }'
   
2. Retry with the same key

   If the request times out or returns a 5xx error, send the same request with the same key. A new key creates a new transfer.

3. Save the transaction ID

   Save the id from the response. Use Get Transaction to check the status of the transfer.

Retry Limitations

• A retry does not restart a transaction. You get the transaction in its current status. A failed transaction stays failed, and an awaiting-approval transaction still needs approval. To try again, use a new key.
• The request body is not compared. If you reuse a key with a different amount or recipient, Crossmint returns the original transaction.
• Keys apply to the whole project and do not expire. A key covers all wallets in the project, on both the Transfer Token and Create Transaction endpoints.
• Responses do not include the key. You cannot look up a transaction by key, so save the transaction id.

On Stellar, a transaction expires if it is not approved before the ledger in onChain.expiration, about 8 minutes after it is created. An expired transaction keeps the awaiting-approval status. If you submit an approval for it, Crossmint returns a 422 error and sets the status to failed.

Next steps

Monitor transfers with webhooks

Track transactions and receive completion notifications

How to check wallet balances

Query token balances across your wallets

Test the Transfer Tokens API

Try out the API in the interactive playground