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.