Transfer Tokens

Transfer tokens between wallets using Crossmint’s APIs

Prerequisites

• Wallet: Create a wallet to transfer from.
• 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 on-chain. This creates an on-chain 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 { wallet } = useWallet();

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

Node.js

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

const crossmint = createCrossmint({
    apiKey: "<your-server-api-key>",
});

const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.getWallet(
    "email:[e-mail]:evm",
    { chain: "base-sepolia", signer: { type: "email" } }
);

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

React Native

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

const { wallet } = useWallet();

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

Swift

import CrossmintClient
import Wallet

let sdk = CrossmintSDK.shared

let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
    chain: .baseSepolia,
    signer: .email("[e-mail]")
)

let result = try await wallet.send("0x0D282906CDD8F6934d60E4dCAa79fa5B1c7a1925", "usdxm", 3.14)

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:usdc/transfers \
       --header 'Content-Type: application/json' \
       --header 'X-API-KEY: <x-api-key>' \
       --data '{
           "recipient": "<recipientAddress>",
           "amount": "3.14",
           "signer": "external-wallet:<externalWalletAddress>"
       }'
   

   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.

   API Key

   API Key signers require no additional steps. Crossmint approves transactions automatically when using API key authentication, so the remaining steps in this guide do not apply.

   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 & Phone

   Email, phone number, and social login signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, Crossmint does not recommend it because you would 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 an api-key signer.

   Call the approve transaction endpoint with the signature from Step 2 and the transaction ID from Step 1.

   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: <x-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 = "<x-api-key>";
const WALLET_ADDRESS = "<walletAddress>";
const CHAIN = "base-sepolia";
const TOKEN = "usdc";

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

const RECIPIENT_ADDRESS = "<recipientAddress>";

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${"<privateKey>"}`);

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 on-chain 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.

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