Skip to main content
The Transfer Token API enables you to trigger regulated transfers from your treasury wallet to user wallets. The API automatically performs compliance checks and will return specific errors if the recipient has not provided the appropriate information or didn’t pass the necessary compliance checks. 
import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

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

const crossmintWallets = CrossmintWallets.from(crossmint);

const treasuryLocator = "<your-treasury-wallet-locator>" 

const treasuryWallet = await crossmintWallets.getWallet(treasuryLocator, {
   chain: "base-sepolia",
   signer: {type: "api-key"},
});

try {
   const { hash, explorerLink } = await treasuryWallet.send(
       "<recipient-wallet-address>",
       "usdc",
       "100"
   );
   
   console.log(`Transfer successful: ${hash}`);
   console.log(`Explorer: ${explorerLink}`);
} catch (error) {
   console.error("Transfer failed:", error.message);
   // Handle compliance errors - see error codes below
}
Wallet locator options for a treasury wallet:
  • <walletAddress> (e.g., 0x1234...5678)
  • chainType[:<walletType>]:alias:<alias> (e.g., evm:smart:alias:treasury)

​
Compliance Errors

If a transfer fails compliance checks, the API will return an error with a specific reason code. Here are the potential compliance-related errors:
Error Message: “Required personal data is missing to complete regulated transfer”Description: The recipient wallet has not provided all personal data required for compliance screening. The recipient must complete their profile with first name, last name, date of birth, and nationality.Resolution: Ensure the recipient has attached their personal data using the user onboarding API.
// Example error response
{
    "error": {
        "reason": "recipient_personal_data_missing",
        "message": "Required personal data is missing to complete regulated transfer"
    }
}
Error Message: “Recipient wallet address is sanctioned and can’t receive assets”Description: The recipient’s wallet address failed Elliptic sanctions screening. This indicates the address has been flagged in sanctions lists or is associated with prohibited activities.Resolution: The transfer cannot proceed. The recipient’s wallet address has been identified as high-risk and is blocked from receiving regulated transfers.
// Example error response
{
    "error": {
        "reason": "recipient_wallet_sanctioned",
        "message": "Recipient wallet address is sanctioned and can't receive assets"
    }
}
Error Message: “Recipient user is sanctioned and can’t receive assets”Description: The recipient’s personal information failed sanctions and PEP (Politically Exposed Person) screening. This indicates the individual is on a sanctions list or is a politically exposed person subject to enhanced due diligence.Resolution: The transfer cannot proceed. The recipient has been identified as high-risk based on their personal information and is blocked from receiving regulated transfers.
// Example error response
{
    "error": {
        "reason": "recipient_person_sanctioned",
        "message": "Recipient user is sanctioned and can't receive assets"
    }
}
Error Message: “Regulated transfers can’t be sent to this wallet. Currently they’re only supported by Crossmint-managed wallets. Contact support for timelines on further wallet support”Description: The destination address is an external wallet, not a Crossmint-managed wallet. Regulated transfers currently only support transfers between Crossmint treasury wallets and Crossmint user wallets.Resolution: Ensure the recipient has a Crossmint wallet. External wallet addresses are not supported for regulated transfers.
External wallet recipients are not currently supported. Contact support for more information.
// Example error response
{
    "error": {
        "reason": "recipient_type_unsupported",
        "message": "Regulated transfers can’t be sent to this wallet. Currently they’re only supported by Crossmint-managed wallets. Contact support for timelines on further wallet support"
    }
}

​
Error Handling Best Practices

When implementing regulated transfers, follow these best practices for error handling:
1

Validate recipient before transfer

Before initiating a transfer, verify that the recipient has completed their onboarding and provided all required personal data. This can help prevent recipient_personal_data_missing errors.
2

Implement retry logic for transient errors

Some errors may be transient (e.g., temporary API issues). Implement appropriate retry logic with exponential backoff for non-compliance errors.
3

Log compliance failures

Log all compliance-related errors for audit purposes. These logs are important for regulatory reporting and investigating failed transfers.
4

Notify users of compliance issues

When a transfer fails due to compliance issues, notify the affected users with clear instructions on how to resolve the issue (e.g., completing their profile, contacting support).

​
Supported Transfer Types

Compliant regulated transfers currently work for transfers between Crossmint treasury wallets and Crossmint user wallets. Transfers to external wallets are not supported.

​
Additional Resources

API Reference

Deep dive into the transfer API reference

Talk to an expert

Contact the Crossmint sales team for support