Onchainkit

OnchainKit

Build production-ready onchain applications using Coinbase's comprehensive React component library and TypeScript utilities.

Overview

OnchainKit provides ready-to-use, full-stack components that abstract blockchain complexity, making it easy to build onchain applications without deep blockchain knowledge. It offers AI-friendly components that work automatically on Base, requires no backend infrastructure, and provides cost-effective transactions (< $0.01 fees).

Quick Start

New Project Setup

# Create a new onchain app with all batteries included
scripts/create-onchain-app.py <project-name>

# Verify setup
scripts/validate-setup.py

Add to Existing Project

npm install @coinbase/onchainkit
# Setup configuration and providers
scripts/setup-environment.py

Core Capabilities

1. Wallet Connection & Management

Connect users to their crypto wallets with minimal code:

import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';

function WalletConnection() {
  return (
    <Wallet>
      <ConnectWallet />
    </Wallet>
  );
}

Use cases:

• Wallet connection flows
• Display wallet status
• Manage connection state
• Handle multiple wallets

Reference: references/wallet-integration.md

2. Identity Display

Show blockchain identities with ENS names, avatars, and verification badges:

import { Identity, Avatar, Name, Badge } from '@coinbase/onchainkit/identity';

function UserProfile({ address }) {
  return (
    <Identity address={address}>
      <Avatar />
      <Name />
      <Badge />
    </Identity>
  );
}

Reference: references/identity-components.md

3. Token Operations

Handle token swaps, purchases, and transfers:

import { Swap, SwapAmountInput, SwapButton } from '@coinbase/onchainkit/swap';

function TokenSwap() {
  return (
    <Swap>
      <SwapAmountInput />
      <SwapButton />
    </Swap>
  );
}

Supported operations:

• Token swaps (any ERC-20)
• Token purchases with fiat
• Balance displays
• Price feeds

Reference: references/token-operations.md

4. Transaction Building

Create and execute blockchain transactions:

import { Transaction, TransactionButton } from '@coinbase/onchainkit/transaction';

function SendTransaction({ calls }) {
  return (
    <Transaction calls={calls}>
      <TransactionButton />
    </Transaction>
  );
}

Reference: references/transactions.md

5. Payment Processing

Build checkout flows and payment processing:

import { Checkout, CheckoutButton } from '@coinbase/onchainkit/checkout';

function PaymentFlow() {
  return (
    <Checkout>
      <CheckoutButton />
    </Checkout>
  );
}

Reference: references/payments.md

6. NFT Integration

Display, mint, and manage NFTs:

import { NFTCard } from '@coinbase/onchainkit/nft';

function NFTDisplay({ contract, tokenId }) {
  return <NFTCard contract={contract} tokenId={tokenId} />;
}

Reference: references/nft-integration.md

Common Workflows

Setting Up a Complete App

1. Initialize project with create-onchain-app.py 2. Configure providers using setup templates 3. Add wallet connection with Wallet components 4. Implement core features (swap, buy, identity) 5. Test and deploy with validation scripts

Building a Token Swap App

1. Start with swap app template from assets/templates/swap-app/ 2. Configure token lists and supported chains 3. Add wallet connection flow 4. Implement swap interface 5. Add transaction confirmations

Creating an NFT Marketplace

1. Use NFT template from assets/templates/nft-mint/ 2. Set up NFT contract integration 3. Build minting interface 4. Add payment processing 5. Implement collection browsing

Configuration & Setup

Environment Variables

# Required for API access
NEXT_PUBLIC_CDP_API_KEY="your-api-key"
NEXT_PUBLIC_WC_PROJECT_ID="your-walletconnect-id"

# Optional configurations
NEXT_PUBLIC_CHAIN_ID="8453" # Base mainnet

Reference: references/configuration.md

Provider Setup

OnchainKit requires proper React provider configuration:

import { OnchainKitProvider } from '@coinbase/onchainkit';
import { WagmiProvider } from 'wagmi';

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <OnchainKitProvider
        apiKey={process.env.NEXT_PUBLIC_CDP_API_KEY}
        chain={base}
      >
        {/* Your app components */}
      </OnchainKitProvider>
    </WagmiProvider>
  );
}

Component Patterns

Progressive Enhancement

Start simple, add features as needed:

// Basic wallet connection
<ConnectWallet />

// Enhanced with custom styling
<ConnectWallet className="custom-wallet-button" />

// Full wallet interface with status
<Wallet>
  <ConnectWallet />
  <WalletDropdown>
    <Identity />
    <WalletDropdownDisconnect />
  </WalletDropdown>
</Wallet>

Composable Architecture

Mix and match components for custom workflows:

function CustomApp() {
  return (
    <div>
      {/* User identity */}
      <Identity address={address}>
        <Avatar />
        <Name />
      </Identity>
      
      {/* Token operations */}
      <Swap>
        <SwapAmountInput />
        <SwapButton />
      </Swap>
      
      {/* Payment processing */}
      <Checkout>
        <CheckoutButton />
      </Checkout>
    </div>
  );
}

Best Practices

Performance

• Use component-level imports: import { Wallet } from '@coinbase/onchainkit/wallet'
• Implement proper loading states
• Cache API responses appropriately
• Optimize for mobile experiences

Security

• Never expose private keys in client code
• Validate all transaction parameters
• Use official OnchainKit providers
• Implement proper error boundaries

User Experience

• Provide clear transaction confirmations
• Show loading states during blockchain operations
• Handle wallet connection failures gracefully
• Support multiple wallet types

Reference: references/best-practices.md

Troubleshooting

Common Issues

• Wallet connection fails: Check WalletConnect configuration
• API errors: Verify API key and network settings
• Transaction reverts: Validate contract calls and gas limits
• Styling issues: Import OnchainKit CSS properly

Debug Steps

1. Check browser console for errors 2. Verify environment variables 3. Test with different wallets 4. Use validation script to check setup

Reference: references/troubleshooting.md

Templates & Examples

Quick Start Templates

• Basic App: assets/templates/basic-app/ - Minimal onchain app
• Token Swap: assets/templates/swap-app/ - Complete swap interface
• NFT Minting: assets/templates/nft-mint/ - NFT marketplace
• Commerce: assets/templates/commerce/ - Onchain store

Real-World Examples

• Wallet connection with identity display
• Multi-token swap interface
• NFT collection with minting
• Payment processing with receipts

Reference: references/examples.md

Advanced Features

Custom Chains

Support additional EVM chains beyond Base:

const customChain = {
  id: 123456,
  name: 'Custom Chain',
  // ... chain configuration
};

<OnchainKitProvider chain={customChain}>

MiniKit Integration

Build Farcaster Frame applications:

import { useMiniKit } from '@coinbase/onchainkit/minikit';

function FrameApp() {
  const { isReady } = useMiniKit();
  return isReady ? <YourFrameContent /> : <Loading />;
}

Reference: references/advanced-features.md

API Reference

OnchainKit provides both React components and utility functions:

• Components: Pre-built UI components for common onchain operations
• Hooks: React hooks for blockchain state management
• Utilities: TypeScript utilities for data formatting and validation
• Types: Complete TypeScript definitions

Reference: references/api-reference.md

Resources

Documentation

• Official docs: onchainkit.xyz
• GitHub: github.com/coinbase/onchainkit
• Examples: OnchainKit playground

Support

• Discord: Coinbase Developer Platform
• Twitter: @OnchainKit

---

💡 Pro Tip: Start with npm create onchain to bootstrap a working app, then customize components as needed. The quickstart template includes all necessary configuration and examples.

🚀 Quick Win: Use the validation script after setup to ensure everything is working correctly before building custom features.

Basic OnchainKit App Template

A minimal OnchainKit application with wallet connection and identity display.

Features

• Wallet connection (Coinbase Wallet, MetaMask, WalletConnect)
• User identity display (ENS name, avatar, address)
• Basic onchain interactions
• Responsive design
• TypeScript support

Quick Start

1. Copy this template to your project directory 2. Install dependencies: npm install 3. Copy .env.local.example to .env.local and add your API keys 4. Run the development server: npm run dev

File Structure

basic-app/
├── pages/
│   ├── _app.tsx          # Next.js app with providers
│   └── index.tsx         # Main page
├── components/
│   ├── WalletSection.tsx # Wallet connection component
│   └── UserProfile.tsx   # User identity display
├── lib/
│   ├── providers.tsx     # OnchainKit providers setup
│   └── wagmi.ts          # Wagmi configuration
├── styles/
│   └── globals.css       # Global styles with OnchainKit theme
├── .env.local.example    # Environment variables template
├── next.config.js        # Next.js configuration
├── package.json          # Dependencies
└── tsconfig.json         # TypeScript configuration

Customization

Adding More Features

