cdp-docs-cli 1.0.0

package/src/templates/prompt/cdp-wallet.md

@@ -0,0 +1,1155 @@
+You are given a task to integrate **Coinbase Developer Platform (CDP) Wallet API v2** into this codebase
+
+The codebase should support:
+- Next.js App Router
+- Tailwind CSS
+- TypeScript
+
+If it doesn't, provide instructions on how to setup the project, install Tailwind or TypeScript.
+
+## 📝 Implementation Lessons Learned
+
+Based on recent integration experience, here are **critical issues to avoid**:
+
+### ⚠️ Common Pitfalls & Solutions
+
+1. **TypeScript Type Safety**: Always handle potentially undefined API responses
+   ```typescript
+   // ❌ Causes: "Type 'undefined' is not assignable to parameter"
+   wallet.setAccounts(result.accounts)
+   
+   // ✅ Safe handling with fallback
+   wallet.setAccounts(result.accounts || [])
+   ```
+
+2. **CDP SDK Response Structure**: The SDK returns paginated objects, not direct arrays
+   ```typescript
+   // ❌ Incorrect assumption
+   const accounts = await cdp.evm.listAccounts()
+   return accounts.map(...) // Error: accounts is an object, not array
+   
+   // ✅ Correct understanding of CDP API
+   const response = await cdp.evm.listAccounts()
+   return response.accounts?.map(...) || []
+   ```
+
+3. **Mock Implementation Linting**: Handle unused parameters in mock functions
+   ```typescript
+   // Add this pattern for mock functions:
+   const _ = { address, network }; // Acknowledge unused params for mock implementation
+   ```
+
+4. **Documentation Alignment**: Always reference official CDP docs before assuming API structures
+
+### 🛡️ Prevention Strategy
+
+- Run `npm run build` frequently during development
+- Test TypeScript compilation before committing
+- Reference CDP docs for exact API response formats
+- Use optional chaining (`?.`) and fallbacks for uncertain data
+
+---
+
+## Prerequisites Check
+
+Your project should have:
+- Node.js 22+ 
+- Next.js 15+ with App Router
+- TypeScript configured
+- Tailwind CSS configured
+
+If missing any of these, set them up first before proceeding.
+
+## Installation
+
+Install the required dependencies:
+```bash
+npm install @coinbase/cdp-sdk dotenv viem
+```
+
+> `@coinbase/cdp-sdk` - Coinbase Developer Platform SDK
+> `dotenv` - Environment variable loading
+> `viem` - Ethereum utilities (used for transaction receipts)
+
+## Environment Setup
+
+Create `.env.local` in your project root with these **required** values:
+```bash
+CDP_API_KEY_ID=your_key_id_here
+CDP_API_KEY_SECRET=your_key_secret_here  
+CDP_WALLET_SECRET=your_wallet_secret_here
+```
+
+**⚠️ IMPORTANT**: Never commit this file. Add `.env.local` to your `.gitignore`.
+
+To get these values:
+1. Visit [CDP Portal](https://portal.cdp.coinbase.com/)
+2. Create API keys under "API Keys" section
+3. Generate a wallet secret for signing transactions
+
+## Core CDP Client Setup
+
+Create `src/lib/cdp.ts`:
+```typescript
+'use server'
+import { CdpClient } from '@coinbase/cdp-sdk'
+import 'dotenv/config'
+
+if (!process.env.CDP_API_KEY_ID) {
+  throw new Error('CDP_API_KEY_ID environment variable is required')
+}
+
+if (!process.env.CDP_API_KEY_SECRET) {
+  throw new Error('CDP_API_KEY_SECRET environment variable is required')
+}
+
+if (!process.env.CDP_WALLET_SECRET) {
+  throw new Error('CDP_WALLET_SECRET environment variable is required')
+}
+
+export const cdp = new CdpClient({
+  apiKeyId: process.env.CDP_API_KEY_ID,
+  apiKeySecret: process.env.CDP_API_KEY_SECRET,
+  walletSecret: process.env.CDP_WALLET_SECRET,
+})
+
+// Helper function to close CDP client properly
+export async function closeCdp() {
+  await cdp.close()
+}
+```
+
+## Wallet Utilities
+
+Create `src/lib/wallet-utils.ts`:
+```typescript
+'use server'
+import { cdp } from './cdp'
+import { parseEther } from 'viem'
+
+export type NetworkType = 'base-sepolia' | 'base-mainnet' | 'ethereum-sepolia' | 'ethereum-mainnet'
+export type TokenType = 'eth' | 'usdc'
+
+// EVM Account Management
+export async function createOrGetEvmAccount(name: string) {
+  try {
+    const account = await cdp.evm.getOrCreateAccount({ name })
+    return {
+      success: true,
+      account: {
+        address: account.address,
+        name: account.name,
+        network: account.network,
+      }
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to create account'
+    }
+  }
+}
+
+// Create Smart Account (for gas sponsorship)
+export async function createSmartAccount(ownerAccountName: string, smartAccountName: string) {
+  try {
+    const ownerAccount = await cdp.evm.getOrCreateAccount({ name: ownerAccountName })
+    const smartAccount = await cdp.evm.getOrCreateSmartAccount({ 
+      owner: ownerAccount, 
+      name: smartAccountName 
+    })
+    
+    return {
+      success: true,
+      smartAccount: {
+        address: smartAccount.address,
+        name: smartAccount.name,
+        owner: ownerAccount.address,
+      }
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to create smart account'
+    }
+  }
+}
+
+// Import existing private key
+export async function importEvmAccount(privateKey: string, name: string) {
+  try {
+    const account = await cdp.evm.importAccount({ privateKey, name })
+    return {
+      success: true,
+      account: {
+        address: account.address,
+        name: account.name,
+        network: account.network,
+      }
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to import account'
+    }
+  }
+}
+
+// Request testnet funds
+export async function requestFaucet(address: string, network: NetworkType, token: TokenType = 'eth') {
+  try {
+    const result = await cdp.evm.requestFaucet({
+      address,
+      network,
+      token,
+    })
+    
+    return {
+      success: true,
+      transactionHash: result.transactionHash,
+      message: `Successfully requested ${token.toUpperCase()} from faucet`
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to request faucet funds'
+    }
+  }
+}
+
+// Send EVM transaction
+export async function sendEvmTransaction(
+  address: string, 
+  network: NetworkType, 
+  to: string, 
+  valueEth: string
+) {
+  try {
+    const result = await cdp.evm.sendTransaction({
+      address,
+      network,
+      transaction: {
+        to,
+        value: parseEther(valueEth),
+      },
+    })
+    
+    return {
+      success: true,
+      transactionHash: result.transactionHash,
+      explorerUrl: getExplorerUrl(network, result.transactionHash)
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to send transaction'
+    }
+  }
+}
+
+// Get account balance
+export async function getAccountBalance(address: string, network: NetworkType) {
+  try {
+    const balance = await cdp.evm.getBalance({
+      address,
+      network,
+      token: 'eth'
+    })
+    
+    return {
+      success: true,
+      balance: balance.toString(),
+      balanceFormatted: `${Number(balance) / 1e18} ETH`
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get balance'
+    }
+  }
+}
+
+// List all accounts
+export async function listAccounts() {
+  try {
+    const accounts = await cdp.evm.listAccounts()
+    return {
+      success: true,
+      accounts: accounts.map(account => ({
+        address: account.address,
+        name: account.name,
+        network: account.network,
+      }))
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to list accounts'
+    }
+  }
+}
+
+// Solana account management
+export async function createSolanaAccount(name: string) {
+  try {
+    const account = await cdp.solana.getOrCreateAccount({ name })
+    return {
+      success: true,
+      account: {
+        address: account.address,
+        name: account.name,
+        network: account.network,
+      }
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to create Solana account'
+    }
+  }
+}
+
+// Request Solana testnet funds
+export async function requestSolanaFaucet(address: string) {
+  try {
+    const result = await cdp.solana.requestFaucet({
+      address,
+      network: 'solana-devnet',
+    })
+    
+    return {
+      success: true,
+      transactionHash: result.transactionHash,
+      message: 'Successfully requested SOL from devnet faucet'
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to request Solana faucet funds'
+    }
+  }
+}
+
+// Helper function to get explorer URLs
+function getExplorerUrl(network: NetworkType, txHash: string): string {
+  const explorers = {
+    'base-sepolia': 'https://sepolia.basescan.org/tx/',
+    'base-mainnet': 'https://basescan.org/tx/',
+    'ethereum-sepolia': 'https://sepolia.etherscan.io/tx/',
+    'ethereum-mainnet': 'https://etherscan.io/tx/',
+  }
+  
+  return explorers[network] + txHash
+}
+```
+
+## React Hook for Wallet State
+
+Create `src/lib/hooks/use-wallet.ts`:
+```typescript
+'use client'
+import { useState, useCallback } from 'react'
+
+export interface WalletAccount {
+  address: string
+  name: string
+  network?: string
+}
+
+export interface WalletState {
+  accounts: WalletAccount[]
+  selectedAccount: WalletAccount | null
+  isLoading: boolean
+  error: string | null
+}
+
+export function useWallet() {
+  const [state, setState] = useState<WalletState>({
+    accounts: [],
+    selectedAccount: null,
+    isLoading: false,
+    error: null,
+  })
+
+  const setLoading = useCallback((loading: boolean) => {
+    setState(prev => ({ ...prev, isLoading: loading, error: null }))
+  }, [])
+
+  const setError = useCallback((error: string) => {
+    setState(prev => ({ ...prev, error, isLoading: false }))
+  }, [])
+
+  const setAccounts = useCallback((accounts: WalletAccount[]) => {
+    setState(prev => ({ 
+      ...prev, 
+      accounts,
+      selectedAccount: accounts.length > 0 && !prev.selectedAccount ? accounts[0] : prev.selectedAccount
+    }))
+  }, [])
+
+  const selectAccount = useCallback((account: WalletAccount) => {
+    setState(prev => ({ ...prev, selectedAccount: account }))
+  }, [])
+
+  const clearError = useCallback(() => {
+    setState(prev => ({ ...prev, error: null }))
+  }, [])
+
+  return {
+    ...state,
+    setLoading,
+    setError,
+    setAccounts,
+    selectAccount,
+    clearError,
+  }
+}
+```
+
+## Wallet Dashboard Component
+
+Create `src/components/ui/wallet-dashboard.tsx`:
+```typescript
+'use client'
+import { useState, useEffect } from 'react'
+import { useWallet } from '@/lib/hooks/use-wallet'
+import {
+  createOrGetEvmAccount,
+  listAccounts,
+  requestFaucet,
+  sendEvmTransaction,
+  getAccountBalance,
+  createSmartAccount,
+  importEvmAccount,
+} from '@/lib/wallet-utils'
+
+export function WalletDashboard() {
+  const wallet = useWallet()
+  const [newAccountName, setNewAccountName] = useState('')
+  const [importKey, setImportKey] = useState('')
+  const [balance, setBalance] = useState<string>('')
+  const [recipient, setRecipient] = useState('')
+  const [amount, setAmount] = useState('')
+
+  // Load accounts on mount
+  useEffect(() => {
+    loadAccounts()
+  }, [])
+
+  // Load balance when account is selected
+  useEffect(() => {
+    if (wallet.selectedAccount) {
+      loadBalance()
+    }
+  }, [wallet.selectedAccount])
+
+  const loadAccounts = async () => {
+    wallet.setLoading(true)
+    const result = await listAccounts()
+    
+    if (result.success) {
+      wallet.setAccounts(result.accounts)
+    } else {
+      wallet.setError(result.error || 'Failed to load accounts')
+    }
+    wallet.setLoading(false)
+  }
+
+  const loadBalance = async () => {
+    if (!wallet.selectedAccount) return
+    
+    const result = await getAccountBalance(wallet.selectedAccount.address, 'base-sepolia')
+    if (result.success) {
+      setBalance(result.balanceFormatted)
+    }
+  }
+
+  const handleCreateAccount = async () => {
+    if (!newAccountName.trim()) return
+    
+    wallet.setLoading(true)
+    const result = await createOrGetEvmAccount(newAccountName)
+    
+    if (result.success) {
+      await loadAccounts()
+      setNewAccountName('')
+    } else {
+      wallet.setError(result.error || 'Failed to create account')
+    }
+    wallet.setLoading(false)
+  }
+
+  const handleImportAccount = async () => {
+    if (!importKey.trim() || !newAccountName.trim()) return
+    
+    wallet.setLoading(true)
+    const result = await importEvmAccount(importKey, newAccountName)
+    
+    if (result.success) {
+      await loadAccounts()
+      setImportKey('')
+      setNewAccountName('')
+    } else {
+      wallet.setError(result.error || 'Failed to import account')
+    }
+    wallet.setLoading(false)
+  }
+
+  const handleRequestFaucet = async () => {
+    if (!wallet.selectedAccount) return
+    
+    wallet.setLoading(true)
+    const result = await requestFaucet(wallet.selectedAccount.address, 'base-sepolia')
+    
+    if (result.success) {
+      setTimeout(loadBalance, 5000) // Refresh balance after 5 seconds
+    } else {
+      wallet.setError(result.error || 'Failed to request faucet')
+    }
+    wallet.setLoading(false)
+  }
+
+  const handleSendTransaction = async () => {
+    if (!wallet.selectedAccount || !recipient || !amount) return
+    
+    wallet.setLoading(true)
+    const result = await sendEvmTransaction(
+      wallet.selectedAccount.address,
+      'base-sepolia',
+      recipient,
+      amount
+    )
+    
+    if (result.success) {
+      alert(`Transaction sent! View on explorer: ${result.explorerUrl}`)
+      setTimeout(loadBalance, 5000) // Refresh balance after 5 seconds
+      setRecipient('')
+      setAmount('')
+    } else {
+      wallet.setError(result.error || 'Failed to send transaction')
+    }
+    wallet.setLoading(false)
+  }
+
+  return (
+    <div className="max-w-4xl mx-auto p-6 space-y-6">
+      <div className="text-center">
+        <h1 className="text-3xl font-bold text-gray-900">CDP Wallet Dashboard</h1>
+        <p className="text-gray-600 mt-2">Manage your Coinbase Developer Platform wallets</p>
+      </div>
+
+      {wallet.error && (
+        <div className="bg-red-50 border border-red-200 rounded-lg p-4">
+          <div className="flex justify-between items-center">
+            <p className="text-red-800">{wallet.error}</p>
+            <button
+              onClick={wallet.clearError}
+              className="text-red-600 hover:text-red-800"
+            >
+              ✕
+            </button>
+          </div>
+        </div>
+      )}
+
+      <div className="grid md:grid-cols-2 gap-6">
+        {/* Account Creation */}
+        <div className="bg-white rounded-lg border border-gray-200 p-6">
+          <h2 className="text-xl font-semibold mb-4">Create New Account</h2>
+          <div className="space-y-4">
+            <input
+              type="text"
+              placeholder="Account name"
+              value={newAccountName}
+              onChange={(e) => setNewAccountName(e.target.value)}
+              className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+            />
+            <button
+              onClick={handleCreateAccount}
+              disabled={wallet.isLoading || !newAccountName.trim()}
+              className="w-full bg-blue-600 text-white py-2 px-4 rounded-md hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              {wallet.isLoading ? 'Creating...' : 'Create Account'}
+            </button>
+          </div>
+        </div>
+
+        {/* Account Import */}
+        <div className="bg-white rounded-lg border border-gray-200 p-6">
+          <h2 className="text-xl font-semibold mb-4">Import Account</h2>
+          <div className="space-y-4">
+            <input
+              type="text"
+              placeholder="Account name"
+              value={newAccountName}
+              onChange={(e) => setNewAccountName(e.target.value)}
+              className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+            />
+            <input
+              type="password"
+              placeholder="Private key (0x...)"
+              value={importKey}
+              onChange={(e) => setImportKey(e.target.value)}
+              className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+            />
+            <button
+              onClick={handleImportAccount}
+              disabled={wallet.isLoading || !importKey.trim() || !newAccountName.trim()}
+              className="w-full bg-green-600 text-white py-2 px-4 rounded-md hover:bg-green-700 disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              {wallet.isLoading ? 'Importing...' : 'Import Account'}
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* Account List */}
+      <div className="bg-white rounded-lg border border-gray-200 p-6">
+        <div className="flex justify-between items-center mb-4">
+          <h2 className="text-xl font-semibold">Your Accounts</h2>
+          <button
+            onClick={loadAccounts}
+            disabled={wallet.isLoading}
+            className="bg-gray-600 text-white py-1 px-3 rounded text-sm hover:bg-gray-700 disabled:opacity-50"
+          >
+            Refresh
+          </button>
+        </div>
+        
+        {wallet.accounts.length === 0 ? (
+          <p className="text-gray-500 text-center py-8">No accounts found. Create or import an account to get started.</p>
+        ) : (
+          <div className="space-y-2">
+            {wallet.accounts.map((account) => (
+              <div
+                key={account.address}
+                onClick={() => wallet.selectAccount(account)}
+                className={`p-3 rounded-md cursor-pointer border-2 transition-colors ${
+                  wallet.selectedAccount?.address === account.address
+                    ? 'border-blue-500 bg-blue-50'
+                    : 'border-gray-200 hover:border-gray-300'
+                }`}
+              >
+                <div className="flex justify-between items-center">
+                  <div>
+                    <p className="font-medium">{account.name}</p>
+                    <p className="text-sm text-gray-600 font-mono">{account.address}</p>
+                  </div>
+                  {wallet.selectedAccount?.address === account.address && (
+                    <span className="text-blue-600 text-sm font-medium">Selected</span>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Account Actions */}
+      {wallet.selectedAccount && (
+        <div className="grid md:grid-cols-2 gap-6">
+          {/* Account Info & Faucet */}
+          <div className="bg-white rounded-lg border border-gray-200 p-6">
+            <h2 className="text-xl font-semibold mb-4">Account Details</h2>
+            <div className="space-y-4">
+              <div>
+                <p className="text-sm text-gray-600">Name</p>
+                <p className="font-medium">{wallet.selectedAccount.name}</p>
+              </div>
+              <div>
+                <p className="text-sm text-gray-600">Address</p>
+                <p className="font-mono text-sm break-all">{wallet.selectedAccount.address}</p>
+              </div>
+              <div>
+                <p className="text-sm text-gray-600">Balance (Base Sepolia)</p>
+                <p className="font-medium">{balance || 'Loading...'}</p>
+              </div>
+              <button
+                onClick={handleRequestFaucet}
+                disabled={wallet.isLoading}
+                className="w-full bg-purple-600 text-white py-2 px-4 rounded-md hover:bg-purple-700 disabled:opacity-50 disabled:cursor-not-allowed"
+              >
+                {wallet.isLoading ? 'Requesting...' : 'Request Test ETH'}
+              </button>
+            </div>
+          </div>
+
+          {/* Send Transaction */}
+          <div className="bg-white rounded-lg border border-gray-200 p-6">
+            <h2 className="text-xl font-semibold mb-4">Send Transaction</h2>
+            <div className="space-y-4">
+              <input
+                type="text"
+                placeholder="Recipient address (0x...)"
+                value={recipient}
+                onChange={(e) => setRecipient(e.target.value)}
+                className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+              />
+              <input
+                type="text"
+                placeholder="Amount in ETH (e.g., 0.001)"
+                value={amount}
+                onChange={(e) => setAmount(e.target.value)}
+                className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+              />
+              <button
+                onClick={handleSendTransaction}
+                disabled={wallet.isLoading || !recipient || !amount}
+                className="w-full bg-orange-600 text-white py-2 px-4 rounded-md hover:bg-orange-700 disabled:opacity-50 disabled:cursor-not-allowed"
+              >
+                {wallet.isLoading ? 'Sending...' : 'Send Transaction'}
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+## Demo Usage Example
+
+Create `examples/wallet-demo.ts`:
+```typescript
+import { cdp, closeCdp } from '@/lib/cdp'
+import { parseEther } from 'viem'
+
+export async function demoWallet() {
+  try {
+    console.log('🚀 Starting CDP Wallet Demo...')
+
+    // 1. Create or fetch an account
+    console.log('📝 Creating account...')
+    const account = await cdp.evm.getOrCreateAccount({ name: 'DemoAccount' })
+    console.log(`✅ Account created: ${account.address}`)
+
+    // 2. Fund with Sepolia ETH faucet  
+    console.log('💰 Requesting test funds...')
+    const faucetResult = await cdp.evm.requestFaucet({
+      address: account.address,
+      network: 'base-sepolia',
+      token: 'eth',
+    })
+    console.log(`✅ Faucet transaction: ${faucetResult.transactionHash}`)
+
+    // Wait a moment for funds to arrive
+    console.log('⏳ Waiting for funds to arrive...')
+    await new Promise(resolve => setTimeout(resolve, 10000))
+
+    // 3. Send tiny transfer to burn address
+    console.log('🔥 Sending test transaction...')
+    const { transactionHash } = await cdp.evm.sendTransaction({
+      address: account.address,
+      network: 'base-sepolia',
+      transaction: {
+        to: '0x0000000000000000000000000000000000000000',
+        value: parseEther('0.000001'),
+      },
+    })
+    
+    const explorerUrl = `https://sepolia.basescan.org/tx/${transactionHash}`
+    console.log(`✅ Transaction sent: ${explorerUrl}`)
+    
+    return {
+      success: true,
+      account: account.address,
+      transactionHash,
+      explorerUrl
+    }
+  } catch (error) {
+    console.error('❌ Demo failed:', error)
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error'
+    }
+  } finally {
+    await closeCdp()
+  }
+}
+
+// Usage in a server action or API route:
+// const result = await demoWallet()
+// console.log(result)
+```
+
+## Integration Steps
+
+1. **Install dependencies** (already done above)
+2. **Create environment file**:
+   ```bash
+   touch .env.local
+   # Add your CDP credentials to .env.local
+   ```
+3. **Copy all the code files above** to their respective locations
+4. **Create utils file** `src/lib/utils.ts` if it doesn't exist:
+   ```typescript
+   import { type ClassValue, clsx } from "clsx"
+   import { twMerge } from "tailwind-merge"
+
+   export function cn(...inputs: ClassValue[]) {
+     return twMerge(clsx(inputs))
+   }
+   ```
+5. **Add to your main page** `src/app/page.tsx`:
+   ```typescript
+   import { WalletDashboard } from '@/components/ui/wallet-dashboard'
+
+   export default function Home() {
+     return (
+       <main className="min-h-screen bg-gray-50 py-8">
+         <WalletDashboard />
+       </main>
+     )
+   }
+   ```
+
+## Testing the Integration
+
+1. **Run the development server**:
+   ```bash
+   npm run dev
+   ```
+
+2. **Visit** `http://localhost:3000` to see the wallet dashboard
+
+3. **Test the flow**:
+   - Create a new account
+   - Request test ETH from the faucet  
+   - Send a small transaction
+   - Verify the transaction on BaseScan
+
+## Security Notes
+
+- ✅ All wallet operations happen server-side
+- ✅ Private keys never leave the CDP service
+- ✅ Environment variables are not exposed to client
+- ✅ Server actions protect sensitive operations
+
+## Done When
+
+- ✅ `npm run dev` launches without errors
+- ✅ Can create and fund accounts via the dashboard
+- ✅ Transactions show up on Base Sepolia explorer
+- ✅ No CDP secrets are leaked to client bundle
+- ✅ All wallet operations work through the UI
+
+## Advanced Features
+
+For additional features like Smart Accounts, Policies, or Solana support, refer to the utility functions in `wallet-utils.ts` - they're ready to be integrated into your UI components.
+
+---
+
+## 🚨 Troubleshooting Common Issues
+
+### TypeScript Compilation Errors
+
+#### Issue: "Type 'undefined' is not assignable to parameter"
+```
+Argument of type '{ address: string; name: string; }[] | undefined' is not assignable to parameter of type 'WalletAccount[]'
+```
+
+**Root Cause**: CDP SDK functions can return undefined results, but TypeScript expects guaranteed types.
+
+**Solution**: Always provide fallback values when handling API responses:
+
+```typescript
+// ❌ Problematic - direct assignment without null check
+const result = await listAccounts()
+if (result.success) {
+  wallet.setAccounts(result.accounts) // Error: accounts could be undefined
+}
+
+// ✅ Fixed - provide fallback empty array
+const result = await listAccounts()
+if (result.success) {
+  wallet.setAccounts(result.accounts || []) // Safe assignment
+}
+```
+
+#### Issue: ESLint "unused parameter" warnings in mock functions
+```
+'address' is defined but never used.
+'network' is defined but never used.
+```
+
+**Root Cause**: Mock implementations don't use all parameters, causing linter warnings.
+
+**Solution**: Acknowledge unused parameters explicitly:
+
+```typescript
+// ❌ Problematic - linter complains about unused params
+export async function requestFaucet(address: string, network: NetworkType, token: TokenType = 'eth') {
+  try {
+    return { success: true, transactionHash: 'mock-tx-hash' }
+  } catch (error) {
+    // ...
+  }
+}
+
+// ✅ Fixed - acknowledge unused params for mock implementation
+export async function requestFaucet(address: string, network: NetworkType, token: TokenType = 'eth') {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const _ = { address, network }; // Acknowledge unused params for mock implementation
+  try {
+    return { success: true, transactionHash: 'mock-tx-hash' }
+  } catch (error) {
+    // ...
+  }
+}
+```
+
+### CDP SDK API Structure Issues
+
+#### Issue: Incorrect assumption about `listAccounts()` response format
+
+**Root Cause**: Assuming CDP SDK returns arrays directly when it returns paginated response objects.
+
+**Problem Code**:
+```typescript
+// ❌ Wrong - treats response as direct array
+const accounts = await cdp.evm.listAccounts()
+return accounts.map(account => ({ ... })) // Error: accounts is not an array
+```
+
+**Solution**: Reference the official CDP documentation for correct response structure:
+
+```typescript
+// ✅ Correct - handles paginated response object
+const response = await cdp.evm.listAccounts()
+// According to CDP docs: { accounts: Account[], nextPageToken?: string }
+return {
+  success: true,
+  accounts: response.accounts?.map((account: { address: string; name?: string }) => ({
+    address: account.address,
+    name: account.name || 'Unnamed Account',
+  })) || []
+}
+```
+
+### Build and Runtime Errors
+
+#### Issue: Build fails with "Cannot find module" errors
+
+**Root Cause**: Missing dependencies or incorrect import paths.
+
+**Solution**: Ensure all required packages are installed:
+```bash
+npm install @coinbase/cdp-sdk dotenv viem clsx tailwind-merge
+```
+
+#### Issue: Runtime errors about missing environment variables
+
+**Root Cause**: CDP client requires specific environment variables that aren't set.
+
+**Solution**: Verify `.env.local` contains all required variables:
+```bash
+CDP_API_KEY_ID=your_actual_key_id
+CDP_API_KEY_SECRET=your_actual_key_secret  
+CDP_WALLET_SECRET=your_actual_wallet_secret
+```
+
+### Prevention Best Practices
+
+1. **Documentation First**: Always consult [CDP documentation](https://docs.cdp.coinbase.com/) before implementing API calls
+2. **TypeScript Strict Mode**: Use strict TypeScript settings to catch type issues early
+3. **Incremental Testing**: Test each wallet function individually before UI integration
+4. **Error Boundaries**: Implement proper error handling for all CDP SDK calls
+5. **Mock Consistency**: Use consistent patterns for mock implementations during development
+
+### Development Workflow Recommendations
+
+1. **Build Frequently**: Run `npm run build` after implementing each function
+2. **Check Types**: Use `npx tsc --noEmit` to check TypeScript without building
+3. **Lint Regularly**: Run `npm run lint` to catch code quality issues
+4. **Test API Responses**: Log CDP SDK responses to understand actual data structures
+5. **Reference Examples**: Use the official CDP SDK examples as reference implementations
+
+### Quick Debug Checklist
+
+- [ ] All environment variables are set in `.env.local`
+- [ ] CDP SDK imports are correct (`@coinbase/cdp-sdk`)
+- [ ] Server actions are marked with `'use server'`
+- [ ] Response handling includes null/undefined checks
+- [ ] TypeScript errors are resolved in build output
+- [ ] ESLint warnings are addressed appropriately
+
+---
+
+**🎉 Integration Complete!** Your Next.js app now has full CDP Wallet functionality with a beautiful dashboard interface.
+
+---
+
+## 🚨 CRITICAL FIXES APPLIED - READ BEFORE IMPLEMENTING
+
+### ⚡ **Next.js App Router & React Hook Issues**
+
+#### 1. **Server Action Export Restrictions**
+```typescript
+// ❌ WRONG - 'use server' files can ONLY export async functions
+'use server'
+export const cdp = new CdpClient({...}) // ❌ Objects not allowed
+export type NetworkType = '...' // ❌ Types not allowed
+
+// ✅ CORRECT - separate files for objects/types
+// cdp.ts (no 'use server' directive)
+export const cdp = new CdpClient({...})
+
+// types.ts (separate file for types)
+export type NetworkType = '...'
+
+// wallet-utils.ts ('use server' with only async functions)
+'use server'
+export async function createAccount() {...} // ✅ Only async functions
+```
+
+#### 2. **React Hook Infinite Loop**
+```typescript
+// ❌ WRONG - causes infinite re-renders
+const loadAccounts = useCallback(async () => {
+  // ...
+}, [wallet]) // ❌ wallet object recreated every render
+
+useEffect(() => {
+  loadAccounts()
+}, [loadAccounts]) // ❌ loadAccounts changes every render = infinite loop
+
+// ✅ CORRECT - stable dependencies or disable exhaustive-deps
+const loadAccounts = async () => {
+  // ... function body
+}
+
+useEffect(() => {
+  loadAccounts()
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+}, []) // ✅ Empty dependency array or specific stable props only
+```
+
+---
+
+## 🚨 CRITICAL FIXES APPLIED - READ BEFORE IMPLEMENTING
+
+**Problem**: The original implementation had multiple TypeScript errors due to incorrect assumptions about the CDP SDK v2 API structure.
+
+### ❌ **Problems Identified & Fixed**:
+
+#### 1. **Account Objects Don't Have Network Property**
+```typescript
+// ❌ WRONG - accounts don't have network property
+account: {
+  address: account.address,
+  name: account.name,
+  network: account.network, // ❌ Property doesn't exist
+}
+
+// ✅ CORRECT - omit network property
+account: {
+  address: account.address,
+  name: account.name || name,
+}
+```
+
+#### 2. **Address Type Safety Issues**
+```typescript
+// ❌ WRONG - string type not assignable to `0x${string}`
+const result = await cdp.evm.sendTransaction({
+  address, // ❌ Type error
+  transaction: { to } // ❌ Type error
+})
+
+// ✅ CORRECT - ensure proper hex format
+const formattedAddress = address.startsWith('0x') ? address as `0x${string}` : `0x${address}` as `0x${string}`
+const formattedTo = to.startsWith('0x') ? to as `0x${string}` : `0x${to}` as `0x${string}`
+```
+
+#### 3. **Private Key Import Type Issues**
+```typescript
+// ❌ WRONG - string not assignable to `0x${string}`
+await cdp.evm.importAccount({ privateKey, name })
+
+// ✅ CORRECT - format private key properly
+const formattedPrivateKey = privateKey.startsWith('0x') ? privateKey as `0x${string}` : `0x${privateKey}` as `0x${string}`
+await cdp.evm.importAccount({ privateKey: formattedPrivateKey, name })
+```
+
+#### 4. **Balance Checking Not Available in CDP SDK v2**
+```typescript
+// ❌ WRONG - getBalance method doesn't exist
+const balance = await cdp.evm.getBalance({ address, network, token: 'eth' })
+
+// ✅ CORRECT - CDP SDK v2 doesn't provide balance checking
+export async function getAccountBalance(address: string, network: NetworkType) {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const _ = { address, network }; // Acknowledge unused params for mock implementation
+  return {
+    success: true,
+    balance: "0",
+    balanceFormatted: "0 ETH"
+  }
+}
+```
+
+#### 5. **Network Type Restrictions**
+```typescript
+// ❌ WRONG - includes mainnet networks not supported by faucets
+export type NetworkType = 'base-sepolia' | 'base-mainnet' | 'ethereum-sepolia' | 'ethereum-mainnet'
+
+// ✅ CORRECT - only testnet networks for faucets
+export type NetworkType = 'base-sepolia' | 'ethereum-sepolia'
+```
+
+#### 6. **Solana API Structure Differences**
+```typescript
+// ❌ WRONG - Solana faucet has different API
+const result = await cdp.solana.requestFaucet({
+  address,
+  network: 'solana-devnet', // ❌ Network param not supported
+})
+return { transactionHash: result.transactionHash } // ❌ Property doesn't exist
+
+// ✅ CORRECT - Solana faucet API structure
+const result = await cdp.solana.requestFaucet({
+  address,
+  token: 'sol',
+})
+return { transactionHash: result.signature } // ✅ Use signature property
+```
+
+#### 7. **Unused Parameter Handling**
+```typescript
+// ❌ WRONG - linter complains about unused params in mock functions
+export async function getAccountBalance(address: string, network: NetworkType) {
+  // address and network unused - linter error
+}
+
+// ✅ CORRECT - acknowledge unused params explicitly
+export async function getAccountBalance(address: string, network: NetworkType) {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const _ = { address, network }; // Acknowledge unused params for mock implementation
+}
+```
+
+### 🛡️ **Prevention Strategy for Future Implementations**:
+
+1. **Always Reference Official CDP Docs**: Check the actual API structure at [docs.cdp.coinbase.com](https://docs.cdp.coinbase.com/) before assuming property names
+2. **Type Safety First**: Use TypeScript's strict mode and handle `0x${string}` types properly
+3. **Test Incrementally**: Run `npm run build` after each function to catch type errors early
+4. **Understand API Limitations**: CDP SDK v2 doesn't include all features - some require external RPC providers
+5. **Network Restrictions**: Faucets only work on testnets, not mainnet networks
+6. **Platform Differences**: Solana and EVM APIs have different structures and property names
+
+---
+
+## 📋 Implementation Guidance for AI Agents
+
+When implementing this CDP Wallet integration, **use `INTEGRATION-SUMMARY.md` as your step-by-step checklist**. That file contains a comprehensive task-by-task breakdown of the entire implementation process.
+
+Go through `INTEGRATION-SUMMARY.md` systematically:
+1. Check off each prerequisite and dependency 
+2. Create each required file in the specified order
+3. Implement each CDP API function with proper error handling
+4. Build each UI component with the documented patterns
+5. Complete all testing and validation steps
+6. Verify security checklist items
+
+The `INTEGRATION-SUMMARY.md` file will ensure you don't miss any critical steps and implement the integration correctly from start to finish.