This page has been updated for Wallets SDK V1. If you are using the previous version,
see the previous version of this page or the V1 migration guide.
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.createscope. 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
- Node.js
- React Native
- Swift
- REST
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");
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);
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");
import CrossmintClient
import Wallet
let recipientAddress = "RECIPIENT_WALLET_ADDRESS"
let sdk = CrossmintSDK.shared
let wallet = try await sdk.crossmintWallets.getWallet(
chain: .baseSepolia
)
let result = try await wallet.send(recipientAddress, "usdxm", 3.14)
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.Call the approve transaction endpoint with the signature from Step 2 and the transaction ID from Step 1.See the API reference for more details.
Create the transaction
Call the transfer token endpoint.See the API reference for more details.
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: YOUR_SERVER_API_KEY' \
--data '{
"recipient": "RECIPIENT_WALLET_ADDRESS",
"amount": "3.14",
"signer": "external-wallet:YOUR_EXTERNAL_WALLET_ADDRESS"
}'
Choose your signer type
The next steps depend on which signer type you specified in the previous step.
- Server Signer
- Device Signer
- External Wallet
- Email & Phone
- Passkey
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:See the Server Signer guide for full configuration and setup details.
- Derive the signing key from your signer secret (scoped to your project, environment, and chain). See the derive-server-signer helper for a reference implementation.
- Sign the approval message returned from the transaction creation step.
- 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.
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.See the Device Signer guide for setup instructions.
Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
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
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 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 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.
Submit the approval
Skip this step if using the SDK with a server signer — the SDK handles signing and approval automatically.
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>"
}]
}'
Complete example
Here’s a complete, copy-pastable example for theexternal-wallet signer flow using :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 = "usdc";
// 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);
Verify your transfer
Once the transfer completes, you can verify it in two ways:- View the onchain transaction using the
explorerLinkreturned by thesendmethod:
console.log("View transaction:", explorerLink);
// Example: https://sepolia.basescan.org/tx/0xe5844116732d6cd21127bfc100ba29aee02b82cc4ab51e134d44e719ca8d0b48
- 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