• Token swaps: Add Swap components
• NFT display: Add NFT components
• Transactions: Add Transaction components
• Payments: Add Checkout components

Styling

• Modify CSS variables in globals.css
• Update component classes
• Add custom themes

Chain Configuration

• Update chain in lib/wagmi.ts
• Add more chains as needed
• Configure custom RPC endpoints

OnchainKit Configuration Reference

Complete configuration guide for OnchainKit applications.

Environment Variables

Required Variables

# Coinbase Developer Platform API Key
# Get from: https://portal.cdp.coinbase.com/
NEXT_PUBLIC_CDP_API_KEY=your-api-key-here

# WalletConnect Project ID
# Get from: https://cloud.walletconnect.com/
NEXT_PUBLIC_WC_PROJECT_ID=your-walletconnect-project-id

Optional Variables

# Chain configuration (default: Base mainnet)
NEXT_PUBLIC_CHAIN_ID=8453

# OnchainKit Analytics (default: false)
NEXT_PUBLIC_ONCHAINKIT_ANALYTICS=true

# Custom RPC URL (optional)
NEXT_PUBLIC_RPC_URL=https://your-custom-rpc-endpoint.com

# App metadata
NEXT_PUBLIC_APP_NAME="My OnchainKit App"
NEXT_PUBLIC_APP_DESCRIPTION="Built with OnchainKit"
NEXT_PUBLIC_APP_URL="https://myapp.com"
NEXT_PUBLIC_APP_ICON="https://myapp.com/icon.png"

Environment Setup Example

# .env.local
NEXT_PUBLIC_CDP_API_KEY=pk_live_1234567890abcdef
NEXT_PUBLIC_WC_PROJECT_ID=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
NEXT_PUBLIC_CHAIN_ID=8453
NEXT_PUBLIC_ONCHAINKIT_ANALYTICS=true
NEXT_PUBLIC_APP_NAME="My DeFi App"

Provider Configuration

Basic Provider Setup

// providers.tsx
import { OnchainKitProvider } from '@coinbase/onchainkit';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { base } from 'wagmi/chains';
import { WagmiProvider } from 'wagmi';
import { getConfig } from './wagmi';

const queryClient = new QueryClient();

interface ProvidersProps {
  children: React.ReactNode;
}

export function Providers({ children }: ProvidersProps) {
  return (
    <WagmiProvider config={getConfig()}>
      <QueryClientProvider client={queryClient}>
        <OnchainKitProvider
          apiKey={process.env.NEXT_PUBLIC_CDP_API_KEY}
          chain={base}
          schemaId="0xf8b05c79f090979bf4a80270aba232dff11a10d9ca55c4f88de95317970f0de9"
        >
          {children}
        </OnchainKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Advanced Provider Configuration

import { OnchainKitProvider } from '@coinbase/onchainkit';
import { base, mainnet, polygon } from 'wagmi/chains';

export function AdvancedProviders({ children }: ProvidersProps) {
  return (
    <WagmiProvider config={getConfig()}>
      <QueryClientProvider client={queryClient}>
        <OnchainKitProvider
          apiKey={process.env.NEXT_PUBLIC_CDP_API_KEY}
          chain={base}
          schemaId="0xf8b05c79f090979bf4a80270aba232dff11a10d9ca55c4f88de95317970f0de9"
          config={{
            appearance: {
              mode: 'auto', // 'light' | 'dark' | 'auto'
              theme: 'default', // 'default' | 'hacker' | 'cyberpunk'
            },
            wallet: {
              display: 'modal', // 'modal' | 'embedded'
            },
          }}
        >
          {children}
        </OnchainKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Wagmi Configuration

Basic Wagmi Config

// wagmi.ts
import { http, createConfig } from 'wagmi';
import { base } from 'wagmi/chains';
import { coinbaseWallet, metaMask, walletConnect } from 'wagmi/connectors';

export function getConfig() {
  return createConfig({
    chains: [base],
    connectors: [
      coinbaseWallet({
        appName: process.env.NEXT_PUBLIC_APP_NAME || 'OnchainKit App',
        preference: 'all',
      }),
      metaMask(),
      walletConnect({
        projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
      }),
    ],
    ssr: true,
    transports: {
      [base.id]: http(),
    },
  });
}

declare module 'wagmi' {
  interface Register {
    config: ReturnType<typeof getConfig>;
  }
}

Multi-Chain Configuration

import { http, createConfig } from 'wagmi';
import { base, mainnet, polygon, arbitrum, optimism } from 'wagmi/chains';

export function getMultiChainConfig() {
  return createConfig({
    chains: [base, mainnet, polygon, arbitrum, optimism],
    connectors: [
      coinbaseWallet({
        appName: process.env.NEXT_PUBLIC_APP_NAME || 'OnchainKit App',
        preference: 'all',
      }),
      metaMask(),
      walletConnect({
        projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
        metadata: {
          name: process.env.NEXT_PUBLIC_APP_NAME || 'OnchainKit App',
          description: process.env.NEXT_PUBLIC_APP_DESCRIPTION || '',
          url: process.env.NEXT_PUBLIC_APP_URL || '',
          icons: [process.env.NEXT_PUBLIC_APP_ICON || ''],
        },
      }),
    ],
    ssr: true,
    transports: {
      [base.id]: http(process.env.NEXT_PUBLIC_RPC_URL_BASE),
      [mainnet.id]: http(process.env.NEXT_PUBLIC_RPC_URL_MAINNET),
      [polygon.id]: http(process.env.NEXT_PUBLIC_RPC_URL_POLYGON),
      [arbitrum.id]: http(process.env.NEXT_PUBLIC_RPC_URL_ARBITRUM),
      [optimism.id]: http(process.env.NEXT_PUBLIC_RPC_URL_OPTIMISM),
    },
  });
}

Custom Chain Configuration

import { defineChain } from 'viem';

export const customChain = defineChain({
  id: 123456,
  name: 'Custom Chain',
  network: 'custom',
  nativeCurrency: {
    decimals: 18,
    name: 'Custom Token',
    symbol: 'CUSTOM',
  },
  rpcUrls: {
    public: { http: ['https://rpc.customchain.com'] },
    default: { http: ['https://rpc.customchain.com'] },
  },
  blockExplorers: {
    etherscan: { name: 'CustomScan', url: 'https://scan.customchain.com' },
    default: { name: 'CustomScan', url: 'https://scan.customchain.com' },
  },
});

// Use in config
export function getCustomConfig() {
  return createConfig({
    chains: [base, customChain],
    // ... other config
  });
}

Theme and Styling

CSS Variables

/* globals.css */
:root {
  --ock-bg-default: #ffffff;
  --ock-bg-default-hover: #f8f9fa;
  --ock-bg-alternate: #f1f3f4;
  --ock-bg-alternate-hover: #e8eaed;
  --ock-bg-inverse: #1a1b23;
  --ock-bg-primary: #0052ff;
  --ock-bg-primary-hover: #0040cc;
  --ock-bg-primary-active: #002999;
  --ock-bg-secondary: #e8eaed;
  --ock-bg-secondary-hover: #d2d5da;
  --ock-bg-secondary-active: #bcc0c7;
  
  /* Text colors */
  --ock-text-primary: #1a1b23;
  --ock-text-secondary: #5b616e;
  --ock-text-disabled: #8b92a5;
  --ock-text-inverse: #ffffff;
  --ock-text-error: #d73a49;
  --ock-text-success: #28a745;
  
  /* Border colors */
  --ock-border-default: #e8eaed;
  --ock-border-active: #0052ff;
  
  /* Border radius */
  --ock-border-radius: 8px;
}

[data-theme='dark'] {
  --ock-bg-default: #1a1b23;
  --ock-bg-default-hover: #2d3748;
  --ock-text-primary: #ffffff;
  --ock-text-secondary: #a0aec0;
}

Custom Component Styling

import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
import './custom-wallet.css';

function CustomStyledWallet() {
  return (
    <Wallet className="custom-wallet">
      <ConnectWallet 
        className="custom-connect-button"
        text="Connect Wallet"
      />
    </Wallet>
  );
}

/* custom-wallet.css */
.custom-wallet {
  border-radius: 16px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  padding: 2px;
}

.custom-connect-button {
  background: white;
  color: #1a1b23;
  border-radius: 14px;
  font-weight: 600;
  transition: all 0.2s ease;
}

.custom-connect-button:hover {
  transform: translateY(-1px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

API Configuration

Coinbase Developer Platform Setup

1. Visit https://portal.cdp.coinbase.com/ 2. Create an account or sign in 3. Create a new project 4. Generate an API key 5. Copy the key to your environment variables

WalletConnect Setup

1. Visit https://cloud.walletconnect.com/ 2. Create an account or sign in 3. Create a new project 4. Get the Project ID 5. Add your app metadata (name, description, URL, icon) 6. Copy the Project ID to your environment variables

RPC Configuration

// Using Alchemy
const alchemyConfig = {
  [base.id]: http(`https://base-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`),
  [mainnet.id]: http(`https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`),
};

// Using Infura
const infuraConfig = {
  [base.id]: http(`https://base-mainnet.infura.io/v3/${process.env.INFURA_PROJECT_ID}`),
  [mainnet.id]: http(`https://mainnet.infura.io/v3/${process.env.INFURA_PROJECT_ID}`),
};

// Using public RPCs (not recommended for production)
const publicConfig = {
  [base.id]: http(),
  [mainnet.id]: http(),
};

Next.js Configuration

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    esmExternals: true,
  },
  webpack: (config) => {
    config.resolve.fallback = {
      fs: false,
      net: false,
      tls: false,
    };
    
    config.externals.push('pino-pretty', 'lokijs', 'encoding');
    
    return config;
  },
  env: {
    NEXT_PUBLIC_CDP_API_KEY: process.env.NEXT_PUBLIC_CDP_API_KEY,
    NEXT_PUBLIC_WC_PROJECT_ID: process.env.NEXT_PUBLIC_WC_PROJECT_ID,
  },
};

module.exports = nextConfig;

TypeScript Configuration

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts"
  ],
  "exclude": ["node_modules"]
}

Security Configuration

Environment Variable Security

# Never commit these to version control
# Use .env.local for local development
# Use platform environment variables for production

# Development
NEXT_PUBLIC_CDP_API_KEY=pk_test_...
NEXT_PUBLIC_WC_PROJECT_ID=test_project_id

# Production
NEXT_PUBLIC_CDP_API_KEY=pk_live_...
NEXT_PUBLIC_WC_PROJECT_ID=production_project_id

Content Security Policy

// next.config.js
const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: [
              "default-src 'self'",
              "script-src 'self' 'unsafe-eval' 'unsafe-inline' https://vercel.live",
              "style-src 'self' 'unsafe-inline'",
              "img-src 'self' data: https:",
              "font-src 'self' data:",
              "connect-src 'self' https: wss:",
            ].join('; '),
          },
        ],
      },
    ];
  },
};

