OnchainKit

Construisez des applications onchain prêtes pour la production en utilisant la bibliothèque complète de composants React de Coinbase et les utilitaires TypeScript.

Overview

OnchainKit fournit des composants full-stack prêts à l'emploi qui abstraient la complexité de la blockchain, facilitant la construction d'applications onchain sans connaissances approfondies de la blockchain. Il propose des composants compatibles IA qui fonctionnent automatiquement sur Base, ne nécessite aucune infrastructure backend, et fournit des transactions économiques (frais < 0,01 $).

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

Connectez les utilisateurs à leurs portefeuilles cryptographiques avec un code minimal :

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

Affichez les identités blockchain avec les noms ENS, les avatars et les badges de vérification :

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

Gérez les échanges de tokens, les achats et les transferts :

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

Créez et exécutez des transactions blockchain :

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

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

Reference: references/transactions.md

5. Payment Processing

Construisez des flux de paiement et du traitement des paiements :

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

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

Reference: references/payments.md

6. NFT Integration

Affichez, frappez et gérez les NFT :

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 avec create-onchain-app.py
2. Configure providers en utilisant les modèles de configuration
3. Add wallet connection avec les composants Wallet
4. Implement core features (swap, buy, identity)
5. Test and deploy avec les scripts de validation

Building a Token Swap App

1. Commencez par le modèle d'application swap depuis assets/templates/swap-app/
2. Configurez les listes de tokens et les chaînes supportées
3. Ajoutez le flux de connexion du portefeuille
4. Implémentez l'interface d'échange
5. Ajoutez les confirmations de transaction

Creating an NFT Marketplace

1. Utilisez le modèle NFT depuis assets/templates/nft-mint/
2. Configurez l'intégration du contrat NFT
3. Construisez l'interface de frappe
4. Ajoutez le traitement des paiements
5. Implémentez la navigation des collections

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 nécessite une configuration appropriée du fournisseur React :

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

Commencez simplement, ajoutez les fonctionnalités au fur et à mesure :

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

Mélangez et associez les composants pour des flux de travail personnalisés :

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

• Utilisez les imports au niveau des composants : import { Wallet } from '@coinbase/onchainkit/wallet'
• Implémentez des états de chargement appropriés
• Mettez en cache les réponses API de manière appropriée
• Optimisez pour les expériences mobiles

Security

• N'exposez jamais les clés privées dans le code client
• Validez tous les paramètres de transaction
• Utilisez les fournisseurs OnchainKit officiels
• Implémentez des limites d'erreur appropriées

User Experience

• Fournissez des confirmations de transaction claires
• Affichez les états de chargement pendant les opérations blockchain
• Gérez les échecs de connexion du portefeuille avec grâce
• Supportez plusieurs types de portefeuilles

Reference: references/best-practices.md

Troubleshooting

Common Issues

• Wallet connection fails: Vérifiez la configuration de WalletConnect
• API errors: Vérifiez la clé API et les paramètres réseau
• Transaction reverts: Validez les appels de contrat et les limites de gaz
• Styling issues: Importez correctement le CSS d'OnchainKit

Debug Steps

1. Vérifiez la console du navigateur pour les erreurs
2. Vérifiez les variables d'environnement
3. Testez avec différents portefeuilles
4. Utilisez le script de validation pour vérifier la configuration

Reference: references/troubleshooting.md

Templates & Examples

Quick Start Templates

• Basic App: assets/templates/basic-app/ - Application onchain minimale
• Token Swap: assets/templates/swap-app/ - Interface d'échange complète
• NFT Minting: assets/templates/nft-mint/ - Place de marché NFT
• Commerce: assets/templates/commerce/ - Boutique onchain

Real-World Examples

• Wallet connection avec affichage d'identité
• Interface d'échange multi-tokens
• Collection NFT avec frappe
• Traitement des paiements avec reçus

Reference: references/examples.md

Advanced Features

Custom Chains

Supportez les chaînes EVM supplémentaires au-delà de Base :

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

<OnchainKitProvider chain={customChain}>

MiniKit Integration

Construisez des applications Farcaster Frame :

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

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

Reference: references/advanced-features.md

API Reference

OnchainKit fournit à la fois des composants React et des fonctions utilitaires :

• Components: Composants d'interface utilisateur prédéfinis pour les opérations onchain communes
• Hooks: Hooks React pour la gestion de l'état blockchain
• Utilities: Utilitaires TypeScript pour le formatage et la validation des données
• Types: Définitions TypeScript complètes

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: Commencez par npm create onchain pour amorcer une application fonctionnelle, puis personnalisez les composants selon vos besoins. Le modèle de démarrage rapide inclut toute la configuration et les exemples nécessaires.

🚀 Quick Win: Utilisez le script de validation après la configuration pour vous assurer que tout fonctionne correctement avant de construire des fonctionnalités personnalisées.