Skip to main content
The Transfers 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.

​
Executing a Transfer

To execute a regulated transfer, use the standard wallet transfer API. Compliance checks are performed automatically:
  • Node.js
  • REST
import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

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

const crossmintWallets = CrossmintWallets.from(crossmint);

const treasuryWallet = await crossmintWallets.getWallet({
    chain: "solana",
    alias: "treasury",
});

try {
    const { hash, explorerLink } = await treasuryWallet.send(
        "recipient-wallet-address",
        "solana:usdc",
        "100.00"
    );
    
    console.log(`Transfer successful: ${hash}`);
    console.log(`Explorer: ${explorerLink}`);
} catch (error) {
    console.error("Transfer failed:", error.message);
    // Handle compliance errors - see error codes below
}
walletLocator format options for treasury wallet:
  • <walletAddress> (e.g., 0x1234...5678)
  • chainType[:<walletType>]:alias:<alias> (e.g., solana:mainnet:alias:treasury or evm: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”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 country code.Resolution: Ensure the recipient has attached their personal data using the user onboarding API.
// Example error response
{
    "error": {
        "reason": "personal_data_missing",
        "message": "Required personal data is missing"
    }
}
Error Message: “Recipient address did not pass sanction tests”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": "address_sanction_check_failed",
        "message": "Recipient address did not pass sanction tests"
    }
}
Error Message: “Recipient user did not pass sanction tests”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": "user_sanction_check_failed",
        "message": "Recipient user did not pass sanction tests"
    }
}
Error Message: “Recipient address is not a Crossmint wallet”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.
// Example error response
{
    "error": {
        "reason": "not_support_recipient_type",
        "message": "Recipient address is not a Crossmint wallet"
    }
}

​
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 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