Development vs Production

Development Configuration

// Development with detailed logging
const developmentConfig = {
  apiKey: process.env.NEXT_PUBLIC_CDP_API_KEY,
  chain: base,
  config: {
    appearance: {
      mode: 'light',
    },
    wallet: {
      display: 'modal',
    },
  },
  // Enable verbose logging in development
  debug: process.env.NODE_ENV === 'development',
};

Production Configuration

// Production with optimizations
const productionConfig = {
  apiKey: process.env.NEXT_PUBLIC_CDP_API_KEY,
  chain: base,
  config: {
    appearance: {
      mode: 'auto',
    },
    wallet: {
      display: 'modal',
    },
  },
  // Disable debugging in production
  debug: false,
};

Configuration Validation

Environment Validation

function validateEnvironment() {
  const requiredEnvVars = [
    'NEXT_PUBLIC_CDP_API_KEY',
    'NEXT_PUBLIC_WC_PROJECT_ID',
  ];

  const missing = requiredEnvVars.filter(
    (envVar) => !process.env[envVar]
  );

  if (missing.length > 0) {
    throw new Error(
      `Missing required environment variables: ${missing.join(', ')}`
    );
  }

  // Validate API key format
  const apiKey = process.env.NEXT_PUBLIC_CDP_API_KEY;
  if (apiKey && !apiKey.startsWith('pk_')) {
    console.warn('CDP API key should start with "pk_"');
  }

  return true;
}

// Use in your app initialization
validateEnvironment();

Runtime Configuration Check

import { useOnchainKit } from '@coinbase/onchainkit';

function ConfigurationStatus() {
  const { config } = useOnchainKit();
  
  return (
    <div className="p-4 bg-gray-100 rounded">
      <h3>Configuration Status</h3>
      <p>API Key: {config.apiKey ? '✅ Configured' : '❌ Missing'}</p>
      <p>Chain: {config.chain.name}</p>
      <p>Schema ID: {config.schemaId ? '✅ Set' : '⚠️ Default'}</p>
    </div>
  );
}

OnchainKit Examples

Real-world implementation examples and common use cases.

Complete App Examples

1. DeFi Portfolio Tracker

A comprehensive app that tracks user's DeFi positions and allows token swaps.

// pages/portfolio.tsx
import { useAccount, useBalance } from 'wagmi';
import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
import { Identity, Avatar, Name } from '@coinbase/onchainkit/identity';
import { Swap } from '@coinbase/onchainkit/swap';

function PortfolioPage() {
  const { address, isConnected } = useAccount();

  if (!isConnected) {
    return (
      <div className="min-h-screen flex items-center justify-center">
        <div className="text-center">
          <h1 className="text-2xl font-bold mb-4">DeFi Portfolio Tracker</h1>
          <p className="text-gray-600 mb-6">Connect your wallet to get started</p>
          <Wallet>
            <ConnectWallet />
          </Wallet>
        </div>
      </div>
    );
  }

  return (
    <div className="min-h-screen bg-gray-50">
      <header className="bg-white shadow-sm">
        <div className="max-w-7xl mx-auto px-4 py-4 flex justify-between items-center">
          <h1 className="text-xl font-bold">Portfolio</h1>
          <Wallet>
            <ConnectWallet>
              <Avatar className="h-6 w-6" />
              <Name />
            </ConnectWallet>
          </Wallet>
        </div>
      </header>

      <main className="max-w-7xl mx-auto px-4 py-8">
        <div className="grid grid-cols-1 lg:grid-cols-3 gap-8">
          <div className="lg:col-span-2">
            <PortfolioOverview address={address} />
            <TokenBalances address={address} />
          </div>
          <div>
            <SwapInterface />
          </div>
        </div>
      </main>
    </div>
  );
}

function PortfolioOverview({ address }) {
  const { data: ethBalance } = useBalance({ address });
  const { data: usdcBalance } = useBalance({
    address,
    token: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
  });

  const totalValue = calculateTotalValue(ethBalance, usdcBalance);

  return (
    <div className="bg-white rounded-lg shadow p-6 mb-6">
      <h2 className="text-lg font-semibold mb-4">Portfolio Overview</h2>
      <div className="grid grid-cols-2 gap-4">
        <div>
          <p className="text-sm text-gray-500">Total Value</p>
          <p className="text-2xl font-bold">${totalValue.toFixed(2)}</p>
        </div>
        <div>
          <p className="text-sm text-gray-500">Assets</p>
          <p className="text-2xl font-bold">2</p>
        </div>
      </div>
    </div>
  );
}

function SwapInterface() {
  return (
    <div className="bg-white rounded-lg shadow p-6">
      <h2 className="text-lg font-semibold mb-4">Quick Swap</h2>
      <Swap>
        {/* Swap components */}
      </Swap>
    </div>
  );
}

2. NFT Marketplace

An NFT marketplace with minting and trading capabilities.

// pages/marketplace.tsx
import { useState } from 'react';
import { NFTCard } from '@coinbase/onchainkit/nft';
import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
import { Transaction, TransactionButton } from '@coinbase/onchainkit/transaction';

interface NFT {
  contract: `0x${string}`;
  tokenId: string;
  name: string;
  image: string;
  price?: string;
}

function MarketplacePage() {
  const [selectedNFT, setSelectedNFT] = useState<NFT | null>(null);
  const [nfts, setNfts] = useState<NFT[]>([
    // Sample NFTs
    {
      contract: '0x...',
      tokenId: '1',
      name: 'Cool NFT #1',
      image: '/nft1.png',
      price: '0.1',
    },
    // ... more NFTs
  ]);

  return (
    <div className="min-h-screen bg-gray-50">
      <header className="bg-white shadow-sm">
        <div className="max-w-7xl mx-auto px-4 py-4 flex justify-between items-center">
          <h1 className="text-xl font-bold">NFT Marketplace</h1>
          <Wallet>
            <ConnectWallet />
          </Wallet>
        </div>
      </header>

      <main className="max-w-7xl mx-auto px-4 py-8">
        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
          {nfts.map((nft, index) => (
            <NFTCard
              key={`${nft.contract}-${nft.tokenId}`}
              contract={nft.contract}
              tokenId={nft.tokenId}
              onClick={() => setSelectedNFT(nft)}
            />
          ))}
        </div>

        {selectedNFT && (
          <NFTModal
            nft={selectedNFT}
            onClose={() => setSelectedNFT(null)}
          />
        )}
      </main>
    </div>
  );
}

