Proof of Ownership

Proof of ownership confirms that an onramp user controls the wallet receiving their assets. It helps Crossmint meet anti-money laundering (AML) and counter-terrorism financing (CTF) requirements by linking the user’s verified identity to the recipient wallet.

When Is Proof of Ownership Required?

Proof of ownership is triggered based on transaction volume thresholds:

Condition	Verification Required?
Transaction below $1,000 AND 30-day volume below $1,000	No
Transaction above $1,000 OR 30-day volume above $1,000	Yes

These thresholds apply to users verified outside the United States who onramp to external wallets. A Crossmint-managed wallet does not require additional verification when its owner is the user; a wallet without an owner or owned by someone else is treated as external. To link the user’s identity to an external wallet, Crossmint asks the user to sign a challenge with the recipient wallet and submit the signature in the proof field. This flow works the same across chains and for all wallet types, including externally owned accounts (EOAs) and smart contract wallets.

How It Works

Link External Wallet

Before creating an onramp order to an external wallet, link the wallet to a Crossmint user (created automatically if one does not yet exist for the locator) using the 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"
    }'

The API responds with a verification challenge in the CAIP-122 format. The standard defines the challenge message and does not limit which wallets can complete verification:

{
    "address": "0x1234...5678",
    "chain": "base-sepolia",
    "type": "external-wallet",
    "ownership": {
        "verified": false,
        "verificationChallenge": "crossmint.com wants you to sign in with your blockchain account:\n0x1234...5678\n\n..."
    }
}

Create Order

Create the onramp order as usual. If verification is required, the order response will have status requires-recipient-verification:

{
    "order": {
        "payment": {
            "status": "requires-recipient-verification",
            "preparation": {
                "message": "crossmint.com wants you to sign in with your blockchain account:\n0x1234...5678\n\n..."
            }
        }
    }
}

Sign the Message

Have the user sign the preparation.message with the recipient wallet:

import { Wallet } from "ethers";

const wallet = new Wallet("YOUR_PRIVATE_KEY");
const message = order.payment.preparation.message;
const signature = await wallet.signMessage(message);

import nacl from "tweetnacl";
import { decodeUTF8 } from "tweetnacl-util";
import { encode as base64Encode } from "@stablelib/base64";

const YOUR_SECRET_KEY_BYTES = new Uint8Array(64); // Replace with your actual secret key bytes
const keypair = nacl.sign.keyPair.fromSecretKey(YOUR_SECRET_KEY_BYTES);

const message = order.payment.preparation.message;
const messageBytes = decodeUTF8(message);
const signatureBytes = nacl.sign.detached(messageBytes, keypair.secretKey);
const signature = base64Encode(signatureBytes);

Submit Signature

Submit the signature as proof of ownership 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 verified, the response confirms ownership:

{
    "address": "0x1234...5678",
    "chain": "base-sepolia",
    "type": "external-wallet",
    "ownership": {
        "verified": true
    }
}

Complete Order

After ownership is verified, fetch the order using the Get Order API. The status will advance to:

requires-kyc — the user has not completed KYC yet.
awaiting-payment — the user can proceed to payment.

Pre-Verifying Ownership

You can verify wallet ownership at the time of linking (before any order is created) by including the proof field in the initial Link External Wallet call. This avoids requiring verification during the checkout flow.

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"
    }'

Onramp to Non-Crossmint Wallets — full guide for non-Crossmint wallet onramp integration
React Quickstart (External Wallets tab) — quickstart with external wallet support

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

When Is Proof of Ownership Required?

How It Works

Pre-Verifying Ownership

​When Is Proof of Ownership Required?

​How It Works

​Pre-Verifying Ownership

​Related Resources

When Is Proof of Ownership Required?

How It Works

Pre-Verifying Ownership

Related Resources