Register User Data

Provide personal information about recipients in order to comply with regulation

Register the transfer recipient as a user in your Crossmint project, then attach the recipient data required for payouts. Crossmint uses this data to screen recipients against Office of Foreign Assets Control (OFAC) sanctions lists.

Requirements

• An API key
• A stable user identifier in your system (used as userLocator)
• A Crossmint wallet address for the recipient (or the ability to create one)

Step 1: Accept Crossmint’s Privacy Policy

Before sharing any user KYC data with Crossmint, you must ensure your users have accepted Crossmint’s Privacy Policy. This is a prerequisite for any company sharing their customers’ KYC data with Crossmint.

Requirements for collecting consent

Consent must be obtained following the guidelines below:

1. The user must have the ability to see the terms they must accept
2. The user must grant consent with a checkbox, unchecked by default
3. The user does not need to open the hyperlink to the privacy policy to view the terms
4. The user needs to see Crossmint’s logo in the flow
5. The specific text that you must present to your end user is: “I consent to my KYC data being processed by Crossmint in accordance with its Privacy Policy”
6. The text can be localized but must link to the same privacy policy link provided above
7. If the privacy policy is updated, you must ask the user to agree to the above terms again

Meeting these requirements is mandatory for sharing user KYC data with Crossmint. Only record acceptance through the API below after the user has granted consent this way. Crossmint audits data-sharing integrations for compliance with these requirements.

Once the user has accepted the privacy policy, record their acceptance using the Accept Legal Document endpoint:

cURL

curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/legal-documents' \
    --header 'X-API-KEY: <your-server-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "type": "crossmint-privacy-policy",
        "acceptedAt": "2025-10-05T14:48:00Z"
    }'

const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
    body: JSON.stringify({
        type: "crossmint-privacy-policy",
        acceptedAt: "2025-10-05T14:48:00Z" // ISO 8601 date string
    })
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/legal-documents`, options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

import requests

user_locator = "userId:johnd-123"

url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/legal-documents"

payload = {
    "type": "crossmint-privacy-policy",
    "acceptedAt": "2025-10-05T14:48:00Z"  # ISO 8601 date string
}
headers = {
    "X-API-KEY": "<your-server-api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())

This call also creates a user with the specified userLocator if one does not already exist.

Step 2: Create a User

Register the transfer recipient as a user in your Crossmint project and associate the user with a Crossmint wallet address.

There are two ways to create a user:

Choose a Method

• Use Method 1 if you create the wallet and user in one API call
• Use Method 2 if you register the user first and create the wallet later

Method 1: On Wallet Creation

Create a wallet for a user and associate it to a userLocator by setting the owner property. This method creates in a single API call both the wallet, and the user associated with it.

The owner property accepts a userLocator. This associates the wallet with the user identifier in your system.

Using your own

• If you have your own user IDs, set the wallet's "owner" property using the userId format (userId:<userId>, e.g., userId:johnd-123).
• If you bring your own auth, Crossmint automatically extracts the user ID from your JWT and assigns it to the wallet's "owner" property.

Using Crossmint auth

If you don't have your own user IDs and you use Crossmint auth, you can use any of the following formats:

• email:<email> (e.g., email:[e-mail])
• phoneNumber:<phoneNumber> (e.g., phoneNumber:[phone])
• twitter:<handle> (e.g., twitter:johndoe)
• x:<handle> (e.g., x:johndoe)

REST

const userLocator = "userId:johnd-123";

const options = {
    method: 'POST',
    headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
    body: JSON.stringify({
        chainType: "evm",
        config: {
            adminSigner: {
                type: "email",
                email: "[e-mail]"
            }
        },
        owner: userLocator
    })
};

fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

React

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

const { getOrCreateWallet } = useWallet();

// The "owner" property is inferred by the JWT token, no need to specify it
const wallet = await getOrCreateWallet({
    chain: "evm",
    signer: {
        type: "email",
        email: "[e-mail]"
    }
});

Method 2: Register User First, Create Wallet Later

Register a user with Crossmint without creating a wallet yet. Later, when you create a wallet for that registered user, you can link the wallet’s owner property to that user’s registered userLocator value. This will associate the wallet with the user identifier in your system.

Using your own

• If you have your own user IDs, set the wallet's "owner" property using the userId format (userId:<userId>, e.g., userId:johnd-123).
• If you bring your own auth, Crossmint automatically extracts the user ID from your JWT and assigns it to the wallet's "owner" property.

Using Crossmint auth

If you don't have your own user IDs and you use Crossmint auth, you can use any of the following formats:

• email:<email> (e.g., email:[e-mail])
• phoneNumber:<phoneNumber> (e.g., phoneNumber:[phone])
• twitter:<handle> (e.g., twitter:johndoe)
• x:<handle> (e.g., x:johndoe)

Step 1: Register the user

const userLocator = "userId:johnd-123";

const options = {
    method: 'PUT',
    headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'}
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

Step 2: Create wallet and link to registered user

When you are ready to create a wallet for the registered user, use the same userLocator in the owner field:

REST

const userLocator = "userId:johnd-123";

const options = {
    method: 'POST',
    headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
    body: JSON.stringify({
        chainType: "evm",
        config: {
            adminSigner: {
                type: "email",
                email: "[e-mail]"
            }
        },
        owner: userLocator
    })
};

fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

React

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

const { getOrCreateWallet } = useWallet(); 

// The "owner" property is inferred by the JWT token, no need to specify it
const wallet = await getOrCreateWallet({
    chain: "evm",
    signer: {
        type: "email",
        email: "[e-mail]"
    }
});

Step 3: Register User Data

Use the Create User API to attach userDetails to the user. To see data requirements by activity and region, see Data Requirements. For payouts, the only information needed is userDetails.

REST

const userLocator = "userId:johnd-123";

const options = {
   method: 'PUT',
   headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
   body: JSON.stringify({
       userDetails: {
           firstName: "John",
           lastName: "Doe",
           dateOfBirth: "2007-01-01",
           countryOfResidence: "DE"
       }
   })
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/`, options)
   .then(response => response.json())
   .then(response => console.log(response))
   .catch(err => console.error(err));

Guides

Data Requirements

Quickstart