function NFTModal({ nft, onClose }: { nft: NFT; onClose: () => void }) {
  return (
    <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center p-4">
      <div className="bg-white rounded-lg p-6 max-w-md w-full">
        <div className="flex justify-between items-center mb-4">
          <h2 className="text-xl font-bold">{nft.name}</h2>
          <button onClick={onClose} className="text-gray-500 hover:text-gray-700">
            ×
          </button>
        </div>

        <NFTCard contract={nft.contract} tokenId={nft.tokenId} />

        {nft.price && (
          <div className="mt-4">
            <p className="text-lg font-semibold mb-2">Price: {nft.price} ETH</p>
            <Transaction
              calls={[{
                to: nft.contract,
                data: '0x...', // Purchase function call
                value: parseEther(nft.price),
              }]}
            >
              <TransactionButton text={`Buy for ${nft.price} ETH`} />
            </Transaction>
          </div>
        )}
      </div>
    </div>
  );
}

3. Token Launchpad

A platform for launching and trading new tokens.

// pages/launchpad.tsx
import { useState } from 'react';
import { useAccount } from 'wagmi';
import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
import { Transaction, TransactionButton } from '@coinbase/onchainkit/transaction';
import { Buy } from '@coinbase/onchainkit/buy';

function LaunchpadPage() {
  const { isConnected } = useAccount();
  const [newTokens, setNewTokens] = useState([
    {
      address: '0x...',
      name: 'NewToken',
      symbol: 'NEW',
      description: 'An innovative new token',
      totalSupply: '1000000',
      price: '0.001',
    },
    // ... more tokens
  ]);

  return (
    <div className="min-h-screen bg-gray-50">
      <header className="bg-white shadow-sm">
        <div className="max-w-7xl mx-auto px-4 py-4 flex justify-between items-center">
          <h1 className="text-xl font-bold">Token Launchpad</h1>
          <div className="flex gap-4">
            <button className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600">
              Launch Token
            </button>
            <Wallet>
              <ConnectWallet />
            </Wallet>
          </div>
        </div>
      </header>

      <main className="max-w-7xl mx-auto px-4 py-8">
        <div className="mb-8">
          <h2 className="text-2xl font-bold mb-4">Featured Launches</h2>
          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
            {newTokens.map((token, index) => (
              <TokenCard key={token.address} token={token} />
            ))}
          </div>
        </div>

        {isConnected && <LaunchTokenForm />}
      </main>
    </div>
  );
}

function TokenCard({ token }) {
  return (
    <div className="bg-white rounded-lg shadow p-6">
      <h3 className="text-lg font-semibold mb-2">{token.name} ({token.symbol})</h3>
      <p className="text-gray-600 mb-4">{token.description}</p>
      <div className="grid grid-cols-2 gap-4 text-sm text-gray-500 mb-4">
        <div>
          <p>Total Supply</p>
          <p className="font-semibold">{token.totalSupply}</p>
        </div>
        <div>
          <p>Price</p>
          <p className="font-semibold">{token.price} ETH</p>
        </div>
      </div>
      <Buy>
        <BuyAmountInput token={token} />
        <BuyButton />
      </Buy>
    </div>
  );
}

Component Integration Examples

1. Multi-Step Onboarding Flow

import { useState } from 'react';
import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
import { Identity, Avatar, Name } from '@coinbase/onchainkit/identity';
import { Fund } from '@coinbase/onchainkit/fund';

function OnboardingFlow() {
  const [step, setStep] = useState(1);
  const { isConnected } = useAccount();

  const steps = [
    { title: 'Connect Wallet', component: <WalletStep /> },
    { title: 'Fund Account', component: <FundingStep /> },
    { title: 'Complete Setup', component: <CompletionStep /> },
  ];

  return (
    <div className="max-w-md mx-auto">
      <div className="mb-8">
        <div className="flex justify-between items-center mb-4">
          {steps.map((_, index) => (
            <div
              key={index}
              className={`w-8 h-8 rounded-full flex items-center justify-center ${
                index + 1 <= step 
                  ? 'bg-blue-500 text-white' 
                  : 'bg-gray-200 text-gray-500'
              }`}
            >
              {index + 1}
            </div>
          ))}
        </div>
        <div className="w-full bg-gray-200 rounded-full h-2">
          <div 
            className="bg-blue-500 h-2 rounded-full transition-all duration-300"
            style={{ width: `${(step / steps.length) * 100}%` }}
          />
        </div>
      </div>

      <div className="bg-white rounded-lg shadow p-6">
        <h2 className="text-xl font-bold mb-4">{steps[step - 1].title}</h2>
        {steps[step - 1].component}
      </div>
    </div>
  );
}

function WalletStep() {
  return (
    <div className="text-center">
      <p className="text-gray-600 mb-6">Connect your wallet to get started</p>
      <Wallet>
        <ConnectWallet />
      </Wallet>
    </div>
  );
}

function FundingStep() {
  return (
    <div>
      <p className="text-gray-600 mb-6">Add funds to your wallet to start trading</p>
      <Fund>
        <FundButton />
      </Fund>
    </div>
  );
}

2. Advanced Swap Interface with Settings

import { useState } from 'react';
import {
  Swap,
  SwapAmountInput,
  SwapToggleButton,
  SwapButton,
  SwapSettings,
  SwapMessage,
} from '@coinbase/onchainkit/swap';

function AdvancedSwapInterface() {
  const [showSettings, setShowSettings] = useState(false);
  const [slippage, setSlippage] = useState(0.5);
  const [deadline, setDeadline] = useState(20);

  return (
    <div className="bg-white rounded-lg shadow p-6 max-w-md mx-auto">
      <div className="flex justify-between items-center mb-4">
        <h2 className="text-lg font-semibold">Swap Tokens</h2>
        <button
          onClick={() => setShowSettings(!showSettings)}
          className="text-gray-500 hover:text-gray-700"
        >
          ⚙️
        </button>
      </div>

      {showSettings && (
        <div className="mb-4 p-4 bg-gray-50 rounded-lg">
          <div className="mb-3">
            <label className="block text-sm font-medium mb-1">
              Slippage Tolerance
            </label>
            <div className="flex gap-2">
              {[0.1, 0.5, 1.0].map((value) => (
                <button
                  key={value}
                  onClick={() => setSlippage(value)}
                  className={`px-3 py-1 rounded ${
                    slippage === value
                      ? 'bg-blue-500 text-white'
                      : 'bg-white border'
                  }`}
                >
                  {value}%
                </button>
              ))}
              <input
                type="number"
                value={slippage}
                onChange={(e) => setSlippage(Number(e.target.value))}
                className="w-16 px-2 py-1 border rounded text-center"
                step="0.1"
              />
            </div>
          </div>

          <div>
            <label className="block text-sm font-medium mb-1">
              Transaction Deadline
            </label>
            <input
              type="number"
              value={deadline}
              onChange={(e) => setDeadline(Number(e.target.value))}
              className="w-20 px-2 py-1 border rounded"
            />
            <span className="ml-2 text-sm text-gray-500">minutes</span>
          </div>
        </div>
      )}

      <Swap
        config={{
          maxSlippage: slippage,
          transactionDeadlineMinutes: deadline,
        }}
      >
        <SwapAmountInput
          label="From"
          swappableTokens={swappableTokens}
          token={swappableTokens[0]}
          type="from"
        />
        <SwapToggleButton />
        <SwapAmountInput
          label="To"
          swappableTokens={swappableTokens}
          token={swappableTokens[1]}
          type="to"
        />
        <SwapButton />
        <SwapMessage />
      </Swap>
    </div>
  );
}

3. Social Trading Dashboard

import { useAccount } from 'wagmi';
import { Identity, Avatar, Name, Badge } from '@coinbase/onchainkit/identity';
import { Swap } from '@coinbase/onchainkit/swap';

interface Trader {
  address: `0x${string}`;
  followers: number;
  roi: number;
  recentTrade: {
    from: string;
    to: string;
    amount: string;
    timestamp: Date;
  };
}

function SocialTradingDashboard() {
  const [topTraders, setTopTraders] = useState<Trader[]>([
    {
      address: '0x...',
      followers: 1250,
      roi: 45.2,
      recentTrade: {
        from: 'ETH',
        to: 'USDC',
        amount: '2.5',
        timestamp: new Date(),
      },
    },
    // ... more traders
  ]);

  return (
    <div className="min-h-screen bg-gray-50">
      <main className="max-w-7xl mx-auto px-4 py-8">
        <div className="grid grid-cols-1 lg:grid-cols-3 gap-8">
          <div className="lg:col-span-2">
            <h2 className="text-xl font-bold mb-4">Top Traders</h2>
            <div className="space-y-4">
              {topTraders.map((trader, index) => (
                <TraderCard key={trader.address} trader={trader} rank={index + 1} />
              ))}
            </div>
          </div>
          <div>
            <div className="bg-white rounded-lg shadow p-6">
              <h3 className="text-lg font-semibold mb-4">Quick Trade</h3>
              <Swap>
                {/* Swap interface */}
              </Swap>
            </div>
          </div>
        </div>
      </main>
    </div>
  );
}

