onchainkit

OnchainKit

使用 Coinbase 全面的 React 组件库和 TypeScript 工具，构建可用于生产环境的链上应用。

概述

OnchainKit 提供开箱即用的全栈组件，可抽象区块链的复杂性，让你无需深入了解区块链也能轻松构建链上应用。它提供可自动在 Base 上运行的 AI 友好型组件，无需后端基础设施，且交易成本低（费用 < 0.01 美元）。

快速开始

创建新项目

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

# Verify setup
scripts/validate-setup.py

添加到现有项目

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

核心功能

1. 钱包连接与管理

只需少量代码，即可将用户连接到加密货币钱包：

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

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

使用场景：

• 钱包连接流程
• 显示钱包状态
• 管理连接状态
• 处理多个钱包

参考： references/wallet-integration.md

2. 身份展示

显示带有 ENS 名称、头像和验证徽章的区块链身份：

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

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

参考： references/identity-components.md

3. 代币操作

处理代币兑换、购买和转账：

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

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

支持的操作：

• 代币兑换（任何 ERC-20 代币）
• 使用法币购买代币
• 余额显示
• 价格动态

参考： references/token-operations.md

4. 交易构建

创建并执行区块链交易：

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

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

参考： references/transactions.md

5. 支付处理

构建结账流程并处理支付：

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

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

参考： references/payments.md

6. NFT 集成

展示、铸造和管理 NFT：

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

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

参考： references/nft-integration.md

常见工作流

设置完整应用

1. 使用 create-onchain-app.py 初始化项目
2. 使用设置模板配置 Provider
3. 使用 Wallet 组件添加钱包连接
4. 实现核心功能（兑换、购买、身份）
5. 使用验证脚本测试并部署

构建代币兑换应用

1. 从 assets/templates/swap-app/ 中选择兑换应用模板
2. 配置代币列表和支持的链
3. 添加钱包连接流程
4. 实现兑换界面
5. 添加交易确认

创建 NFT 市场

1. 使用 assets/templates/nft-mint/ 中的 NFT 模板
2. 设置 NFT 合约集成
3. 构建铸造界面
4. 添加支付处理
5. 实现藏品浏览

配置与设置

环境变量

# 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

参考： references/configuration.md

Provider 设置

OnchainKit 需要正确配置 React Provider：

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>
  );
}

组件模式

渐进增强

从简单开始，根据需要添加功能：

// 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>

可组合架构

混合搭配组件，构建自定义工作流：

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

最佳实践

性能

• 按组件导入：import { Wallet } from '@coinbase/onchainkit/wallet'
• 实现适当的加载状态
• 适当缓存 API 响应
• 针对移动端体验进行优化

安全

• 切勿在客户端代码中暴露私钥
• 验证所有交易参数
• 使用官方 OnchainKit Provider
• 实现适当的错误边界

用户体验

• 提供清晰的交易确认
• 在区块链操作期间显示加载状态
• 妥善处理钱包连接失败
• 支持多种钱包类型

参考： references/best-practices.md

故障排除

常见问题

• 钱包连接失败：检查 WalletConnect 配置
• API 错误：检查 API 密钥和网络设置
• 交易回滚：验证合约调用和 Gas 限制
• 样式问题：正确导入 OnchainKit CSS

调试步骤

1. 检查浏览器控制台是否有错误
2. 验证环境变量
3. 使用不同的钱包进行测试
4. 使用验证脚本检查设置

参考： references/troubleshooting.md

模板与示例

快速入门模板

• 基础应用：assets/templates/basic-app/ - 最简版链上应用
• 代币兑换：assets/templates/swap-app/ - 完整的兑换界面
• NFT 铸造：assets/templates/nft-mint/ - NFT 市场
• 电商：assets/templates/commerce/ - 链上商店

实际示例

• 显示身份信息的钱包连接
• 多代币兑换界面
• 带有铸造功能的 NFT 系列
• 带有收据的支付处理

参考： references/examples.md

高级功能

自定义链

支持 Base 以外的其他 EVM 链：

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

<OnchainKitProvider chain={customChain}>

MiniKit 集成

构建 Farcaster Frame 应用：

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

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

参考： references/advanced-features.md

API 参考

OnchainKit 提供 React 组件和实用函数：

• 组件：用于常见链上操作的预构建 UI 组件
• 钩子：用于管理区块链状态的 React 钩子
• 实用工具：用于数据格式化和验证的 TypeScript 实用工具
• 类型：完整的 TypeScript 类型定义

参考： references/api-reference.md

资源

文档

• 官方文档：onchainkit.xyz
• GitHub：github.com/coinbase/onchainkit
• 示例：OnchainKit playground

支持

• Discord：Coinbase Developer Platform
• Twitter：@OnchainKit

---

💡 专业提示：使用 npm create onchain 启动并创建可运行的应用，然后根据需要自定义组件。快速入门模板包含所有必要的配置和示例。

🚀 快速见效：设置完成后，使用验证脚本确认一切正常，再构建自定义功能。