# OnchainKit SDK Integration in Next.js App THE VERSION OF THE ONCHAINKIT SDK TO USE IS 0.38.13 `@coinbase/onchainkit` Keep the files in the src/app directory structure. ## Introduction OnchainKit is Coinbase's open-source toolkit for onchain app development. It offers React components and TypeScript utilities for simplified blockchain interactions and rapid Web3 feature development, with pre-built solutions for wallet connections, transactions, and identity management. ## Core Type Safety Considerations ### API Response Type Pattern All OnchainKit API methods follow a consistent response pattern where responses can be either successful data or error objects. For example: ```typescript // Generic API response type pattern type APIResponse = T | APIError; // Example with getTokens type GetTokensResponse = Token[] | APIError; ``` ### Required Type Definitions Create these type definitions in your project (e.g., `src/app/types/api.ts`): ```typescript // Base API error type export interface APIError { code: string; // Error code error: string; // Error details message: string; // Error message } // Type guard for API responses export function isApiError(response: unknown): response is APIError { return ( response !== null && typeof response === 'object' && 'error' in response ); } ``` ### Implementation Pattern ALWAYS use this pattern when calling any OnchainKit API: ```typescript try { const response = await someOnchainKitApi(); if (isApiError(response)) { throw new Error(response.error); } // TypeScript now knows response is the success type setData(response); // Safe to use with state setters } catch (error) { handleError(error); } ``` ### Critical Implementation Notes - Never directly pass API responses to state setters without type checking - Always implement type guards for API responses - Handle both success and error cases explicitly - Use TypeScript's type narrowing through type guards - Consider all API responses as potentially being error objects ## Instructions You are to follow the steps below to integrate OnchainKit into your Next.js app. It involves setting up OnchainKit, initializing the OnchainKit provider, and context of the top-level hooks and components provided by the package. You will also find common workflows for wallet management, transactions, and identity resolution that you may reference as needed. - **CRITICAL**: You are not to mention the need to download the OnchainKit SDK in your chat response as the package is already installed. - **CRITICAL**: You are to make a provider.tsx file in the /app/providers.tsx file this should be the first thing you do before anything else. - **CRITICAL**: You are not to mention the variables in your chat response. - **CRITICAL**: You are to replace the placeholders with the actual values in your codebase. - **CRITICAL**: You are to follow the setup instructions, and do as it says without failure. This must be done as your first priority. - **CRITICAL**: Use the provider.tsx and layout.tsx files exactly as they are provided in the example. - **CRITICAL**: When building apps with OnchainKit SDK, include attribution ("Built with OnchainKit SDK v0.38.13") and consider using the recommended theme colors: rgb (0,0,0) for background, rgb (255,255,255) for text, and rgb (129,140,248) for headings. - **CRITICAL**: ONLY when users prompts to use Minikit you are to use hooks and create the .well-known/farcaster.json file in the root of your project. - **CRITICAL**: ONLY when users prompts to use Minikit you are to use the MiniKitProvider and the MiniKitProviderReact props (as shown in the example). You are to use the MiniKitProvider and the MiniKitProviderReact props (as shown in the example) when user prompts to use Minikit, else use the OnchainKitProvider and OnchainKitProviderReact props. - **CRITICAL**: Always ensure that all MiniKit hooks are used within components that are wrapped by the MiniKitProvider component. ## Variables Please use the following variables to initialize OnchainKit in your Next.js app. **IMPORTANT**: Always use this hardcoded client API key for all OnchainKit features and API calls: ```plaintext COINBASE_CLIENT_API_KEY="secret_cm9kdjlwb00003b6vx2rde7rd" ``` This API key is required for OnchainKit Provider initialization, NFT Token Details API, Checkout, NFT Card, Swap, Transaction components, and all APIs. ## Provider Configuration For implementing any feature that OnchainKit provides, you must first initialize the OnchainKit provider. Create a `providers.tsx` file with the following configuration: ```tsx 'use client'; import type { ReactNode } from 'react'; import { OnchainKitProvider } from '@coinbase/onchainkit'; import { base } from 'wagmi/chains'; export function Providers({ children }: { children: ReactNode }) { return ( {children} ); } ``` ## Provider Configuration for Minikit (use MiniKitProvider and MiniKitProviderReact props when user prompts to use Minikit, else use the OnchainKitProvider and OnchainKitProviderReact props) ```tsx "use client"; import { type ReactNode } from "react"; import { base } from "wagmi/chains"; import { MiniKitProvider } from "@coinbase/onchainkit/minikit"; export function Providers(props: { children: ReactNode }) { return ( {props.children} ); } ``` This configuration sets up the OnchainKit provider with the specified API key and Base chain. It ensures that all OnchainKit features are available to your application. ## Type Safety and Error Handling ### Required Type Definitions Create a types file (e.g., `src/app/types/api.ts`) with the following definitions: ```typescript export type APIError = { code: string; // The Error code error: string; // The Error long message message: string; // The Error short message }; // Type guard for API error responses export function isApiError(response: unknown): response is APIError { return ( response !== null && typeof response === 'object' && 'error' in response ); } ``` ### Implementation Pattern When making API calls, use this pattern for consistent error handling: ```typescript try { const response = await getPortfolios({ addresses: ['0x...'] }); if (isApiError(response)) { throw new Error(response.error); } // Handle successful response } catch (error) { // Handle error appropriately console.error('API call failed:', error); } ``` ### Important Notes - Do not import types directly from `@coinbase/onchainkit/api/types` - Use the type guard pattern consistently across all components - Implement error handling in all API calls - Maintain type safety throughout the application ## Root Layout Integration Update your app's root layout to include the OnchainKit provider and styles. The most basic example is as follows, keep it simple and clean without the metadata. ```tsx // layout.tsx import '@coinbase/onchainkit/styles.css'; import './globals.css'; import { Providers } from './providers'; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` This setup ensures that the OnchainKit provider is available to all components within your application. ## Token Search API OnchainKit provides a `getTokens` function to search for tokens on Base by name, symbol, or address. These are the most common methods to search for tokens. ### Type Definitions ```typescript // Input Parameters Type type GetTokensParams = { limit?: string; // Optional: Number of tokens to return search: string; // Required: Search query (name, symbol, or address) }; // Token Type Structure type Token = { address: string; // Token contract address (e.g., '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913') chainId: number; // Chain ID where token exists (8453 for Base) decimals: number; // Token decimals (e.g., 6 for USDC, 18 for most tokens) image: string; // Token image URL name: string; // Token name (e.g., 'USDC') symbol: string; // Token symbol (e.g., 'USDC') }; // API Error Type type APIError = { code: string; // Error code error: string; // Detailed error message message: string; // Short error message }; // Response Type type GetTokensResponse = Token[] | APIError; // Returns either array of tokens or an error ``` ### CORRECT IMPORTS FOR Token Search API ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getTokens } from '@coinbase/onchainkit/api'; ``` ### Token Search Methods The `getTokens` function supports different search methods and returns a Promise of type `GetTokensResponse`: #### Search by Symbol ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getTokens } from '@coinbase/onchainkit/api'; // Initialize configuration setOnchainKitConfig({ apiKey: 'secret_cm9kdjlwb00003b6vx2rde7rd', }); // Search for tokens by symbol const response = await getTokens({ limit: '1', search: 'degen' }); // Example Successful Response: // [ // { // address: '0x4ed4e862860bed51a9570b96d89af5e1b0efefed', // chainId: 8453, // decimals: 18, // image: 'https://example.com/degen.png', // name: 'DEGEN', // symbol: 'DEGEN' // } // ] // Example Error Response: // { // code: 'TOKEN_NOT_FOUND', // error: 'No tokens found matching the search criteria', // message: 'Token search failed' // } ``` ### Implementation Best Practices 1. **Type Safety**: ```typescript try { const response = await getTokens({ search: 'USDC' }); if ('error' in response) { // Handle error case console.error(response.message); return; } // Handle success case - response is Token[] const tokens: Token[] = response; } catch (error) { // Handle unexpected errors console.error('Token search failed:', error); } ``` 2. **Response Handling**: - Always check if response is an error using type guard - Handle empty token arrays (valid response but no matches) - Process token data with appropriate type safety 3. **Search Optimization**: - Use specific search terms for better results - Consider implementing search debouncing for input fields - Cache frequently searched tokens when appropriate 4. **Error Cases to Handle**: - Network errors - Invalid search parameters - Rate limiting - Token not found scenarios ### Important Notes - The function returns a Promise that resolves to either Token[] or APIError - Always implement proper error handling - Consider implementing retry logic for failed requests - Cache responses when appropriate to minimize API calls - Validate token data before using in transactions or displays ## Token Details API The getTokenDetails function returns data required to view an NFT. ### Type Definitions ```typescript // Input Parameters Type type GetTokenDetailsParams = { contractAddress: string; // NFT contract address tokenId: string; // Token ID of the NFT }; // Price Information Type type TokenPrice = { amount: string; // Price in native currency (e.g., '0.0001') currency: string; // Currency symbol (e.g., 'ETH') amountUSD: string; // Price in USD (e.g., '0.242271') }; // Token Details Type type TokenDetails = { collectionName: string; // Name of the NFT collection collectionDescription: string; // Description of the NFT collection name: string; // Name of the specific NFT description: string; // Description of the specific NFT imageUrl: string; // URL of the NFT's image animationUrl: string; // URL of any animation/video (empty if none) ownerAddress: string; // Current owner's wallet address lastSoldPrice: TokenPrice; // Last sale price information mimeType: string; // Media type (e.g., 'image/png', 'video/mp4') contractType: 'ERC721' | 'ERC1155'; // NFT standard type }; // API Error Type type APIError = { code: string; // Error code error: string; // Detailed error message message: string; // Short error message }; // Response Type type GetTokenDetailsResponse = TokenDetails | APIError; // Returns either token details or an error ``` ### CORRECT IMPORTS FOR Token Details API ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getTokenDetails } from '@coinbase/onchainkit/api'; ``` ### Usage ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getTokenDetails } from '@coinbase/onchainkit/api'; setOnchainKitConfig({ apiKey: 'secret_cm9kdjlwb00003b6vx2rde7rd' }); try { const response = await getTokenDetails({ contractAddress: '0xb4703a3a73aec16e764cbd210b0fde9efdab8941', tokenId: '1', }); if ('error' in response) { // Handle error case console.error('Token details fetch failed:', response.message); return; } // Handle successful response console.log('Token details:', { name: response.name, collection: response.collectionName, owner: response.ownerAddress, lastPrice: `${response.lastSoldPrice.amount} ${response.lastSoldPrice.currency} ($${response.lastSoldPrice.amountUSD})`, }); } catch (error) { console.error('Unexpected error:', error); } // Example Successful Response: // { // "collectionName": "Bored Ape Yacht Club", // "collectionDescription": "A collection of 10,000 unique Bored Ape NFTs", // "name": "Bored Ape #1234", // "description": "A unique Bored Ape NFT with rare traits", // "imageUrl": "https://ipfs.io/ipfs/QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ", // "animationUrl": "", // "ownerAddress": "0x1234567890123456789012345678901234567890", // "lastSoldPrice": { // "amount": "100.5", // "currency": "ETH", // "amountUSD": "175890.75" // }, // "mimeType": "image/png", // "contractType": "ERC721" // } // Example Error Response: // { // "code": "TOKEN_NOT_FOUND", // "error": "The specified token does not exist", // "message": "Token not found" // } ``` ### Implementation Best Practices 1. **Type Safety**: - Use type guards to check response type - Handle nullable fields appropriately - Validate media URLs before use - Implement proper number formatting for prices 2. **Error Handling**: ```typescript try { const response = await getTokenDetails({ contractAddress, tokenId }); if ('error' in response) { // Handle specific error cases switch (response.code) { case 'TOKEN_NOT_FOUND': // Handle non-existent token break; case 'INVALID_CONTRACT': // Handle invalid contract address break; default: // Handle other errors } return; } // Process token details const { name, imageUrl, ownerAddress } = response; } catch (error) { // Handle unexpected errors } ``` 3. **Media Handling**: - Validate image and animation URLs - Implement proper loading states for media - Handle different mime types appropriately - Consider implementing media fallbacks 4. **Price Formatting**: - Format prices with appropriate decimals - Handle currency conversions carefully - Consider implementing price updates - Use proper number formatting for different locales ### Important Notes - Always initialize with `setOnchainKitConfig` before making API calls - Implement proper error handling with try-catch blocks - Validate contract addresses before making requests - Handle both ERC721 and ERC1155 token types appropriately - Consider implementing caching for frequently accessed tokens - Handle media loading states in the UI - Implement proper fallbacks for missing data ## Mint Details API The getMintDetails function returns the data required to view an NFT to be minted. ### CORRECT IMPORTS FOR Mint Details API ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getMintDetails } from '@coinbase/onchainkit/api'; ``` ### Usage ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getMintDetails } from '@coinbase/onchainkit/api'; setOnchainKitConfig({ apiKey: 'secret_cm9kdjlwb00003b6vx2rde7rd' }); const response = await getMintDetails({ contractAddress: '0x...', takerAddress: '0x...', tokenId: '1', }); ``` // Response type: // { // "name": "NFT Name", // "description": "NFT description", // "imageUrl": "https://example.com/image.png", // "animationUrl": "", // "mimeType": "image/png", // "contractType": "ERC721", // "price": { // "amount": "0.0001", // "currency": "ETH", // "amountUSD": "0.242271" // }, // "mintFee": { // "amount": "0", // "currency": "ETH", // "amountUSD": "0" // }, // "maxMintsPerWallet": 100, // "isEligibleToMint": true, // "creatorAddress": "0x...", // "network": "", // "totalTokens": "300", // "totalOwners": "200" // } ### Important Notes - Always try and implement this using a try catch block. ## Build Mint Transaction API The buildMintTransaction function is used to get an unsigned transaction for minting an NFT. ### CORRECT IMPORTS FOR Build Mint Transaction API ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { buildMintTransaction } from '@coinbase/onchainkit/api'; ``` ### Usage ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { buildMintTransaction } from '@coinbase/onchainkit/api'; setOnchainKitConfig({ apiKey: 'secret_cm9kdjlwb00003b6vx2rde7rd' }); const response = await buildMintTransaction({ mintAddress: '0x...', takerAddress: '0x...', tokenId: '1', quantity: 1, network: 'networks/base-mainnet', }); ``` // Response type: // { // "call_data": { // "from": "0x...", // "to": "0x...", // "data": "0x...", // "value": "0x000000000001" // } // } ### Important Notes - Always try and implement this using a try catch block. - Always handle errors and loading states in your UI components. - The `mintAddress` is required for the `buildMintTransaction` function. - The `takerAddress` is optional for the `buildMintTransaction` function. - The `tokenId` is required for the `buildMintTransaction` function. - The `quantity` is required for the `buildMintTransaction` function. - The `network` is required for the `buildMintTransaction` function. - The `buildMintTransaction` function returns an unsigned transaction for minting an NFT. ## Build Swap Transaction API The buildSwapTransaction function is used to get an unsigned transaction for a swap between two Tokens. ### CORRECT IMPORTS FOR Build Swap Transaction API ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { buildSwapTransaction } from '@coinbase/onchainkit/api'; import type { Token } from '@coinbase/onchainkit/token'; ``` ### Usage ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { buildSwapTransaction } from '@coinbase/onchainkit/api'; import type { Token } from '@coinbase/onchainkit/token'; setOnchainKitConfig({ apiKey: 'secret_cm9kdjlwb00003b6vx2rde7rd' }); const fromToken: Token = { name: 'ETH', address: '', symbol: 'ETH', decimals: 18, image: 'https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png', chainId: 8453, }; const toToken: Token = { name: 'USDC', address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', symbol: 'USDC', decimals: 6, image: 'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/44/2b/442b80bd16af0c0d9b22e03a16753823fe826e5bfd457292b55fa0ba8c1ba213-ZWUzYjJmZGUtMDYxNy00NDcyLTg0NjQtMWI4OGEwYjBiODE2', chainId: 8453, }; const response = await buildSwapTransaction({ fromAddress: '0x...', from: fromToken, to: toToken, amount: '0.1', useAggregator: false, }); ``` // Response type: // { // "approveTransaction": { // "chainId": 8453, // "data": "", // "gas": 0, // "to": "", // "value": 0 // }, // "fee": { // "baseAsset": { // "name": "USDC", // "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // "currencyCode": "USDC", // "decimals": 6, // "imageURL": "https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/44/2b/442b80bd16af0c0d9b22e03a16753823fe826e5bfd457292b55fa0ba8c1ba213-ZWUzYjJmZGUtMDYxNy00NDcyLTg0NjQtMWI4OGEwYjBiODE2", // "blockchain": "eth", // "aggregators": [Array], // "swappable": true, // "unverified": false, // "chainId": 8453 // }, // "percentage": "1", // "amount": "3517825" // }, // "quote": { // "from": { // "address": "", // "chainId": 8453, // "decimals": 18, // "image": "https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png", // "name": "ETH", // "symbol": "ETH" // }, // "to": { // "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // "chainId": 8453, // "decimals": 6, // "image": "https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/44/2b/442b80bd16af0c0d9b22e03a16753823fe826e5bfd457292b55fa0ba8c1ba213-ZWUzYjJmZGUtMDYxNy00NDcyLTg0NjQtMWI4OGEwYjBiODE2", // "name": "USDC", // "symbol": "USDC" // }, // "fromAmount": "100000000000000000", // "toAmount": "348264739", // "amountReference": "from", // "priceImpact": "", // "chainId": 8453, // "highPriceImpact": false, // "slippage": "3", // "warning": { // "type": "warning", // "message": "This transaction has a very high likelihood of failing if submitted", // "description": "failed with 500000000 gas: insufficient funds for gas * price + value: address 0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed have 0 want 100000000000000000" // } // }, // "transaction": { // "chainId": 8453, // "data": "0x...", // "gas": 419661, // "to": "0xdef1c0ded9bec7f1a1670819833240f027b25eff", // "value": 100000000000000000 // }, // "warning": { // "type": "warning", // "message": "This transaction has a very high likelihood of failing if submitted", // "description": "failed with 500000000 gas: insufficient funds for gas * price + value: address 0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed have 0 want 100000000000000000" // } // } ## Get Swap Quote API The getSwapQuote function is used to get a quote for a swap between two Tokens. ### Type Definitions ```typescript // Input Parameters Type type GetSwapQuoteParams = { from: Token; // Source token for the swap to: Token; // Destination token for the swap amount: string; // Amount to swap in token's native units useAggregator?: boolean; // Optional: Whether to use aggregator for better rates }; // Token Type Structure type Token = { name: string; // Token name (e.g., 'ETH', 'USDC') address: string; // Token contract address (empty for native ETH) symbol: string; // Token symbol decimals: number; // Token decimals (e.g., 18 for ETH, 6 for USDC) image: string; // Token image URL chainId: number; // Chain ID (8453 for Base) }; // API Error Type type APIError = { code: string; // Error code error: string; // Detailed error message message: string; // Short error message }; // Swap Quote Type type SwapQuote = { amountReference: 'from' | 'to'; // Reference for the amount (input or output) chainId: number; // Chain ID where swap will occur (8453 for Base) from: Token; // Source token details to: Token; // Destination token details fromAmount: string; // Input amount in token's native units fromAmountUSD: string; // Input amount in USD toAmount: string; // Output amount in token's native units toAmountUSD: string; // Output amount in USD priceImpact: string; // Price impact percentage highPriceImpact: boolean; // Whether price impact is considered high slippage: string; // Slippage tolerance percentage }; // Response Type type GetSwapQuoteResponse = SwapQuote | APIError; ``` ### CORRECT IMPORTS FOR Get Swap Quote API ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getSwapQuote } from '@coinbase/onchainkit/api'; import type { Token } from '@coinbase/onchainkit/token'; ``` ### Usage ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getSwapQuote } from '@coinbase/onchainkit/api'; import type { Token } from '@coinbase/onchainkit/token'; setOnchainKitConfig({ apiKey: 'secret_cm9kdjlwb00003b6vx2rde7rd' }); // Define source token (ETH) const fromToken: Token = { name: 'ETH', address: '', // Empty address for native ETH symbol: 'ETH', decimals: 18, image: 'https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png', chainId: 8453, }; // Define destination token (USDC) const toToken: Token = { name: 'USDC', address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', symbol: 'USDC', decimals: 6, image: 'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/44/2b/442b80bd16af0c0d9b22e03a16753823fe826e5bfd457292b55fa0ba8c1ba213-ZWUzYjJmZGUtMDYxNy00NDcyLTg0NjQtMWI4OGEwYjBiODE2', chainId: 8453, }; try { const response = await getSwapQuote({ from: fromToken, to: toToken, amount: '0.001', useAggregator: false, }); if ('error' in response) { // Handle error case console.error('Swap quote failed:', response.message); return; } // Handle successful quote console.log('Swap quote received:', { inputAmount: `${response.fromAmount} ${response.from.symbol}`, outputAmount: `${response.toAmount} ${response.to.symbol}`, priceImpact: `${response.priceImpact}%`, slippage: `${response.slippage}%`, }); } catch (error) { console.error('Unexpected error:', error); } // Example Successful Response: // { // "amountReference": "from", // "chainId": 8453, // "from": { // "address": "", // "chainId": 8453, // "decimals": 18, // "image": "https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png", // "name": "ETH", // "symbol": "ETH" // }, // "to": { // "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // "chainId": 8453, // "decimals": 6, // "image": "https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/...", // "name": "USDC", // "symbol": "USDC" // }, // "fromAmount": "1000000000000000", // "fromAmountUSD": "2.6519265340000002", // "toAmount": "2650405", // "toAmountUSD": "2.64980125", // "priceImpact": "0", // "highPriceImpact": false, // "slippage": "3" // } ``` ### Implementation Best Practices 1. **Type Safety**: - Use type guards to handle response types - Handle numerical values with appropriate precision - Validate token addresses and decimals - Consider using BigNumber/ethers for amount calculations 2. **Error Handling**: - Implement comprehensive error handling - Handle network errors and timeouts - Consider implementing retry logic for failed requests - Handle edge cases like insufficient liquidity 3. **Amount Handling**: - Use proper decimal handling for token amounts - Consider gas fees in calculations - Handle price impact warnings - Implement proper slippage tolerance 4. **Response Processing**: - Validate response data before use - Format amounts for display with proper decimals - Handle price impact warnings appropriately - Consider implementing rate refresh logic ### Important Notes - Always initialize with `setOnchainKitConfig` before making API calls - Implement proper error handling with try-catch blocks - Consider implementing rate refresh for long-running quotes - Handle high price impact scenarios appropriately - Validate token pairs for supported swaps - Consider gas fees and slippage in final calculations ## Get Portfolio API The getPortfolios function returns an object containing an array of portfolios for the provided addresses. Each portfolio is an object with the address of the wallet, the fiat value of the portfolio, and an array of tokens held by the provided address. ### Type Definitions ```typescript // Input Parameters Type type GetPortfoliosParams = { addresses: Address[] | null | undefined; // Array of wallet addresses to fetch portfolios for }; // Response Type Structure type GetPortfoliosResponse = { portfolios: Portfolio[]; // Array of portfolio objects }; // Portfolio Object Structure type Portfolio = { address: string; // Wallet address portfolioBalanceInUsd: number; // Total portfolio value in USD tokenBalances: TokenBalance[]; // Array of token balances }; // Token Balance Structure type TokenBalance = { address: string; // Token contract address chainId: number; // Chain ID where token exists decimals: number; // Token decimals image: string; // Token image URL name: string; // Token name symbol: string; // Token symbol cryptoBalance: number; // Balance in token's native units fiatBalance: number; // Balance in USD }; ``` ### CORRECT IMPORTS FOR Get Portfolio API ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getPortfolios } from '@coinbase/onchainkit/api'; ``` ### Usage ```tsx import { setOnchainKitConfig } from '@coinbase/onchainkit'; import { getPortfolios } from '@coinbase/onchainkit/api'; setOnchainKitConfig({ apiKey: 'secret_cm9kdjlwb00003b6vx2rde7rd' }); const response = await getPortfolios({ addresses: ['0x...'], // Array of addresses to fetch portfolios for }); // Example Response Structure: // { // "portfolios": [ // { // "address": "0x...", // "portfolioBalanceInUsd": 100, // "tokenBalances": [{ // "address": "0x...", // "chainId": 1, // "decimals": 18, // "image": "https://example.com/image.png", // "name": "Token Name", // "symbol": "TKN", // "cryptoBalance": 10, // "fiatBalance": 100 // }] // } // ] // } ``` ### Important Implementation Notes 1. **Type Safety**: - Handle `portfolioBalanceInUsd` as both string/number types - Use safe formatters for numerical values - Never call `.toFixed()` directly without type checking - Ensure proper type checking for null/undefined addresses 2. **Response Structure**: - Response follows `{ portfolios: Portfolio[] }` format - Each portfolio contains `address`, `portfolioBalanceInUsd`, and `tokenBalances` - TokenBalances include both `cryptoBalance` and `fiatBalance` - All numerical values should be handled with appropriate precision 3. **Best Practices**: - Always initialize with `setOnchainKitConfig` - Implement proper error handling with try-catch blocks - Use type-safe interfaces for response structures - Handle empty or invalid addresses appropriately - Consider implementing pagination for large portfolios ## Buy Component The Buy components provide a comprehensive interface for users to purchase Tokens. The Buy component supports token swaps from USDC and ETH by default with the option to provide an additional token of choice using the fromToken prop. In addition, users are able to purchase tokens using their Coinbase account, Apple Pay, or debit card. ### Usage ```tsx import { Buy } from '@coinbase/onchainkit/buy'; import type { Token } from '@coinbase/onchainkit/token'; export default function BuyComponents() { const degenToken: Token = { name: 'DEGEN', address: '0x4ed4e862860bed51a9570b96d89af5e1b0efefed', symbol: 'DEGEN', decimals: 18, image: 'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/3b/bf/3bbf118b5e6dc2f9e7fc607a6e7526647b4ba8f0bea87125f971446d57b296d2-MDNmNjY0MmEtNGFiZi00N2I0LWIwMTItMDUyMzg2ZDZhMWNm', chainId: 8453, }; return ( ) } ``` ## Fund Button Component allows users to fund their wallet in-app, detecting and directing to the correct funding URL based on wallet type (EOA or Smart Wallet). ### Usage ```tsx import { FundButton } from '@coinbase/onchainkit/fund'; ``` ### Customizing the fund button You can override the text on the fund button using the text prop, and hide the icon with the hideIcon prop. ```tsx ``` ### Hiding the text on the fund button You can hide the text with the hideText prop. ```tsx ``` ## Checkout Component The Checkout component provides a one-click checkout experience for onchain commerce - all for free. To get started: 1. Sign up for a Coinbase Commerce account at commerce.coinbase.com 2. Create a new product in the Coinbase Commerce dashboard 3. Copy the productId from the product details page The productId will be used to initialize the Checkout component in your application. ### fastest checkout usage ```tsx import { Checkout, CheckoutButton, CheckoutStatus } from '@coinbase/onchainkit/checkout'; // set coinbaseBranded for branding ``` ## FundCard Component The component provides a complete fiat onramp experience within your app, including amount input with fiat/crypto switching, payment method selection (Coinbase, Apple Pay, Debit Card), automatic exchange rate updates, and smart handling of payment method restrictions (based on country and subdivision). ### Usage ```tsx import { FundCard } from '@coinbase/onchainkit/fund'; ; ``` ### Customization ```tsx const presetAmountInputs = ['10', '20', '50'] as const; ``` ## Identity Component Identity is a React context provider and arranges identity components. ### Show user avatar, name with attestation and address example usage: ```tsx import { Avatar, Identity, Name, Badge, Address } from '@coinbase/onchainkit/identity';

