{"id":18542717,"url":"https://github.com/coinbase/onramp-demo-application","last_synced_at":"2026-04-10T03:02:01.778Z","repository":{"id":259112882,"uuid":"873352110","full_name":"coinbase/onramp-demo-application","owner":"coinbase","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-20T18:17:31.000Z","size":1790,"stargazers_count":43,"open_issues_count":2,"forks_count":48,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T08:09:55.895Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://onramp-demo-application.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coinbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-16T02:50:05.000Z","updated_at":"2025-03-23T21:38:40.000Z","dependencies_parsed_at":"2024-12-26T05:23:41.927Z","dependency_job_id":"bec723ff-57ca-4b43-9f0c-0cee09cb43e0","html_url":"https://github.com/coinbase/onramp-demo-application","commit_stats":null,"previous_names":["coinbase/onramp-demo-application"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fonramp-demo-application","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fonramp-demo-application/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fonramp-demo-application/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fonramp-demo-application/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coinbase","download_url":"https://codeload.github.com/coinbase/onramp-demo-application/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018060,"owners_count":21034048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T20:09:53.887Z","updated_at":"2026-04-10T03:02:01.772Z","avatar_url":"https://github.com/coinbase.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Coinbase On/Off Ramp Demo\n\nA Next.js application demonstrating the integration of Coinbase's On-ramp and Off-ramp services, allowing users to easily convert between fiat and cryptocurrency.\n\n## Features\n\n- **Coinbase Onramp Integration**: Allows users to purchase crypto with fiat currency\n- **Coinbase Offramp Integration**: Enables users to convert crypto back to fiat\n  - ⚠️ **Important**: Offramp requires a Coinbase account with linked bank details. Guest checkout is NOT supported for fiat withdrawals.\n- **Apple Pay Onramp**: Fast, native Apple Pay integration with iframe embedding\n- **Secure Initialization**: Support for session tokens for enhanced security\n- **Wallet Connection**: Integrates with Web3 wallets via WalletConnect\n- **Responsive Design**: Modern UI that works across devices\n- **Multiple Integration Options**:\n  - **Fund Card**: Pre-built UI component from Coinbase\n  - **Custom Integration**: Fully customizable UI with enhanced dropdown options\n  - **Apple Pay**: Native Apple Pay experience with embedded iframe\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+ and npm\n\n### Installation\n\n1. Clone the repository\n\n   ```bash\n   git clone https://github.com/coinbase/onramp-demo-application.git\n   cd onramp-demo-application\n   ```\n\n2. Install dependencies\n\n   ```bash\n   npm install\n   ```\n\n3. Set up environment variables:\n\n   Copy the `.env.example` file to `.env.local`:\n\n   ```bash\n   cp .env.example .env.local\n   ```\n\n4. Obtain the necessary API keys from the [Coinbase Developer Platform Dashboard](https://portal.cdp.coinbase.com/):\n\n   - **CDP Project ID**: Your public project identifier (found in Projects dashboard)\n   - **CDP Secret API Key**: Create from API Keys \u003e Secret API Keys (select Ed25519 format)\n   - **CDP API Private Key**: The base64-encoded private key from the API key creation\n\n5. Add your API keys to the `.env.local` file:\n\n   ```bash\n   # ==============================================\n   # PUBLIC ENVIRONMENT VARIABLES (safe to expose)\n   # ==============================================\n\n   # CDP Project ID - This is your public project identifier\n   # Get from: https://portal.cdp.coinbase.com/\n   NEXT_PUBLIC_CDP_PROJECT_ID=\"your_project_id_here\"\n\n   # Project Name (optional)\n   NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME=\"Coinbase Ramp Demo\"\n\n   # ==============================================\n   # PRIVATE ENVIRONMENT VARIABLES (server-side only)\n   # ==============================================\n\n   # CDP Secret API Key Name/ID\n   # Get from: https://portal.cdp.coinbase.com/access/api\n   # When creating the key, select \"Ed25519\" as the signature algorithm (recommended)\n   # Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n   CDP_API_KEY=\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n\n   # CDP API Private Key (Ed25519 format - recommended)\n   # Copy the base64-encoded key from CDP Portal\n   # Format: A long base64 string ending with \"==\"\n   CDP_API_SECRET=\"your-base64-encoded-ed25519-private-key-here==\"\n\n   # ==============================================\n   # OPTIONAL\n   # ==============================================\n\n   # CORS Origins - Comma-separated list of allowed origins\n   # Add your production domain(s) here for Apple Pay and custom integrations\n   ALLOWED_ORIGINS=\"http://localhost:3000,http://localhost:3001,https://yourdomain.com\"\n\n   # Node environment\n   NODE_ENV=development\n   ```\n\n   \u003e **IMPORTANT**: Never commit your API keys to the repository. The `.env.local` file is included in `.gitignore` to prevent accidental exposure.\n\n6. Start the development server\n\n   ```bash\n   npm run dev\n   ```\n\n7. Open [http://localhost:3000](http://localhost:3000) in your browser\n\n## Security Requirements (Coinbase CDP)\n\nThis demo implements **required security measures** as specified by Coinbase Developer Platform:\n\n### CORS Protection (Required)\n\nAll session token API endpoints implement CORS headers to prevent unauthorized access:\n\n- ✅ Only allows requests from approved origins\n- ✅ Rejects requests from unauthorized domains  \n- ✅ Prevents malicious websites from hijacking your API\n\n**Configuration:**\n\nThe API endpoints (`/api/session` and `/api/fund/session`) automatically:\n- Allow `localhost:3000` and `localhost:3001` for development\n- Check the `ALLOWED_ORIGINS` environment variable for production domains\n\n**For Production:** The following domains are configured by default:\n- `https://onramp-demo-application-git-main-coinbase-vercel.vercel.app`\n- `https://www.onrampdemo.com`\n\nTo add additional domains, set the `ALLOWED_ORIGINS` environment variable:\n```bash\nALLOWED_ORIGINS=\"https://yourdomain.com,https://www.yourdomain.com\"\n```\n\n### Rate Limiting (Implemented)\n\n- ✅ 10 requests per minute for `/api/session`\n- ✅ 20 requests per minute for `/api/fund/session`\n- ✅ Per-IP tracking to prevent abuse\n\n### Input Validation (Implemented)\n\n- ✅ Zod schema validation on all inputs\n- ✅ Address format validation\n- ✅ Blockchain network validation\n\n### Secure Logging (Implemented)\n\n- ✅ No sensitive data (API keys, tokens) in logs\n- ✅ Structured logging for security events\n- ✅ Request tracking for audit purposes\n\n**⚠️ Important:** These security measures are **required** by Coinbase to prevent unauthorized usage of onramp sessions. Failure to implement these measures may result in unauthorized access to your integration.\n\nFor more information, see: [Coinbase Security Requirements](https://docs.cdp.coinbase.com/onramp/docs/security-requirements)\n\n## Secure Initialization (Session Tokens)\n\nThis demo now supports secure initialization using session tokens, which provides enhanced security for onramp and offramp transactions.\n\n### What are Session Tokens?\n\nSession tokens are short-lived, one-time-use tokens that authenticate users and manage sessions securely. When enabled, the application generates a session token server-side before initiating the onramp/offramp flow.\n\n### Benefits of Using Session Tokens\n\n- **Enhanced Security**: API credentials are never exposed to the client\n- **Better Control**: Server-side validation before initiating transactions\n- **Compliance**: Meets security requirements for production applications\n\n### How to Enable Secure Initialization\n\n1. **Set up CDP API Credentials**: Add your CDP API key and secret to your `.env.local` file:\n   ```\n   CDP_API_KEY=\"your_cdp_api_key\"\n   CDP_API_SECRET=\"your_cdp_api_secret\"\n   ```\n\n2. **Toggle Secure Initialization**: In both the Onramp and Offramp features, you'll find a \"Use Secure Initialization\" checkbox. Enable it to use session tokens.\n\n3. **Implementation Example**:\n   ```typescript\n   // Generate a session token\n   const response = await fetch('/api/session', {\n     method: 'POST',\n     headers: { 'Content-Type': 'application/json' },\n     body: JSON.stringify({\n       addresses: [{\n         address: \"0x...\",\n         blockchains: [\"ethereum\", \"base\"]\n       }],\n       assets: [\"ETH\", \"USDC\"]\n     }),\n   });\n   \n   const { token } = await response.json();\n   \n   // Use the token in your onramp URL\n   const url = generateOnrampURL({\n     sessionToken: token,\n     // other optional UI params...\n   });\n   ```\n\n### Important Notes\n\n- Session tokens expire quickly and can only be used once\n- When using session tokens, you don't need to pass `appId`, `addresses`, or `assets` in the URL\n- The secure initialization option is available in both Onramp and Offramp features\n\n## Offramp Implementation\n\nThis demo uses the **One-Click-Sell Offramp approach** via the [Sell Quote API](https://docs.cdp.coinbase.com/onramp-\u0026-offramp/offramp-apis/generating-quotes). When you include `source_address`, `redirect_url`, and `partner_user_id` in the quote request, the API returns a ready-to-use URL with all parameters pre-filled (sessionToken, defaultAsset, presetFiatAmount, quoteId, defaultCashoutMethod).\n\nUsers are taken directly to the order preview screen on Coinbase Pay!\n\n### Dynamic Configuration via CDP APIs\n\nThe offramp UI now dynamically loads:\n- **Supported countries and payment methods** via [Sell Config API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-sell-config) (`GET /v1/sell/config`)\n- **Available crypto assets and fiat currencies** via [Sell Options API](https://docs.cdp.coinbase.com/api-reference/rest-api/onramp-offramp/get-sell-options) (`GET /v1/sell/options`)\n\nThis ensures dropdown options always reflect what Coinbase actually supports in each country. Check the browser console for confirmation of API data loading vs. fallback data.\n\n### Offramp Requirements\n\n⚠️ **CRITICAL: Coinbase Account Required for Offramp**\n\nUnlike onramp (which supports guest checkout), **offramp transactions require users to have a Coinbase account with linked bank details**. This is a Coinbase requirement, not a limitation of this demo app.\n\n### What Users Need for Offramp\n\nTo successfully complete an offramp (cash-out) transaction, users MUST have:\n\n1. **Active Coinbase Account**\n   - Sign up at [coinbase.com](https://www.coinbase.com)\n   - Guest checkout is NOT supported for fiat withdrawals\n\n2. **Identity Verification**\n   - Complete Coinbase's KYC (Know Your Customer) verification\n   - This is required by financial regulations\n\n3. **Linked Payment Method**\n   - For ACH transfers: Link a US bank account in Coinbase\n   - For PayPal: Connect PayPal account in Coinbase settings\n   - For SEPA: Link European bank account (Europe only)\n\n4. **Crypto Assets**\n   - Have the cryptocurrency you want to sell in your connected wallet\n   - Assets must be on the correct blockchain network\n   - Sufficient balance to cover the transaction amount\n\n### Common Reasons Offramp May Fail\n\nIf clicking \"Cash Out Now\" doesn't complete the transaction, it's usually because:\n\n- ❌ User doesn't have a Coinbase account\n- ❌ Bank account/payment method not linked in Coinbase\n- ❌ Identity verification incomplete\n- ❌ Insufficient crypto balance in wallet\n- ❌ Crypto is on wrong network\n- ❌ Transaction was cancelled by user\n\n### Testing Offramp\n\nTo test offramp in this demo:\n\n1. Create a Coinbase account if you don't have one\n2. Complete identity verification\n3. Link your bank account or PayPal\n4. Ensure you have crypto (USDC, ETH, etc.) in your connected wallet\n5. Make sure the asset is on the network you selected\n\n**Note**: This is a real transaction if all requirements are met. Only test with amounts you're comfortable cashing out.\n\n## Integration Options\n\n### Fund Card\n\nThe Fund Card provides a pre-built UI component from Coinbase that handles the entire on-ramp process with minimal configuration.\n\n#### Troubleshooting FundCard Issues\n\nIf you're experiencing issues with the FundCard component:\n\n1. **400 Bad Request Error**:\n\n   - Ensure your CDP Project ID is correctly set in the `.env.local` file as both `NEXT_PUBLIC_CDP_PROJECT_ID` and `CDP_PROJECT_ID`\n   - Verify that your OnchainKit API Key is valid and active\n   - Check that your wallet is connected to the correct network (Base is recommended)\n   - Look for detailed error messages in the browser console\n\n2. **Wallet Connection Issues**:\n\n   - Make sure your WalletConnect Project ID is correctly set\n   - Try disconnecting and reconnecting your wallet\n   - Ensure you're using a compatible wallet (Coinbase Wallet is recommended)\n\n3. **Testing with Simplified Components**:\n\n   - Visit `/basic-fund` to test a minimal FundCard implementation\n   - Visit `/simple-fund` to test a FundCard with CDP Project ID handling\n\n4. **Environment Variable Verification**:\n   - Both client-side (`NEXT_PUBLIC_*`) and server-side variables must be set\n   - The CDP Project ID must be set as both `NEXT_PUBLIC_CDP_PROJECT_ID` (client-side) and `CDP_PROJECT_ID` (server-side)\n   - The API route at `/api/auth` must return a valid CDP Project ID\n   - Make sure your OnchainKit API Key is set as both `NEXT_PUBLIC_ONCHAINKIT_API_KEY` (client-side) and `ONCHAINKIT_API_KEY` (server-side)\n\n### Custom Integration\n\nThe Custom Integration demo showcases a fully customizable UI that gives you complete control over the user experience. Recent enhancements include:\n\n- **Expanded Currency Options**: Support for USD, EUR, GBP, CAD, AUD, JPY, CHF, SGD\n- **Multiple Cryptocurrency Assets**: USDC, ETH, BTC, SOL, MATIC, AVAX, LINK, UNI, AAVE, DAI\n- **Diverse Network Support**: Base, Ethereum, Optimism, Arbitrum, Polygon, Avalanche, Solana, BNB Chain\n- **Comprehensive Payment Methods**: Card, Bank, Apple Pay, Google Pay, PayPal, Coinbase, ACH, SEPA, iDEAL, SOFORT\n- **Global Coverage**: Support for multiple countries including US, UK, Canada, Australia, Germany, France, Spain, Italy, Netherlands, Switzerland, Singapore, Japan\n\n## Tech Stack\n\n- Next.js 14\n- React\n- TypeScript\n- Tailwind CSS\n- @coinbase/onchainkit\n- wagmi\n\n## Deployment\n\nThis project can be easily deployed on Vercel:\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fcoinbase%2Fonramp-demo-application)\n\nWhen deploying, make sure to set up the environment variables in your Vercel project settings.\n\n## Repository Information\n\nThis 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](https://portal.cdp.coinbase.com/).\n\n### Contributing\n\nContributions to this demo application are welcome. Please feel free to submit issues or pull requests to improve the demonstration.\n\n## Recent Updates\n\n- **Enhanced Custom Integration**: Added comprehensive dropdown options for countries, currencies, payment methods, and networks\n- **Improved Type Safety**: Fixed TypeScript type issues for better reliability\n- **UI Enhancements**: Updated styling for better user experience\n\n## Troubleshooting\n\n### Common Issues\n\n1. **API Key Issues**:\n   - Ensure all API keys are correctly set in your `.env.local` file\n   - Verify that your API keys are active and have the correct permissions\n   - Make sure your CDP_PROJECT_ID and NEXT_PUBLIC_CDP_PROJECT_ID are correctly set and match\n   - Check for any whitespace or quotes that might be causing issues\n\n2. **Wallet Connection Problems**:\n   - Try disconnecting and reconnecting your wallet\n   - Ensure you're using a compatible wallet (Coinbase Wallet is recommended)\n   - Check that you're connected to the correct network\n\n3. **Build or Runtime Errors**:\n   - Make sure you're using Node.js 18 or higher\n   - Try clearing your browser cache or using incognito mode\n   - Run `npm install` again to ensure all dependencies are properly installed\n\nIf you encounter any other issues, please check the [Issues](https://github.com/coinbase/onramp-demo-application/issues) section of the repository or create a new issue.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoinbase%2Fonramp-demo-application","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoinbase%2Fonramp-demo-application","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoinbase%2Fonramp-demo-application/lists"}