Skip to main content

Introduction

Once a user wallet is created and the agent is authorized, the next step is to fund the wallet so the agent has stablecoins to spend. The onramp flow lets users buy USDC with a credit card and deliver it directly to their Crossmint wallet. Onramp is a UI flow, not a headless API. Card authorization, 3DS challenges, and KYC checks all require the user to interact with a Crossmint-hosted component, the same way Apple Pay or Stripe Elements work. Raw card data and PII never reach your servers. In this guide, you’ll learn how to:
  • Create a Crossmint order using a server action
  • Use Crossmint’s embedded checkout component to handle KYC, payment, and delivery automatically
You can start testing Onramp in staging. Once you are ready to go live, reach out to sales to enable the feature in production

Prerequisites

1

Install the SDK

Install the Crossmint client SDK:
2

Create API keys

Create a server-side API key with the orders.create and orders.read scopes enabled.Create a client-side API key for the embedded checkout component.In staging, all scopes are enabled by default.
3

Create a user wallet

Make sure the user has a Crossmint wallet. See Create a User Wallet if you have not done this yet.
4

Add environment variables

Add environment variables to your .env.local:
.env.local

Steps

1

Create the server action

Create a server action that creates onramp orders via the Crossmint API. The recipient is the user’s wallet address — funds are delivered straight to the wallet your agent is authorized on.
app/actions/createOrder.ts
2

Build the onramp component

Create a client component that pulls the user’s wallet from useWallet(), creates an order, and renders the embedded checkout. Because the agent is already authorized on the wallet, any USDC delivered here is immediately spendable by the agent.
app/components/OnrampCheckout.tsx
The embedded checkout already runs inside the CrossmintProvider you set up to create the user’s wallet, so no extra provider is needed here.
3

Add the component to your page

Drop OnrampCheckout into the page where the user funds their wallet — for example, right after authorizing the agent.
app/page.tsx
When the user clicks Continue to Checkout, the server action creates an order and the embedded checkout component handles KYC, payment, and delivery automatically. As soon as USDC lands in the wallet, the agent can spend it.
Testing: Use the test credit card number 4242 4242 4242 4242 with any future expiration date and any 3-digit CVC.

Common Gotchas

The recipient of the order is always the user’s wallet address. The agent does not have its own balance — it spends from the user’s wallet using its delegated server signer.
The token locators above target Base Sepolia, Solana Devnet, and Stellar Testnet. Switch to mainnet locators only after end-to-end staging tests pass.
Card collection, 3DS, and KYC must be completed by the user in the embedded checkout. An agent cannot complete onramp on behalf of the user.

What Is Next

On-Chain Actions

Once funded, send stablecoins and call contracts from your agent.

Save a Card

Set up the card that will fund the wallet.