Making a Payout

Execute compliant payouts and handle compliance errors

The Transfer Token API enables you to trigger payouts 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 did not pass the necessary compliance checks.

You must include "transactionType": "regulated-transfer" in your transfer request to enable compliance checks. Without it, the transfer defaults to direct mode, which skips all compliance screening. See Supported Transfer Types for all options.

cURL

curl --request POST \
    --url 'https://staging.crossmint.com/api/2025-06-09/wallets/<your-treasury-wallet-locator>/tokens/base-sepolia:usdc/transfers' \
    --header 'X-API-KEY: <your-server-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "recipient": "<recipient-wallet-address>",
        "amount": "100",
        "transactionType": "regulated-transfer"
    }'

Signing transactions (REST API): The cURL and Python examples above use the simplified Transfer Token endpoint. If your integration requires custom transaction signing, see the full create → sign → approve flow in Send a Transaction (EVM) — REST tab.

Wallet locator options for a treasury wallet:

• <walletAddress> (e.g., 0x1234...5678)
• chainType[:<walletType>]:alias:<alias> (e.g., evm:smart:alias:treasury)

Transfers are irreversible once executed. Clients must ensure that all transaction details are correct before submitting a transfer request.

Compliance Errors

If a payout fails compliance checks, the API returns an error response with a top-level error flag and a human-readable message. No machine-readable reason code is returned, so display or log the message rather than matching on its text in your code. The possible failures are:

Recipient personal data is missing

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 country of residence.

Resolution: Ensure the recipient has attached their personal data using the user onboarding API.

Show How to test

In staging, send a transfer to any user wallet that has not had personal data registered.

// Example error response
{
    "error": true,
    "message": "Required personal data is missing to complete regulated transfer"
}

Recipient wallet failed risk screening

Error Message: “Recipient wallet was marked as unsafe. It can’t receive assets.”

Description: The recipient’s wallet address was marked as unsafe by Crossmint’s wallet screening. This is returned for any blocking screening outcome, not only sanctions matches: a high-risk result from the screening provider (TRM Labs), an active transaction-monitoring alert on the address, or a manual block set by Crossmint. The message is the same for every cause.

Resolution: The payout cannot proceed. The recipient’s wallet address is blocked from receiving payouts.

Show How to test

In staging, you can trigger this error by using the following special addresses across different chains as the recipient:

• EVM: 0xc9b888e8f2c9c60f72f84e97e4416c3aca3e1f7c
• Solana: 7H7Dph61J9W9WzvRUQbM1tsPJpEQhaQ3GVxPSj1EnSuw
• Stellar: G5CLUPQPRWQXKHASBYSYMIPHE2ZMIFLMEH3ROBTOQMR24YWQIFQW2RY5

// Example error response
{
    "error": true,
    "message": "Recipient wallet was marked as unsafe. It can't receive assets."
}

Recipient failed identity verification

Error Message: “User does not meet the verification requirements to proceed. Check the user’s verification status via GET /users/{userLocator}/identity-verification.”

Description: The recipient did not pass the verification checks required to proceed. This is returned for any blocking KYC outcome, including sanctions/PEP screening matches, watchlist hits, banned users, restricted geographies, or failed full/light KYC.

Resolution: The payout cannot proceed. Inspect the recipient’s verification status via GET /users/{userLocator}/identity-verification to determine the specific reason and any next steps.

Show How to test

In staging, if you create a user profile with the name “Sanctioned User Name”, Crossmint will consider them sanctioned. You can use this for testing.

To trigger this error, create a user with the following data:

{
    "personalData": {
        "firstName": "Sanctioned User Name",
        // ... any value for other required fields
    }
}

Then attempt a payout to that user’s wallet.

// Example error response
{
    "error": true,
    "message": "User does not meet the verification requirements to proceed. Check the user's verification status via GET /users/{userLocator}/identity-verification."
}

Recipient wallet type is not supported

Error Message: “Regulated transfers can only be sent to Crossmint-managed wallets or external wallets linked to a Crossmint user.”

Description: The destination address is not a Crossmint-managed wallet and is not linked to a Crossmint user. Payouts support transfers to Crossmint user wallets and to external wallets that a Crossmint user has linked to their account.

Resolution: Ensure the recipient has a Crossmint wallet, or link the external wallet address to the recipient’s Crossmint user with the Link External Wallet API before initiating the payout. After linking, the recipient may also need to prove ownership by signing the verification challenge (see the unverified wallet ownership entry below):

curl --request PUT \
    --url https://staging.crossmint.com/api/2025-06-09/users/YOUR_USER_LOCATOR/linked-wallets/YOUR_WALLET_ADDRESS \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
        "chain": "base-sepolia"
    }'

// Example error response
{
    "error": true,
    "message": "Regulated transfers can only be sent to Crossmint-managed wallets or external wallets linked to a Crossmint user."
}

Recipient wallet ownership is not verified

Error Message: “Recipient external wallet ownership has not been verified. The recipient must sign the wallet ownership challenge before receiving regulated transfers.”

Description: The destination address is an external wallet linked to a Crossmint user, but the user has not proven ownership of the wallet by signing the ownership verification challenge.

Resolution: Have the recipient sign the verificationChallenge returned when the wallet was linked (or retrieve it anytime via the Get Linked Wallet endpoint), then submit the signature as proof using the same Link External Wallet API:

curl --request PUT \
    --url https://staging.crossmint.com/api/2025-06-09/users/YOUR_USER_LOCATOR/linked-wallets/YOUR_WALLET_ADDRESS \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
        "chain": "base-sepolia",
        "proof": "YOUR_SIGNATURE"
    }'

Once the response shows "ownership": { "verified": true }, retry the payout. The verification flow is the same one used for onramp — see Onramp to Non-Crossmint Wallets for how all wallets, including externally owned accounts (EOAs) and smart contract wallets, use the same flow.

// Example error response
{
    "error": true,
    "message": "Recipient external wallet ownership has not been verified. The recipient must sign the wallet ownership challenge before receiving regulated transfers."
}

Error Handling Best Practices

When implementing payouts, follow these best practices for error handling:

1. Validate recipient before transfer

   Before initiating a payout, verify that the recipient has completed their onboarding and provided all required personal data. This can help prevent the missing personal data error.

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

When calling the Transfer Token API, you must specify the transactionType field to indicate whether the transfer requires compliance checks:

Type	Description
regulated-transfer	The transaction is routed through Crossmint’s regulated infrastructure. This enables compliance with regulatory requirements and performs AML screening, sanctions checks, and travel rule validation. Required for payouts to customers.
onramp	The transaction is routed through Crossmint’s regulated infrastructure, similar to regulated-transfer. Used for fiat-to-crypto onramp flows that require compliance checks.
direct	Standard transfer with no compliance checks. Used for internal treasury-to-treasury transfers. This is the default if transactionType is omitted.

Omitting the transactionType field defaults to direct, which skips all compliance checks. Always set transactionType to regulated-transfer (or onramp for fiat-to-crypto flows) when sending payouts to customer wallets.

Compliant payouts work for transfers from Crossmint treasury wallets to Crossmint user wallets and to external wallets linked to a Crossmint user with verified ownership. Payouts to unlinked 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