function TraderCard({ trader, rank }: { trader: Trader; rank: number }) {
  const [isFollowing, setIsFollowing] = useState(false);

  return (
    <div className="bg-white rounded-lg shadow p-6">
      <div className="flex items-center justify-between mb-4">
        <div className="flex items-center gap-3">
          <span className="text-2xl font-bold text-gray-300">#{rank}</span>
          <Identity address={trader.address}>
            <Avatar className="h-10 w-10" />
            <div>
              <Name className="font-medium" />
              <Badge />
            </div>
          </Identity>
        </div>
        <button
          onClick={() => setIsFollowing(!isFollowing)}
          className={`px-4 py-2 rounded-full text-sm font-medium ${
            isFollowing
              ? 'bg-gray-200 text-gray-700 hover:bg-gray-300'
              : 'bg-blue-500 text-white hover:bg-blue-600'
          }`}
        >
          {isFollowing ? 'Following' : 'Follow'}
        </button>
      </div>

      <div className="grid grid-cols-3 gap-4 text-center mb-4">
        <div>
          <p className="text-sm text-gray-500">Followers</p>
          <p className="font-bold">{trader.followers}</p>
        </div>
        <div>
          <p className="text-sm text-gray-500">ROI</p>
          <p className={`font-bold ${trader.roi > 0 ? 'text-green-500' : 'text-red-500'}`}>
            {trader.roi > 0 ? '+' : ''}{trader.roi}%
          </p>
        </div>
        <div>
          <p className="text-sm text-gray-500">Trades</p>
          <p className="font-bold">247</p>
        </div>
      </div>

      <div className="border-t pt-4">
        <p className="text-sm text-gray-500 mb-2">Recent Trade</p>
        <div className="flex items-center justify-between">
          <span className="text-sm">
            {trader.recentTrade.amount} {trader.recentTrade.from} → {trader.recentTrade.to}
          </span>
          <span className="text-xs text-gray-500">
            {trader.recentTrade.timestamp.toLocaleTimeString()}
          </span>
        </div>
      </div>
    </div>
  );
}

Utility and Helper Examples

1. Token Price Tracking

import { useQuery } from '@tanstack/react-query';
import { Token } from '@coinbase/onchainkit/token';

function useTokenPrice(token: Token) {
  return useQuery({
    queryKey: ['tokenPrice', token.address],
    queryFn: async () => {
      const response = await fetch(`/api/price/${token.address}`);
      return response.json();
    },
    refetchInterval: 30000, // Refetch every 30 seconds
  });
}

function TokenPriceTracker({ tokens }: { tokens: Token[] }) {
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
      {tokens.map((token) => (
        <TokenPriceCard key={token.address} token={token} />
      ))}
    </div>
  );
}

function TokenPriceCard({ token }: { token: Token }) {
  const { data: price, isLoading } = useTokenPrice(token);
  const [priceHistory, setPriceHistory] = useState([]);

  useEffect(() => {
    if (price) {
      setPriceHistory(prev => [...prev.slice(-23), price]);
    }
  }, [price]);

  return (
    <div className="bg-white rounded-lg shadow p-4">
      <div className="flex items-center gap-2 mb-2">
        <img src={token.image} alt={token.symbol} className="w-6 h-6 rounded-full" />
        <span className="font-medium">{token.symbol}</span>
      </div>
      
      {isLoading ? (
        <div className="animate-pulse bg-gray-200 h-6 rounded"></div>
      ) : (
        <>
          <p className="text-2xl font-bold">${price?.current}</p>
          <p className={`text-sm ${price?.change24h > 0 ? 'text-green-500' : 'text-red-500'}`}>
            {price?.change24h > 0 ? '+' : ''}{price?.change24h}%
          </p>
          <div className="mt-2 h-16 bg-gray-50 rounded">
            <MiniChart data={priceHistory} />
          </div>
        </>
      )}
    </div>
  );
}

2. Transaction History

import { useAccount } from 'wagmi';
import { Identity, Avatar, Name } from '@coinbase/onchainkit/identity';

function TransactionHistory() {
  const { address } = useAccount();
  const [transactions, setTransactions] = useState([]);

  useEffect(() => {
    if (address) {
      fetchTransactionHistory(address).then(setTransactions);
    }
  }, [address]);

  return (
    <div className="bg-white rounded-lg shadow">
      <div className="p-6 border-b">
        <h2 className="text-lg font-semibold">Recent Transactions</h2>
      </div>
      
      <div className="divide-y">
        {transactions.map((tx, index) => (
          <TransactionItem key={tx.hash} transaction={tx} />
        ))}
      </div>
    </div>
  );
}

function TransactionItem({ transaction }) {
  const getTransactionIcon = (type) => {
    switch (type) {
      case 'swap': return '🔄';
      case 'send': return '↗️';
      case 'receive': return '↘️';
      case 'approve': return '✅';
      default: return '📋';
    }
  };

  return (
    <div className="p-4 hover:bg-gray-50">
      <div className="flex items-center justify-between">
        <div className="flex items-center gap-3">
          <span className="text-2xl">{getTransactionIcon(transaction.type)}</span>
          <div>
            <p className="font-medium capitalize">{transaction.type}</p>
            <p className="text-sm text-gray-500">
              {new Date(transaction.timestamp).toLocaleString()}
            </p>
          </div>
        </div>
        
        <div className="text-right">
          <p className="font-medium">{transaction.value} {transaction.symbol}</p>
          <a
            href={`https://basescan.org/tx/${transaction.hash}`}
            target="_blank"
            rel="noopener noreferrer"
            className="text-sm text-blue-500 hover:underline"
          >
            View on Explorer ↗
          </a>
        </div>
      </div>
    </div>
  );
}

These examples show real-world implementations that users can adapt for their specific needs, demonstrating best practices for component composition, state management, and user experience.

Token Operations Reference

Complete guide for token swaps, purchases, and management with OnchainKit.

Token Swaps

Basic Swap Interface

import {
  Swap,
  SwapAmountInput,
  SwapToggleButton,
  SwapButton,
  SwapMessage,
  SwapToast,
} from '@coinbase/onchainkit/swap';
import { Token } from '@coinbase/onchainkit/token';

const swappableTokens: Token[] = [
  {
    address: '', // ETH
    chainId: 8453,
    decimals: 18,
    name: 'Ethereum',
    symbol: 'ETH',
    image: 'https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png',
  },
  {
    address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC
    chainId: 8453,
    decimals: 6,
    name: 'USD Coin',
    symbol: 'USDC',
    image: 'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/44/2b/442b80bd16af0c0d9b22e03a16753823fe826e5bfd457292b55fa0ba8c1ba213-ZWUzYjJmZGUtMDYxNy00NDcyLTg0NjQtMWI4OGEwYjBiODE2',
  },
];

function TokenSwap() {
  return (
    <div className="w-full max-w-md">
      <Swap>
        <SwapAmountInput
          label="Sell"
          swappableTokens={swappableTokens}
          token={swappableTokens[0]}
          type="from"
        />
        <SwapToggleButton />
        <SwapAmountInput
          label="Buy"
          swappableTokens={swappableTokens}
          token={swappableTokens[1]}
          type="to"
        />
        <SwapButton />
        <SwapMessage />
        <SwapToast />
      </Swap>
    </div>
  );
}

Custom Token Lists

import { Token } from '@coinbase/onchainkit/token';

// Base ecosystem tokens
const baseTokens: Token[] = [
  {
    address: '',
    chainId: 8453,
    decimals: 18,
    name: 'Ethereum',
    symbol: 'ETH',
    image: 'https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png',
  },
  {
    address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    chainId: 8453,
    decimals: 6,
    name: 'USD Coin',
    symbol: 'USDC',
    image: '...',
  },
  {
    address: '0x4200000000000000000000000000000000000006',
    chainId: 8453,
    decimals: 18,
    name: 'Wrapped Ether',
    symbol: 'WETH',
    image: '...',
  },
  {
    address: '0x50c5725949a6f0c72e6c4a641f24049a917db0cb',
    chainId: 8453,
    decimals: 18,
    name: 'Dai Stablecoin',
    symbol: 'DAI',
    image: '...',
  },
];

// Popular meme tokens
const memeTokens: Token[] = [
  {
    address: '0x6921d7a4c0c712b2b29ebf1c3f47e2bab17b87b7',
    chainId: 8453,
    decimals: 18,
    name: 'Based',
    symbol: 'BASED',
    image: '...',
  },
  // Add more meme tokens
];

Swap with Custom Callbacks

import { SwapError } from '@coinbase/onchainkit/swap';

