User Onboarding and KYC

Register users for the Onramp

Every end user must complete KYC before buying stablecoins through the Onramp. This page explains the two decisions you need to make: who collects KYC data, and which KYC tier applies.

Who Collects KYC Data?

This is independent of the integration mode you choose (embedded component or headless API). In either case, you decide whether Crossmint collects KYC directly from the user, or you supply data you have already collected.

Approach	Best For	How It Works
Crossmint-Hosted	Teams that want the fastest integration	The user completes KYC inside Crossmint’s secure embedded components. You do not need to handle any KYC data yourself.
You supply KYC data	Platforms that already verify users through their own identity verification (IDV) provider	You pass verified user data to Crossmint via API before creating an order.

KYC Tiers

Crossmint applies three KYC tiers based on cumulative transaction volume, transaction frequency, and risk profile:

Tier	Applies When	Data Required
Progressive KYC	Up to $1,000 in total volume in the last 12 months	Name, date of birth, nationality, country, address, email, and phone number (phone required for US residents). An ID number or SSN is required for US (SSN) and EU/EEA residents; optional elsewhere.
Full KYC	Over $1,000 in total volume in the last 12 months, or a high number of transactions	Progressive KYC data plus dueDiligence, verificationHistory, identity document, and selfie. See the data requirements page.
Enhanced Due Diligence (EDD)	High-risk individuals or regions	Full KYC data plus proof of address and proof of income

How It Works

Crossmint-Hosted

Crossmint handles all KYC data collection and tier transitions. You create the order via API and render the embedded component in your app.

1. Create an Onramp Order and Render the Embedded Component

   Create an order via API and render the Crossmint embedded checkout component in your app. The onramp quickstart walks through both steps.

2. Crossmint Collects KYC Inside the Embedded Component

   The embedded checkout component prompts the user for the required identity data. You do not collect or handle any KYC data yourself.

3. Crossmint Manages Tier Transitions Automatically

   When a user crosses the $1,000 threshold or reaches a high number of transactions, the component automatically prompts them for the additional Full KYC data. If Enhanced Due Diligence (EDD) is required, the component handles that as well. You do not need to build or manage any tier logic.

KYC Data Sharing

You verify users through your own identity verification (IDV) provider and pass the data to Crossmint via API. You are responsible for supplying the correct tier of data.

1. Record User Acceptance of Legal Terms

   Before submitting any user data, you must record the user’s acceptance of Crossmint’s Terms of Service and Privacy Policy. The Identity quickstart walks through this step.

2. Register Progressive KYC Data

   Register the user’s basic identity data via the Create User API.

3. Trigger Identity Verification

   Call the Trigger Identity Verification API to run Crossmint’s compliance checks. Verification runs asynchronously.

4. Check Verification Status

   Poll the Get Identity Verification Status API until the onramp eligibility reads verified. If the status is requires-data, the response includes missingData and missingDocuments arrays that tell you exactly what additional information is needed. Supply it via the Create User API and/or Upload Document API, then re-trigger verification.

5. Create an Onramp Order and Render the Embedded Component

   Create an order via API and render the Crossmint embedded checkout component in your app. The onramp quickstart walks through both steps.

6. Supply Full KYC or EDD Data When Needed

   On order creation, if the user has exceeded the progressive KYC threshold and full KYC data has not been provided, the order returns an error: "Insufficient KYC data provided for this user to perform onramp". Supply the required data via the Upsert User API and/or Upload Document API, then retry order creation. See the data requirements page for the full list of fields.

Tier transitions are not automatic. You must detect when additional data is needed and provide it. The verification status response tells you exactly what is missing.

Onboarding for AI Agents

For AI agent use cases where a human operator has already completed KYC through your platform, you can pre-register the agent operator’s identity data via the API. The agent can then execute onramp transactions without being prompted for KYC in the checkout flow.

See the Agent Wallets Onramp guide for agent-specific integration details.

Guides

Import KYC Data

Identity Quickstart

Data Requirements

Proof of Wallet Ownership