Skip to main content
In this quickstart you will learn how to create wallets, check balances, and transfer tokens from your backend using the Crossmint Wallets API.

Before you start

Set up your project and get an API key.

Wallets Quickstart

See a full working example.

​
Understanding Wallet Types

Crossmint supports two types of wallets:
  • Smart Wallets: Account abstraction wallets with configurable signers. You control who can sign transactions (external wallets, API keys, passkeys, etc.).
  • MPC Wallets: Custodial wallets where Crossmint manages the private keys using multi-party computation. Simpler setup with no signer configuration needed.
1

Create a wallet

Smart wallets on EVM chains (Base, Polygon, Ethereum, etc.) with configurable signers.
curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <x-api-key>' \
    --data '{
        "chainType": "evm",
        "type": "smart",
        "config": {
            "adminSigner": {
                "type": "external-wallet",
                "address": "<your-wallet-address>"
            }
        },
        "owner": "email:user@example.com"
    }'
Key Parameters:
  • chainType: The blockchain family (evm for Ethereum-compatible chains)
  • type: Wallet type (smart for smart wallets)
  • config.adminSigner: The primary signer for the wallet
    • type: "external-wallet": Use an external wallet address you control
    • type: "api-key": Let Crossmint manage signing via API
  • owner: User identifier in format email:user@example.com (optional but recommended)
{
    "chainType": "evm",
    "type": "smart",
    "address": "0xABC1234567890DEF1234567890ABCDEF12345678",
    "owner": "email:user@example.com",
    "config": {
        "adminSigner": {
            "type": "external-wallet",
            "address": "<your-wallet-address>",
            "locator": "external-wallet:<your-wallet-address>"
        }
    },
    "createdAt": "2025-12-15T10:30:00.000Z"
}
Save the address field - you’ll need it to interact with this wallet.
See the API reference for all available parameters.
2

Retrieve a wallet

Retrieve wallet information using a . This is useful when you need to get wallet details without storing the wallet address.Wallet Locator Formats:
  • By address: 0xABC... or GbA2NZ...
  • By email: email:user@example.com:evm:smart
  • By user ID: userId:507f1f77bcf86cd799439011:solana:mpc
curl --request GET \
    --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm:smart \
    --header 'X-API-KEY: <x-api-key>'

{
    "chainType": "evm",
    "type": "smart",
    "address": "0xABC1234567890DEF1234567890ABCDEF12345678",
    "owner": "email:user@example.com",
    "config": {
        "adminSigner": {
            "type": "external-wallet",
            "address": "<your-wallet-address>",
            "locator": "external-wallet:<your-wallet-address>"
        }
    },
    "createdAt": "2025-12-15T10:30:00.000Z"
}
  • 0x1234567890123456789012345678901234567890 - Direct address
  • email:user@example.com:evm:smart - Email + wallet type
  • userId:507f1f77bcf86cd799439011:solana:mpc - User ID + wallet type
  • phoneNumber:+12125551234:evm:smart - Phone + wallet type
  • twitter:johndoe:evm:smart or x:@johndoe:evm:smart - Twitter/X + wallet type
  • me:evm:smart - Authenticated user (client-side only)
3

Check wallet balance

Check token balances for a wallet. You can query multiple tokens at once by providing a comma-separated list.
curl --request GET \
    --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc,eth' \
    --header 'X-API-KEY: <x-api-key>'
Query Parameters:
  • tokens (required): Comma-separated list of token symbols (e.g., usdc,eth,usdxm)
  • chains (optional): Filter by specific chains when using multi-chain wallets
{
    "nativeToken": {
        "symbol": "ETH",
        "decimals": 18,
        "balance": "1500000000000000000",
        "balanceUSD": "4500.00"
    },
    "tokens": [
        {
            "symbol": "USDC",
            "decimals": 6,
            "balance": "1000000000",
            "balanceUSD": "1000.00",
            "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        }
    ]
}
Balances are returned as strings in the token’s smallest unit (wei for ETH, lamports for SOL, etc.).
4

Transfer tokens

Send tokens from a wallet to a recipient. Smart wallets handle gas fees automatically through Crossmint’s paymaster.Token Locator Format: {chain}:{symbol} or {chain}:{contractAddress} (e.g., base-sepolia:eth, polygon:usdc, base-sepolia:0x123...)
curl --request POST \
    --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/tokens/base-sepolia:eth/transfers' \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <x-api-key>' \
    --data '{
        "recipient": "<recipient-wallet-address>",
        "amount": "0.001"
    }'
Request Parameters:
  • recipient (required): Destination address or AddressLocator. Supports wallet addresses (0x...) or identity-based locators like email:user@example.com, phoneNumber:+12125551234, userId:abc123
  • amount (required): Amount to transfer in decimal format (e.g., "0.001" for 0.001 ETH)
  • signer (optional): Signer locator if using delegated signers (defaults to admin signer)
{
    "id": "cm47h2m8e0003vn0zf8yz1234",
    "chainType": "evm",
    "walletType": "smart",
    "status": "pending",
    "params": {
        "calls": [...],
        "chain": "base-sepolia",
        "signer": {
            "type": "evm-keypair",
            "address": "0x..."
        }
    },
    "onChain": {
        "userOperationHash": "0x...",
        "txId": null
    },
    "sendParams": {
        "token": "base-sepolia:eth",
        "recipient": "<recipient-wallet-address>",
        "amount": "0.001"
    },
    "createdAt": "2025-12-15T10:35:00.000Z"
}
Transaction Status Values:
  • awaiting-approval - Transaction created, waiting for signer approval
  • pending - Transaction submitted to the blockchain
  • success - Transaction confirmed onchain
  • failed - Transaction failed
Poll the transaction status using the transaction ID, or set up webhooks for real-time updates.
EVM Chains:
  • base-sepolia:eth - ETH on Base Sepolia testnet
  • base-sepolia:usdc - USDC on Base Sepolia
  • polygon:usdc - USDC on Polygon mainnet
  • ethereum:usdt - USDT on Ethereum mainnet
Solana:
  • solana:sol - Native SOL token
  • solana:usdc - USDC on Solana
For contract tokens, use the contract address: base-sepolia:0x123...

​
Using Idempotency Keys

Prevent duplicate wallet creation by using idempotency keys: 
curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <x-api-key>' \
    --header 'x-idempotency-key: unique-operation-id-123' \
    --data '{
        "chainType": "evm",
        "type": "mpc",
        "owner": "email:user@example.com"
    }'
If you retry with the same idempotency key, you’ll receive the same wallet without creating a duplicate.

​
Launching in Production

Ready to go live? Here’s what you need to do:
  1. Create a production account at www.crossmint.com/console
  2. Create a production API key with the required scopes:
    • wallets.create, wallets.read, wallets:balance.read, wallets:transactions.create
  3. Update your API endpoint from staging.crossmint.com to www.crossmint.com
  4. Update your API key in your code to use the production key
Never expose your server-side API keys in client-side code or public repositories. Store them securely in environment variables or a secrets manager.

​
Learn More

Check Balances

Check the balance of a wallet.

Transfer Tokens

Send tokens between wallets.

Delegated Signers

Add delegated signers to a wallet.