function SwapWithCallbacks() {
  const handleSwapSuccess = (transactionReceipt) => {
    console.log('Swap successful!', transactionReceipt);
    // Track analytics, show success message, etc.
  };

  const handleSwapError = (error: SwapError) => {
    console.error('Swap failed:', error);
    // Show error message, track errors, etc.
  };

  return (
    <Swap
      onSuccess={handleSwapSuccess}
      onError={handleSwapError}
    >
      {/* Swap components */}
    </Swap>
  );
}

Token Purchases

Buy with Fiat

import {
  Buy,
  BuyAmountInput,
  BuyButton,
  BuyMessage,
  BuyToast,
} from '@coinbase/onchainkit/buy';

function TokenPurchase() {
  return (
    <div className="w-full max-w-md">
      <Buy>
        <BuyAmountInput
          label="Buy"
          token={ethToken}
        />
        <BuyButton />
        <BuyMessage />
        <BuyToast />
      </Buy>
    </div>
  );
}

Fund Wallet

import {
  Fund,
  FundButton,
  FundToast,
} from '@coinbase/onchainkit/fund';

function WalletFunding() {
  return (
    <div className="w-full max-w-md">
      <Fund>
        <FundButton />
        <FundToast />
      </Fund>
    </div>
  );
}

Token Display & Information

Token Balance Display

import { TokenBalance } from '@coinbase/onchainkit/token';
import { useAccount } from 'wagmi';

function UserBalance() {
  const { address } = useAccount();

  if (!address) return null;

  return (
    <div className="space-y-2">
      <TokenBalance
        address={address}
        token={{
          address: '',
          chainId: 8453,
          decimals: 18,
          symbol: 'ETH',
        }}
      />
      <TokenBalance
        address={address}
        token={{
          address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
          chainId: 8453,
          decimals: 6,
          symbol: 'USDC',
        }}
      />
    </div>
  );
}

Token Price Display

import { TokenPrice } from '@coinbase/onchainkit/token';

function TokenPrices() {
  return (
    <div className="grid grid-cols-2 gap-4">
      <div className="text-center">
        <p>ETH Price</p>
        <TokenPrice
          token={{
            address: '',
            chainId: 8453,
            decimals: 18,
            symbol: 'ETH',
          }}
        />
      </div>
      <div className="text-center">
        <p>USDC Price</p>
        <TokenPrice
          token={{
            address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
            chainId: 8453,
            decimals: 6,
            symbol: 'USDC',
          }}
        />
      </div>
    </div>
  );
}

Token Search

import { TokenSearch } from '@coinbase/onchainkit/token';
import { useState } from 'react';

function TokenSelector() {
  const [selectedToken, setSelectedToken] = useState<Token | null>(null);

  return (
    <div>
      <TokenSearch
        onSelect={setSelectedToken}
        tokens={swappableTokens}
      />
      {selectedToken && (
        <div className="mt-4">
          <p>Selected: {selectedToken.name} ({selectedToken.symbol})</p>
        </div>
      )}
    </div>
  );
}

Advanced Token Operations

Custom Slippage Settings

import { Swap, SwapSettings } from '@coinbase/onchainkit/swap';

function SwapWithSettings() {
  return (
    <Swap
      config={{
        maxSlippage: 3, // 3% slippage tolerance
      }}
    >
      <SwapSettings />
      {/* Other swap components */}
    </Swap>
  );
}

Multi-Token Swap

function MultiTokenSwap() {
  const [fromToken, setFromToken] = useState(baseTokens[0]);
  const [toToken, setToToken] = useState(baseTokens[1]);

  return (
    <Swap>
      <SwapAmountInput
        label="From"
        swappableTokens={baseTokens}
        token={fromToken}
        type="from"
        onSelectToken={setFromToken}
      />
      <SwapToggleButton />
      <SwapAmountInput
        label="To"
        swappableTokens={baseTokens}
        token={toToken}
        type="to"
        onSelectToken={setToToken}
      />
      <SwapButton />
    </Swap>
  );
}

Token Allowance Management

import { useTokenAllowance, useApproveToken } from '@coinbase/onchainkit/token';

function TokenAllowance({ tokenAddress, spenderAddress }) {
  const { data: allowance } = useTokenAllowance({
    tokenAddress,
    spenderAddress,
  });

  const { approveToken, isLoading } = useApproveToken();

  const handleApprove = async () => {
    try {
      await approveToken({
        tokenAddress,
        spenderAddress,
        amount: parseUnits('1000', 18), // Approve 1000 tokens
      });
    } catch (error) {
      console.error('Approval failed:', error);
    }
  };

  return (
    <div>
      <p>Current allowance: {allowance?.toString()}</p>
      <button 
        onClick={handleApprove} 
        disabled={isLoading}
        className="bg-blue-500 text-white px-4 py-2 rounded"
      >
        {isLoading ? 'Approving...' : 'Approve Token'}
      </button>
    </div>
  );
}

Error Handling

Swap Error Types

import { SwapError, SwapErrorType } from '@coinbase/onchainkit/swap';

function handleSwapError(error: SwapError) {
  switch (error.error) {
    case SwapErrorType.INSUFFICIENT_FUNDS:
      // Show insufficient funds message
      break;
    case SwapErrorType.SLIPPAGE_TOO_HIGH:
      // Suggest increasing slippage tolerance
      break;
    case SwapErrorType.NETWORK_ERROR:
      // Show network error and retry option
      break;
    case SwapErrorType.USER_REJECTED:
      // User cancelled transaction
      break;
    default:
      // Generic error handling
      break;
  }
}

Token Validation

function validateTokenAddress(address: string): boolean {
  // Check if it's a valid Ethereum address
  return /^0x[a-fA-F0-9]{40}$/.test(address);
}

function validateTokenAmount(amount: string, decimals: number): boolean {
  try {
    const parsed = parseUnits(amount, decimals);
    return parsed > 0n;
  } catch {
    return false;
  }
}

Performance Optimization

Token List Caching

import { useMemo } from 'react';
import { Token } from '@coinbase/onchainkit/token';

function useTokenList() {
  const tokens = useMemo(() => {
    // Cache expensive token list operations
    return baseTokens.sort((a, b) => a.symbol.localeCompare(b.symbol));
  }, []);

  return tokens;
}

Debounced Token Search

import { useDebounce } from 'use-debounce';
import { useState } from 'react';

function TokenSearchWithDebounce() {
  const [searchTerm, setSearchTerm] = useState('');
  const [debouncedSearchTerm] = useDebounce(searchTerm, 300);

  const filteredTokens = useMemo(() => {
    return baseTokens.filter(token =>
      token.name.toLowerCase().includes(debouncedSearchTerm.toLowerCase()) ||
      token.symbol.toLowerCase().includes(debouncedSearchTerm.toLowerCase())
    );
  }, [debouncedSearchTerm]);

  return (
    <div>
      <input
        type="text"
        value={searchTerm}
        onChange={(e) => setSearchTerm(e.target.value)}
        placeholder="Search tokens..."
      />
      {/* Render filtered tokens */}
    </div>
  );
}

Best Practices

1. Always Validate User Input

function ValidatedSwapInput() {
  const [amount, setAmount] = useState('');
  const [error, setError] = useState('');

  const handleAmountChange = (value: string) => {
    if (!/^\d*\.?\d*$/.test(value)) {
      setError('Please enter a valid number');
      return;
    }
    
    setError('');
    setAmount(value);
  };

  return (
    <div>
      <input
        value={amount}
        onChange={(e) => handleAmountChange(e.target.value)}
      />
      {error && <p className="text-red-500">{error}</p>}
    </div>
  );
}

2. Handle Loading States

function SwapWithLoading() {
  const [isLoading, setIsLoading] = useState(false);

  return (
    <Swap
      onStart={() => setIsLoading(true)}
      onSuccess={() => setIsLoading(false)}
      onError={() => setIsLoading(false)}
    >
      <SwapButton disabled={isLoading}>
        {isLoading ? 'Swapping...' : 'Swap'}
      </SwapButton>
    </Swap>
  );
}

3. Implement Proper Error Messages

function UserFriendlyErrors({ error }: { error: SwapError }) {
  const getErrorMessage = (error: SwapError) => {
    switch (error.error) {
      case SwapErrorType.INSUFFICIENT_FUNDS:
        return "You don't have enough tokens for this swap.";
      case SwapErrorType.SLIPPAGE_TOO_HIGH:
        return "Price changed too much. Try again or increase slippage tolerance.";
      default:
        return "Something went wrong. Please try again.";
    }
  };

  return (
    <div className="bg-red-50 border border-red-200 rounded p-4">
      <p className="text-red-800">{getErrorMessage(error)}</p>
    </div>
  );
}

4. Gas Optimization

• Use multicall for multiple operations
• Batch token approvals when possible
• Consider gas prices in UI feedback
• Provide gas estimation before transactions

