A Next.js application demonstrating the integration of Coinbase's On-ramp and Off-ramp services, allowing users to easily convert between fiat and cryptocurrency.
- Coinbase Onramp Integration: Allows users to purchase crypto with fiat currency
- Coinbase Offramp Integration: Enables users to convert crypto back to fiat
- Wallet Connection: Integrates with Web3 wallets via WalletConnect
- Responsive Design: Modern UI that works across devices
- Multiple Integration Options:
- Fund Card: Pre-built UI component from Coinbase
- Custom Integration: Fully customizable UI with enhanced dropdown options
- Node.js 18+ and npm
-
Clone the repository
git clone https://github.com/coinbase/onramp-demo-application.git cd onramp-demo-application -
Install dependencies
npm install
-
Set up environment variables:
Copy the
.env.examplefile to.env.local:cp .env.example .env.local
-
Obtain the necessary API keys:
- Onchain Kit API Key: Get this from the Coinbase Developer Platform Dashboard
- CDP Project ID: Get this from the Coinbase Developer Platform Dashboard
- CDP API Keys: Get these from the Coinbase Developer Platform Dashboard
- Iron Password: Create a secure password (at least 32 characters) for session encryption
-
Add your API keys to the
.env.localfile:# Client-side variables (accessible in browser) NEXT_PUBLIC_ONCHAINKIT_API_KEY="your_onchainkit_api_key" NEXT_PUBLIC_CDP_PROJECT_ID="your_cdp_project_id" # Server-side variables (not accessible in browser) IRON_PASSWORD="your_secure_password_at_least_32_chars_long" CDP_API_KEY_NAME="your_cdp_api_key_name" CDP_API_KEY_PRIVATE_KEY="your_cdp_api_private_key" CDP_PROJECT_ID="your_cdp_project_id" ONCHAINKIT_API_KEY="your_onchainkit_api_key"IMPORTANT: Never commit your API keys to the repository. The
.env.localfile is included in.gitignoreto prevent accidental exposure. -
Start the development server
npm run dev
-
Open http://localhost:3000 in your browser
The Fund Card provides a pre-built UI component from Coinbase that handles the entire on-ramp process with minimal configuration.
If you're experiencing issues with the FundCard component:
-
400 Bad Request Error:
- Ensure your CDP Project ID is correctly set in the
.env.localfile as bothNEXT_PUBLIC_CDP_PROJECT_IDandCDP_PROJECT_ID - Verify that your OnchainKit API Key is valid and active
- Check that your wallet is connected to the correct network (Base is recommended)
- Look for detailed error messages in the browser console
- Ensure your CDP Project ID is correctly set in the
-
Wallet Connection Issues:
- Make sure your WalletConnect Project ID is correctly set
- Try disconnecting and reconnecting your wallet
- Ensure you're using a compatible wallet (Coinbase Wallet is recommended)
-
Testing with Simplified Components:
- Visit
/basic-fundto test a minimal FundCard implementation - Visit
/simple-fundto test a FundCard with CDP Project ID handling
- Visit
-
Environment Variable Verification:
- Both client-side (
NEXT_PUBLIC_*) and server-side variables must be set - The CDP Project ID must be set as both
NEXT_PUBLIC_CDP_PROJECT_ID(client-side) andCDP_PROJECT_ID(server-side) - The API route at
/api/authmust return a valid CDP Project ID - Make sure your OnchainKit API Key is set as both
NEXT_PUBLIC_ONCHAINKIT_API_KEY(client-side) andONCHAINKIT_API_KEY(server-side)
- Both client-side (
The Custom Integration demo showcases a fully customizable UI that gives you complete control over the user experience. Recent enhancements include:
- Expanded Currency Options: Support for USD, EUR, GBP, CAD, AUD, JPY, CHF, SGD
- Multiple Cryptocurrency Assets: USDC, ETH, BTC, SOL, MATIC, AVAX, LINK, UNI, AAVE, DAI
- Diverse Network Support: Base, Ethereum, Optimism, Arbitrum, Polygon, Avalanche, Solana, BNB Chain
- Comprehensive Payment Methods: Card, Bank, Apple Pay, Google Pay, PayPal, Coinbase, ACH, SEPA, iDEAL, SOFORT
- Global Coverage: Support for multiple countries including US, UK, Canada, Australia, Germany, France, Spain, Italy, Netherlands, Switzerland, Singapore, Japan
- Next.js 14
- React
- TypeScript
- Tailwind CSS
- @coinbase/onchainkit
- wagmi
This project can be easily deployed on Vercel:
When deploying, make sure to set up the environment variables in your Vercel project settings.
This repository is maintained by Coinbase and serves as a demonstration of how to integrate Coinbase's On/Off Ramp services into your application. For more information about Coinbase Developer Platform, visit Coinbase Developer Platform.
Contributions to this demo application are welcome. Please feel free to submit issues or pull requests to improve the demonstration.
- Enhanced Custom Integration: Added comprehensive dropdown options for countries, currencies, payment methods, and networks
- Improved Type Safety: Fixed TypeScript type issues for better reliability
- UI Enhancements: Updated styling for better user experience
-
API Key Issues:
- Ensure all API keys are correctly set in your
.env.localfile - Verify that your API keys are active and have the correct permissions
- Make sure your CDP_PROJECT_ID and NEXT_PUBLIC_CDP_PROJECT_ID are correctly set and match
- Check for any whitespace or quotes that might be causing issues
- Ensure all API keys are correctly set in your
-
Wallet Connection Problems:
- Try disconnecting and reconnecting your wallet
- Ensure you're using a compatible wallet (Coinbase Wallet is recommended)
- Check that you're connected to the correct network
-
Build or Runtime Errors:
- Make sure you're using Node.js 18 or higher
- Try clearing your browser cache or using incognito mode
- Run
npm installagain to ensure all dependencies are properly installed
If you encounter any other issues, please check the Issues section of the repository or create a new issue.
MIT