onramp-demo-application/.env.example at main · coinbase/onramp-demo-application · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# ==============================================
# Coinbase Onramp Demo - Environment Variables
# ==============================================
# Copy this file to .env.local and fill in your actual values
# NEVER commit .env.local to version control!

# ==============================================
# PUBLIC ENVIRONMENT VARIABLES (safe to expose)
# ==============================================

# CDP Project ID - This is your public project identifier
# Get from: https://portal.cdp.coinbase.com/
NEXT_PUBLIC_CDP_PROJECT_ID=your_project_id_here

# Project Name (optional)
NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME=Coinbase Ramp Demo

# ==============================================
# PRIVATE ENVIRONMENT VARIABLES (server-side only)
# ==============================================

# CDP SECRET API Key Name/ID
# Get from: https://portal.cdp.coinbase.com/access/api
# When creating the key, select "Ed25519" as the signature algorithm (recommended)
# This is the API Key ID shown in the CDP Portal (UUID format)
# Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CDP_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# CDP API Private Key (Ed25519 format - recommended)
# ⚠️ CRITICAL: This is a base64-encoded string
# Copy the entire key exactly as shown in CDP Portal (64-byte key encoded as base64)
# Format: A long base64 string ending with "=="
# Example format: "ABC...XYZ123...=="
CDP_API_SECRET="your-base64-encoded-ed25519-private-key-here=="

# Note: If you created your key with EC (legacy) format instead of Ed25519,
# it will look like a PEM key with BEGIN/END markers:
# CDP_API_SECRET="-----BEGIN EC PRIVATE KEY-----
# YourPrivateKeyLine1Here
# YourPrivateKeyLine2Here
# -----END EC PRIVATE KEY-----"
# However, Ed25519 is recommended for better security and performance.

# ==============================================
# OPTIONAL
# ==============================================
NODE_ENV=development

# CORS Origins - Comma-separated list of allowed origins for API requests
# Add your production domain(s) here for Apple Pay and custom integrations
# Example: https://your-app.vercel.app,https://www.yourapp.com
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001

# ==============================================
# APPLE PAY CONFIGURATION
# ==============================================
# For Apple Pay to work in production:
# 1. Set CDP_API_KEY and CDP_API_SECRET (required above)
# 2. Add your HTTPS production domain to ALLOWED_ORIGINS
# 3. Add the SAME domain to CDP Portal > Payments > Domain allowlist
#    URL: https://portal.cdp.coinbase.com/products/onramp
# 4. Ensure domain uses HTTPS (not HTTP) - required by Apple Pay
#
# Note: Apple Pay iframe embedding only works on HTTPS domains
# For localhost testing, use the "Open in new tab" option

# ==============================================
# SESSION TOKEN AUTHENTICATION (SECURE INITIALIZATION)
# ==============================================
# Coinbase Onramp/Offramp components use session tokens for secure authentication.
# Session tokens are generated server-side and passed to the Onramp/Offramp URL.
#
# Requirements:
# 1. CDP_API_KEY and CDP_API_SECRET must be configured (see above)
# 2. Enable "Enforce secure initialization" in CDP Portal (recommended for production):
#    https://portal.cdp.coinbase.com/products/onramp
# 3. Session tokens must include the TRUE client IP (from TCP layer, not headers)
# 4. Session tokens expire after 5 minutes and are single-use
#
# Implementation:
# - This app auto-generates session tokens using the CDP API
# - See app/utils/sessionTokenApi.ts for implementation example
# - JWT authentication is handled automatically by @coinbase/cdp-sdk
#
# Reference:
# - Session Token API: https://docs.cdp.coinbase.com/onramp-offramp/docs/session-token-authentication
# - Security Requirements: https://docs.cdp.coinbase.com/onramp-offramp/docs/security-requirements
#
# ==============================================
# TROUBLESHOOTING
# ==============================================
# If Fund components show "Missing or invalid parameters" error:
#
# 1. Check CDP_API_KEY and CDP_API_SECRET are set correctly
# 2. Verify your API key uses Ed25519 format (recommended)
# 3. For development: You can disable "Enforce secure initialization" in CDP Portal
# 4. For production: Enable "Enforce secure initialization" for better security
#
# ==============================================
# SECURITY NOTES
# ==============================================
# 1. NEXT_PUBLIC_* variables are safe to expose (public)
# 2. CDP_API_KEY and CDP_API_SECRET must NEVER be exposed client-side
# 3. Session tokens must be generated server-side only
# 4. Always use true client IP (TCP layer) for session tokens
# 5. Never trust X-Forwarded-For or similar headers (easily spoofed)
# 6. In Vercel: Set environment variables in Settings > Environment Variables
# 7. Rotate API keys every 90 days
# 8. Revoke compromised keys immediately
# 9. Use IP allowlisting in CDP Portal for additional security
# ==============================================