5. Security Best Practices

• Always validate token addresses
• Implement slippage protection
• Use secure RPC endpoints
• Validate transaction parameters
• Implement proper allowance management

OnchainKit Troubleshooting Guide

Common issues and solutions when working with OnchainKit applications.

Installation Issues

Issue: npm install fails with peer dependency warnings

npm WARN peer dep missing: react@^19.0.0

Solutions: 1. Install peer dependencies explicitly:

npm install react@^19 react-dom@^19 viem@^2.27 wagmi@^2.16

2. Use --legacy-peer-deps flag:

npm install --legacy-peer-deps

3. Update to compatible versions:

npm update react react-dom

Issue: TypeScript errors during installation

Type errors in node_modules/@coinbase/onchainkit

Solutions: 1. Skip type checking during build:

npm run build -- --no-type-check

2. Update TypeScript configuration:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Environment Configuration

Issue: "Missing API key" error

Error: OnchainKit requires an API key

Solutions: 1. Check environment variable name:

# Correct
NEXT_PUBLIC_CDP_API_KEY=pk_live_...

# Incorrect
CDP_API_KEY=pk_live_...  # Missing NEXT_PUBLIC_

2. Verify .env.local is in project root 3. Restart development server after adding environment variables 4. Check API key format (should start with pk_)

Issue: WalletConnect connection fails

Error: WalletConnect project ID is required

Solutions: 1. Get project ID from https://cloud.walletconnect.com/ 2. Add to environment:

NEXT_PUBLIC_WC_PROJECT_ID=your-project-id-here

3. Verify project settings in WalletConnect dashboard 4. Check domain allowlist in WalletConnect settings

Issue: Environment variables not loading

process.env.NEXT_PUBLIC_CDP_API_KEY is undefined

Solutions: 1. Ensure variables start with NEXT_PUBLIC_ for client-side access 2. Check file location (must be in project root) 3. Restart development server 4. Verify no syntax errors in .env.local

Wallet Connection Issues

Issue: Wallet not connecting

Error: Connector not found

Solutions: 1. Check wallet extension is installed and enabled 2. Verify Wagmi connector configuration:

import { coinbaseWallet, metaMask, walletConnect } from 'wagmi/connectors';

const connectors = [
  coinbaseWallet({
    appName: 'Your App Name',
    preference: 'all',
  }),
  metaMask(),
  walletConnect({
    projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
  }),
];

3. Clear browser cache and cookies 4. Try a different wallet/browser combination

Issue: Wrong network

Error: Chain not supported

Solutions: 1. Add chain switching:

import { useSwitchChain } from 'wagmi';

function NetworkSwitcher() {
  const { switchChain } = useSwitchChain();
  
  return (
    <button onClick={() => switchChain({ chainId: 8453 })}>
      Switch to Base
    </button>
  );
}

2. Configure multiple chains in Wagmi:

import { base, mainnet } from 'wagmi/chains';

const config = createConfig({
  chains: [base, mainnet],
  // ... other config
});

Issue: Connection persists after disconnect

Wallet shows as connected after disconnect

Solutions: 1. Clear local storage:

const handleDisconnect = () => {
  disconnect();
  localStorage.removeItem('wagmi.store');
  window.location.reload();
};

2. Implement proper cleanup:

import { useEffect } from 'react';
import { useAccount } from 'wagmi';

function ConnectionManager() {
  const { isConnected } = useAccount();

  useEffect(() => {
    if (!isConnected) {
      // Clear app state when wallet disconnects
      localStorage.removeItem('user-preferences');
    }
  }, [isConnected]);
}

Component Issues

Issue: Components not rendering

Nothing appears when using OnchainKit components

Solutions: 1. Ensure providers are properly set up:

// _app.tsx or root component
import { Providers } from '../lib/providers';

export default function App({ Component, pageProps }) {
  return (
    <Providers>
      <Component {...pageProps} />
    </Providers>
  );
}

2. Check component imports:

// Correct
import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';

// Incorrect
import { Wallet, ConnectWallet } from '@coinbase/onchainkit';

3. Import CSS:

import '@coinbase/onchainkit/styles.css';

Issue: Styling issues/components look broken

Components appear unstyled or layout is broken

Solutions: 1. Import OnchainKit CSS:

// pages/_app.tsx
import '@coinbase/onchainkit/styles.css';
import '../styles/globals.css';

2. Check CSS order (OnchainKit CSS should come first) 3. Verify Tailwind CSS isn't conflicting:

/* Exclude OnchainKit classes from Tailwind reset */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* OnchainKit overrides */
@layer components {
  .ockConnectWallet {
    @apply !important;
  }
}

Issue: TypeScript errors with components

Property 'xyz' does not exist on type...

Solutions: 1. Update TypeScript and @types/react:

npm update typescript @types/react @types/react-dom

2. Add type declarations:

// types/onchainkit.d.ts
declare module '@coinbase/onchainkit/wallet' {
  export interface WalletProps {
    children?: React.ReactNode;
    className?: string;
  }
}

Transaction Issues

Issue: Transactions fail with gas errors

Error: insufficient funds for gas * price + value

Solutions: 1. Check ETH balance for gas:

import { useBalance } from 'wagmi';

function GasChecker() {
  const { data: balance } = useBalance({
    address: userAddress,
  });

  if (balance && balance.value < parseEther('0.001')) {
    return <div>Insufficient ETH for gas fees</div>;
  }
}

2. Estimate gas before transaction:

import { useEstimateGas } from 'wagmi';

function TransactionWithGasEstimate() {
  const { data: gasEstimate } = useEstimateGas({
    to: contractAddress,
    data: encodedFunctionData,
  });

  return <div>Estimated gas: {gasEstimate?.toString()}</div>;
}

Issue: Transaction rejected by user

Error: User rejected the request

Solutions: 1. Add user-friendly messaging:

const handleTransaction = async () => {
  try {
    await sendTransaction();
  } catch (error) {
    if (error.code === 4001) {
      console.log('Transaction cancelled by user');
      // Show gentle message
    } else {
      console.error('Transaction failed:', error);
    }
  }
};

2. Provide clear transaction details before confirmation

Issue: Slow transaction confirmation

Transaction pending for long time

Solutions: 1. Implement transaction tracking:

import { useWaitForTransactionReceipt } from 'wagmi';

function TransactionTracker({ hash }) {
  const { data, isLoading } = useWaitForTransactionReceipt({
    hash,
  });

  return (
    <div>
      {isLoading && <div>Waiting for confirmation...</div>}
      {data && <div>Transaction confirmed!</div>}
    </div>
  );
}

2. Allow gas price adjustment for faster confirmation

API and Network Issues

Issue: API calls failing

Error: CDP API request failed

Solutions: 1. Check API key validity and permissions 2. Verify API key environment variable 3. Check network connectivity 4. Monitor API rate limits 5. Use proper error handling:

const fetchTokenData = async () => {
  try {
    const response = await fetch('/api/tokens');
    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error('Failed to fetch token data:', error);
    // Implement retry logic or fallback
  }
};

Issue: RPC endpoint errors

Error: RPC request failed

Solutions: 1. Use reliable RPC providers (Alchemy, Infura, Coinbase) 2. Implement fallback RPCs:

const config = createConfig({
  transports: {
    [base.id]: fallback([
      http(`https://base-mainnet.g.alchemy.com/v2/${alchemyKey}`),
      http(`https://base-mainnet.infura.io/v3/${infuraKey}`),
      http(), // Public RPC as fallback
    ]),
  },
});

3. Add retry logic for RPC calls

Performance Issues

Issue: Slow app loading

App takes long time to load or respond

Solutions: 1. Implement lazy loading:

import { lazy, Suspense } from 'react';

const SwapComponent = lazy(() => import('./components/SwapComponent'));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SwapComponent />
    </Suspense>
  );
}

2. Optimize bundle size:

// Import specific components instead of entire modules
import { Wallet } from '@coinbase/onchainkit/wallet';
import { Swap } from '@coinbase/onchainkit/swap';

3. Use React Query for caching:

import { useQuery } from '@tanstack/react-query';

function TokenPrice({ tokenAddress }) {
  const { data, isLoading } = useQuery({
    queryKey: ['tokenPrice', tokenAddress],
    queryFn: () => fetchTokenPrice(tokenAddress),
    staleTime: 60000, // Cache for 1 minute
  });
}

Development Issues

Issue: Hot reload not working

Changes not reflected in development

Solutions: 1. Restart development server 2. Clear Next.js cache:

rm -rf .next
npm run dev

3. Check file watchers (especially on Linux):

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Issue: Build failures

Build fails in production but works in development

Solutions: 1. Run build locally to debug:

npm run build

2. Check for environment-specific code:

// Avoid window/document access during SSR
const isClient = typeof window !== 'undefined';