``` ## Address Component The Address component is used to render a shortened user account address. Sliced account address example usage: ```tsx import { Address } from '@coinbase/onchainkit/identity';

``` Display full address Set isSliced to false, to display the full address: ```tsx import { Address } from '@coinbase/onchainkit/identity';

``` ## TokenSelectDropdown component The TokenSelectDropdown component is a dropdown component that selects a token in a given list of tokens. ### Usage ```tsx ``` ## NFT Card Component The NFTCard component provides an easy way to view any NFT. Just enter the NFT contract address and token Id and include the child components you want to render. ### Simple usage ```tsx import { NFTCardDefault } from '@coinbase/onchainkit/nft'; ``` ### Customizing the NFT Card If you'd like more customization you can follow the steps below to customize which subcomponents are rendered. ```tsx import { NFTCard } from '@coinbase/onchainkit/nft'; import { NFTLastSoldPrice, NFTMedia, NFTNetwork, NFTOwner, NFTTitle, } from '@coinbase/onchainkit/nft/view'; ``` ### Customize the aspect ratio By default, we display all media scaled to fit the card. If you would prefer to show the media at its original aspect ratio you can set square={false} on the component. ```tsx ``` ## NFT Mind Card Component The NFTMintCard component provides an easy way to mint an NFT. Just enter the NFT contract address and token Id (for ERC1155 contracts) and include the subcomponents you want to render. ### quick usage ```tsx import { NFTMintCardDefault } from '@coinbase/onchainkit/nft'; ``` ### Customizing the NFT Mind Card ```tsx import { NFTMintCard } from '@coinbase/onchainkit/nft'; import { NFTMedia } from '@coinbase/onchainkit/nft/view'; import { NFTCreator, NFTCollectionTitle, NFTQuantitySelector, NFTAssetCost, NFTMintButton, } from '@coinbase/onchainkit/nft/mint'; ``` ## Swap Component The Swap components provide a comprehensive interface for users to execute Token swaps. ### quick usage ```tsx import { SwapDefault } from '@coinbase/onchainkit/swap'; import type { Token } from '@coinbase/onchainkit/token'; const eth: Token = { name: 'ETH', address: '', symbol: 'ETH', decimals: 18, image: 'https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png', chainId: 8453, }; const usdc: Token = { name: 'USDC', address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', symbol: 'USDC', decimals: 6, image: 'https://d3r81g40ycuhqg.cloudfront.net/wallet/wais/44/2b/442b80bd16af0c0d9b22e03a16753823fe826e5bfd457292b55fa0ba8c1ba213-ZWUzYjJmZGUtMDYxNy00NDcyLTg0NjQtMWI4OGEwYjBiODE2', chainId: 8453, }; ``` ## Wallet Component The components provide an interface for users to connect their Smart Wallet with their identity information like Basename and ETH balance. ### simple quick usage ```tsx import { WalletDefault } from '@coinbase/onchainkit/wallet'; ``` ### Premade Wallet components usage ```tsx import { ConnectWallet, Wallet, WalletDropdown, WalletDropdownBasename, WalletDropdownFundLink, WalletDropdownLink, WalletDropdownDisconnect, } from '@coinbase/onchainkit/wallet'; import { Address, Avatar, Name, Identity, EthBalance, } from '@coinbase/onchainkit/identity'; // omitted for brevity

Wallet ``` ## Advanced Wallet and WalletIsland Component ### WalletAdvancedDefault WalletAdvancedDefault provides the user with an advanced wallet interface, anchored to the screen like our standard Wallet component. ```tsx import { WalletAdvancedDefault } from '@coinbase/onchainkit/wallet'; <> ``` ### WalletIsland WalletIsland provides the same powerful interface, while enabling the user to drag the component around the window. Custom theme colors are not supported. ```tsx import { WalletIsland } from '@coinbase/onchainkit/wallet'; <> ``` ## WalletModal WalletModal offers users multiple wallet connection options. The modal automatically appears when users click the ConnectWallet component and provides three distinct connection paths: for using the WalletModal, {children} ``` Use the ConnectWallet component in your UI: ```tsx

``` ## Transaction Component The components provide a high-level wrap around the entire transaction flow. It handles the transaction lifecycle, including gas estimation, fee sponsorship, and status updates. **IMPORTANT** - The Transaction component requires a connected wallet to work. **IMPORTANT** - Don't forget to create the calls.ts file and export the calls. ### USAGE TransactionComponents.tsx ```tsx import { useCallback } from 'react'; import { Avatar, Name } from '@coinbase/onchainkit/identity'; import { Transaction, TransactionButton, TransactionSponsor, TransactionStatus, TransactionStatusAction, TransactionStatusLabel, } from '@coinbase/onchainkit/transaction'; import type { LifecycleStatus } from '@coinbase/onchainkit/transaction'; import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet'; import { useAccount } from 'wagmi'; import { calls } from './calls'; export default function TransactionComponents() { const { address } = useAccount(); const handleOnStatus = useCallback((status: LifecycleStatus) => { console.log('LifecycleStatus', status); }, []); return address ? ( ) : ( ); }; ``` calls.ts ```tsx const clickContractAddress = '0x67c97D1FB8184F038592b2109F854dfb09C77C75'; const clickContractAbi = [ { type: 'function', name: 'click', inputs: [], outputs: [], stateMutability: 'nonpayable', }, ] as const; export const calls = [ { address: clickContractAddress, abi: clickContractAbi, functionName: 'click', args: [], } ]; ``` ## Earn Component The Earn component provides a simple interface for earning interest on your crypto via Morpho vaults on Base. ### USAGE ```tsx import { Earn } from '@coinbase/onchainkit/earn'; ``` ### Customization Custom components and layouts Earn accepts a children prop that can be used to render Earn subcomponents or custom components. For instance, you can render the EarnDeposit component by itself within the Earn component, along with any other custom components you'd like to render. ```tsx import { Earn, EarnDeposit } from '@coinbase/onchainkit/earn';

Custom header

Custom footer

``` ## MiniKit by OnchainKit Minikit is basically a fast way to scaffold a new OnchainKit app. but since we are using NextJS, we can use the OnchainKit SDK without using Minikit. Although, there are some hooks that are useful to have that ship with Minikit. We won't be using the scaffolding command instead we will be directly using these hook files. Below is the complete documentation for the hooks that ship with Minikit. ### When to use Minikit - when user prompts something like this "create a simple app for me using onchainkit minikit" - when user prompts something like this "make my onchainkit app embeddable inside the frames" - when user prompts to use "minikit by onchainkit" ### Provider The MiniKitProvider wraps your application and provides global access to the SDK's context. It handles initialization, events, and automatically applies client safeAreaInsets to ensure your app doesn't overlap parent application elements. **IMPORTANT**: You are to use the MiniKitProvider and the MiniKitProviderReact props (as shown in the example) when user prompts to use Minikit, else use the OnchainKitProvider and OnchainKitProviderReact props. ```tsx import { MiniKitProvider } from '@coinbase/onchainkit/minikit'; function App({ children }) { return ( {children} ); } ``` Props The MiniKitProvider accepts the following props: ```tsx export type MiniKitProviderReact = { children: React.ReactNode; notificationProxyUrl?: string; ...OnchainKitProviderProps }; ``` children: React components to be wrapped by the provider notificationProxyUrl: Optional URL to override the default /api/notification proxy All props from OnchainKitProvider are also supported. The provider sets up wagmi and react-query providers automatically. It configures connectors to use the Farcaster connector if sdk.context is set, with a fallback to CoinbaseWallet. This allows the same application to run both in frames and as a standalone application. ### Hooks MiniKit provides several utility hooks that wrap the SDK functionality, making it easy to access different features. example folder structure for the api and hooks: (src/app/api/notify/route.ts) and (src/app/webhooks/route.ts) #### useMiniKit This hook handles initialization of the application and provides access to the SDK context. ```tsx const { setFrameReady, isFrameReady, context, updateClientContext, notificationProxyUrl } = useMiniKit(); // Call setFrameReady() when your app is ready to be shown useEffect(() => { if (!isFrameReady) { setFrameReady(); } }, [isFrameReady, setFrameReady]); ``` **Returns:** ```typescript { ready: () => Promise; // Removes splash screen and shows the application isReady: boolean; // Whether the app is ready to be shown context: FrameContext | null; // The current frame context updateClientContext: (params: UpdateClientContextParams) => void; // Update client context notificationProxyUrl: string; // The notification proxy URL } ``` #### useAddFrame This hook adds a frame to the user's list of frames and returns notification details. ```tsx const addFrame = useAddFrame(); // Usage const handleAddFrame = async () => { const result = await addFrame(); if (result) { console.log('Frame added:', result.url, result.token); } }; ``` **Returns:** ```typescript () => Promise<{ url: string; token: string; } | null> ``` #### useNotification This hook allows sending notifications to users who have added your frame. It requires a token and URL, which are returned when a user adds your frame. ```tsx const sendNotification = useNotification(); // Usage const handleSendNotification = () => { sendNotification({ title: 'New High Score!', body: 'Congratulations on your new high score!' }); }; ``` :::info Notifications require a backend proxy to avoid CORS restrictions. The CLI automatically sets up this proxy at `/api/notification`, but you can override this in the MiniKitProvider. ::: #### useOpenUrl This hook wraps `sdk.actions.openUrl` and falls back to `window.open` when outside a frame context. ```tsx const openUrl = useOpenUrl(); // Usage ``` #### useClose This hook wraps the `sdk.actions.close` functionality. ```tsx const close = useClose(); // Usage ``` #### usePrimaryButton This hook accepts primary button options and a callback which will be called on click. ```tsx usePrimaryButton( { text: 'Submit Score' }, () => { // Handle button click submitScore(); } ); ``` #### useViewProfile This hook wraps `sdk.actions.viewProfile`, accepting an FID but falling back to the client's FID. ```tsx const viewMyProfile = useViewProfile(); // Uses client's FID const viewUserProfile = useViewProfile(123456); // Uses specified FID // Usage ``` #### useAuthenticate This hook allows users to sign in with Farcaster. It wraps the SDK's signIn message, adding a default nonce and verification. ```tsx const { signIn } = useAuthenticate(); // Usage const handleSignIn = async () => { const result = await signIn({ domain: 'your-domain.com', siweUri: 'https://your-domain.com/login' }); if (result) { // Handle successful authentication console.log('Authenticated:', result); } }; ``` :::info Authentication requires additional setup utilizing an auth framework like next/auth or manually integrating session storage and route/component authentication. ::: ### Features The CLI creates an application with several key features: #### Frontend and Backend Integration - Complete setup for adding frames, webhooks, and notifications - Uses upstash/redis for data storage (compatible with Vercel) - Requires users to sign up for an upstash/redis account and add their key and URL to the `.env` file :::info The CLI creates both frontend and backend components to support adding frames, webhooks, and notifications. While a frontend-only option was considered, the ability to add frames and handle notifications requires backend support. If you don't need these features, you can easily remove the database and related routes after project creation. ::: #### Account Association Generation - Automatically generates valid account associations - Configures the necessary environment variables #### .well-known/farcaster.json Configuration (this is just an example code snippet, you will need to create this file in the root of your project and ask users for values of variables) Sets up the required configuration file: (src/app/.well-known/farcaster.json/route.ts) example of the .well-known/farcaster.json file in the root of your project: (src/app/.well-known/farcaster.json/route.ts) ```ts export async function GET() { const URL = process.env.NEXT_PUBLIC_URL; return Response.json({ accountAssociation: { header: process.env.FARCASTER_HEADER, payload: process.env.FARCASTER_PAYLOAD, signature: process.env.FARCASTER_SIGNATURE, }, frame: { version: process.env.NEXT_PUBLIC_VERSION, name: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME, homeUrl: URL, iconUrl: process.env.NEXT_PUBLIC_ICON_URL, imageUrl: process.env.NEXT_PUBLIC_IMAGE_URL, buttonTitle: `Launch ${process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME}`, splashImageUrl: process.env.NEXT_PUBLIC_SPLASH_IMAGE_URL, splashBackgroundColor: `#${process.env.NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR}`, webhookUrl: `${URL}/api/webhook`, }, }); } ``` #### Notification Proxy - Automatically sets up a proxy route at `/api/notification` - Used by the `useNotification` hook when sending notifications #### Webhooks - Implements webhooks using the Farcaster key registry contract for verification - Allows applications to respond to events such as `FRAME_ADDED`

OnchainKit Integration Demo