if (isClient) {
  // Client-only code
}

3. Configure Next.js for proper builds:

// next.config.js
const nextConfig = {
  experimental: {
    esmExternals: true,
  },
  webpack: (config) => {
    config.resolve.fallback = {
      fs: false,
      net: false,
      tls: false,
    };
    return config;
  },
};

Getting Help

Debug Information to Collect

1. Browser console errors 2. Network tab for failed requests 3. OnchainKit version: npm list @coinbase/onchainkit 4. React/Next.js versions 5. Environment configuration (without sensitive data)

Useful Debug Commands

# Check versions
npm list @coinbase/onchainkit wagmi viem react

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# Test build
npm run build

# Check environment
env | grep NEXT_PUBLIC_

Community Resources

• OnchainKit Discord: Coinbase Developer Platform
• GitHub Issues: OnchainKit Repository
• Documentation: onchainkit.xyz
• Twitter: @OnchainKit

When to Contact Support

• API key or account issues
• Platform-specific problems
• Security concerns
• Feature requests
• Bug reports with reproduction steps

Wallet Integration Reference

Complete guide for implementing wallet connection and management with OnchainKit.

Basic Wallet Connection

Simple Connection

import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';

function App() {
  return (
    <Wallet>
      <ConnectWallet />
    </Wallet>
  );
}

With Identity Display

import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
import { Avatar, Name } from '@coinbase/onchainkit/identity';

function App() {
  return (
    <Wallet>
      <ConnectWallet>
        <Avatar className="h-6 w-6" />
        <Name />
      </ConnectWallet>
    </Wallet>
  );
}

Full Wallet Interface

Complete Dropdown Menu

import { 
  Wallet,
  ConnectWallet,
  WalletDropdown,
  WalletDropdownBasename,
  WalletDropdownDisconnect,
  WalletDropdownFundLink,
  WalletDropdownLink,
} from '@coinbase/onchainkit/wallet';
import { Avatar, Name, Identity } from '@coinbase/onchainkit/identity';

function WalletInterface() {
  return (
    <Wallet>
      <ConnectWallet>
        <Avatar className="h-6 w-6" />
        <Name />
      </ConnectWallet>
      <WalletDropdown>
        <Identity className="px-4 pt-3 pb-2">
          <Avatar />
          <Name />
        </Identity>
        <WalletDropdownBasename />
        <WalletDropdownLink icon="wallet" href="https://keys.coinbase.com">
          Wallet
        </WalletDropdownLink>
        <WalletDropdownFundLink />
        <WalletDropdownDisconnect />
      </WalletDropdown>
    </Wallet>
  );
}

Connection State Management

Using Wagmi Hooks

import { useAccount, useConnect, useDisconnect } from 'wagmi';

function ConnectionStatus() {
  const { address, isConnected } = useAccount();
  const { connect, connectors } = useConnect();
  const { disconnect } = useDisconnect();

  if (isConnected) {
    return (
      <div>
        <p>Connected to {address}</p>
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    );
  }

  return (
    <div>
      {connectors.map((connector) => (
        <button
          key={connector.id}
          onClick={() => connect({ connector })}
        >
          {connector.name}
        </button>
      ))}
    </div>
  );
}

Custom Connection Logic

import { useCallback } from 'react';
import { useAccount } from 'wagmi';

function useWalletConnection() {
  const { address, isConnected, isConnecting } = useAccount();

  const handleConnect = useCallback(() => {
    // Custom connection logic
    if (!isConnected) {
      // Trigger connection flow
    }
  }, [isConnected]);

  const handleDisconnect = useCallback(() => {
    // Custom disconnection logic
  }, []);

  return {
    address,
    isConnected,
    isConnecting,
    connect: handleConnect,
    disconnect: handleDisconnect,
  };
}

Wallet Configuration

Supported Wallets

import { coinbaseWallet, metaMask, walletConnect } from 'wagmi/connectors';

const connectors = [
  coinbaseWallet({
    appName: 'My OnchainKit App',
    preference: 'all', // 'all' | 'smartWalletOnly' | 'eoaOnly'
  }),
  metaMask(),
  walletConnect({
    projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
  }),
];

Custom Wallet Configuration

import { createConfig } from 'wagmi';
import { base, mainnet } from 'wagmi/chains';

const config = createConfig({
  chains: [base, mainnet],
  connectors,
  transports: {
    [base.id]: http(),
    [mainnet.id]: http(),
  },
});

Advanced Features

Smart Wallet Integration

import { coinbaseWallet } from 'wagmi/connectors';

const smartWalletConnector = coinbaseWallet({
  appName: 'My App',
  preference: 'smartWalletOnly',
  version: '4',
});

Multi-Chain Support

import { useAccount, useSwitchChain } from 'wagmi';
import { base, mainnet } from 'wagmi/chains';

function ChainSwitcher() {
  const { chain } = useAccount();
  const { switchChain } = useSwitchChain();

  return (
    <div>
      <p>Current chain: {chain?.name}</p>
      <button onClick={() => switchChain({ chainId: base.id })}>
        Switch to Base
      </button>
      <button onClick={() => switchChain({ chainId: mainnet.id })}>
        Switch to Ethereum
      </button>
    </div>
  );
}

Custom Styling

import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';

function StyledWallet() {
  return (
    <Wallet>
      <ConnectWallet 
        className="bg-blue-500 hover:bg-blue-600 text-white px-4 py-2 rounded"
        text="Connect Your Wallet"
      />
    </Wallet>
  );
}

Error Handling

Connection Errors

import { useConnect } from 'wagmi';
import { useCallback } from 'react';

function WalletWithErrorHandling() {
  const { connect, error } = useConnect();

  const handleConnect = useCallback((connector) => {
    try {
      connect({ connector });
    } catch (err) {
      console.error('Connection failed:', err);
      // Handle error (show toast, modal, etc.)
    }
  }, [connect]);

  return (
    <div>
      {error && <p className="text-red-500">Error: {error.message}</p>}
      {/* Connection UI */}
    </div>
  );
}

Retry Logic

import { useConnect } from 'wagmi';
import { useState, useCallback } from 'react';

function RetryableConnection() {
  const [retryCount, setRetryCount] = useState(0);
  const { connect, error } = useConnect();

  const handleRetry = useCallback(async (connector) => {
    if (retryCount < 3) {
      setRetryCount(prev => prev + 1);
      try {
        await connect({ connector });
      } catch (err) {
        // Will retry automatically
      }
    }
  }, [connect, retryCount]);

  return (
    <div>
      {error && retryCount < 3 && (
        <button onClick={() => handleRetry(connector)}>
          Retry Connection ({retryCount}/3)
        </button>
      )}
    </div>
  );
}

Best Practices

1. Always Wrap with Providers

import { WagmiProvider } from 'wagmi';
import { OnchainKitProvider } from '@coinbase/onchainkit';

function App() {
  return (
    <WagmiProvider config={config}>
      <OnchainKitProvider apiKey={apiKey} chain={base}>
        <WalletInterface />
      </OnchainKitProvider>
    </WagmiProvider>
  );
}

2. Handle Loading States

function WalletStatus() {
  const { isConnected, isConnecting } = useAccount();

  if (isConnecting) {
    return <div>Connecting...</div>;
  }

  if (isConnected) {
    return <div>Connected!</div>;
  }

  return <ConnectWallet />;
}

3. Graceful Degradation

function WalletFeature() {
  const { isConnected } = useAccount();

  if (!isConnected) {
    return (
      <div className="text-center p-4 border rounded">
        <p>Connect your wallet to access this feature</p>
        <ConnectWallet />
      </div>
    );
  }

  return <YourFeatureComponent />;
}

4. Security Considerations

• Never store private keys in client code
• Always validate wallet addresses on the server
• Use secure connections (HTTPS) in production
• Implement proper session management
• Validate all user inputs before signing

Common Issues

Issue: Wallet Not Connecting

Solution: Check WalletConnect project ID and network configuration

Issue: Wrong Network

Solution: Implement chain switching or network detection

Issue: Connection Persists Across Sessions

Solution: Implement proper disconnect handling and local storage cleanup

Issue: Multiple Wallet Conflicts

Solution: Properly configure connector priorities and handle conflicts

Testing

Unit Tests

import { render } from '@testing-library/react';
import { WagmiProvider } from 'wagmi';
import { WalletInterface } from './WalletInterface';

test('renders wallet connection button', () => {
  render(
    <WagmiProvider config={testConfig}>
      <WalletInterface />
    </WagmiProvider>
  );
  // Test wallet functionality
});

E2E Tests

// Playwright/Cypress test
test('wallet connection flow', async () => {
  await page.goto('/');
  await page.click('[data-testid="connect-wallet"]');
  await page.waitForSelector('[data-testid="wallet-connected"]');
});