CDP Explainers for LLMs
We’ve created a few documents that you can easily copy and paste into your large language model (LLM) of choice to give more context on how all of our CDP APIs works and significantly improve the accuracy of your AI-generated code.CDP SDK
Copy paste the following into an LLM or AI Agents like Cursor or Replit to help them easily understand the correct syntax of the CDP SDK, a backend set of tools for interacting with blockchain. You can also directly download the document in NodeJS or Python. In our experience, Claude 3.5 Sonnet is the best model for this task.Copy
Ask AI
# Comprehensive Coinbase Developer Platform (CDP) SDK Documentation
## Table of Contents
1. [Introduction](#introduction)
2. [Installation](#installation)
3. [SDK Configuration](#sdk-configuration)
4. [Wallet Management](#wallet-management)
5. [Address Management](#address-management)
6. [Transfers](#transfers)
7. [Trades](#trades)
8. [Smart Contract Interactions](#smart-contract-interactions)
9. [Token Deployments](#token-deployments)
10. [Message Signing](#message-signing)
11. [Balances and Transactions](#balances-and-transactions)
12. [Server-Signer Integration](#server-signer-integration)
13. [Error Handling](#error-handling)
## Introduction
The Coinbase Developer Platform (CDP) SDK provides a comprehensive set of tools for interacting with blockchain networks, managing wallets, and performing various crypto operations. This document serves as a detailed guide for developers looking to integrate the CDP SDK into their applications.
## Installation
Install the CDP SDK using npm:
bash
npm install @coinbase/coinbase-sdk
## SDK Configuration
### Configuring the SDK
Configure the SDK with your API key.
typescript
import { Coinbase } from "@coinbase/coinbase-sdk";
Coinbase.configureFromJson({ filePath: '~/Downloads/cdp_api_key.json' });
Parameters:
- `filePath`: String path to the JSON file containing your CDP API key.
Example:
typescript
Coinbase.configureFromJson({ filePath: '/home/user/cdp_api_key.json' });
### Enabling Server-Signer
Enable the Server-Signer for enhanced security in production environments.
typescript
Coinbase.useServerSigner = true;
## Wallet Management
### Creating a Wallet
Create a new wallet on a specified network.
typescript
import { Wallet, Coinbase } from "@coinbase/coinbase-sdk";
let wallet = await Wallet.create({ networkId: Coinbase.networks.BaseMainnet });
Parameters:
- `networkId`: (Optional) The network ID for the wallet. Defaults to Base Sepolia testnet.
NodeJS Network Labels:
| Network Name | Coinbase.networks Constant |
|------------------|----------------------------|
| Base Mainnet | Coinbase.networks.BaseMainnet |
| Base Sepolia | Coinbase.networks.BaseSepolia |
| Ethereum Mainnet | Coinbase.networks.EthereumMainnet |
| Polygon Mainnet | Coinbase.networks.PolygonMainnet |
| Bitcoin Mainnet | Coinbase.networks.BitcoinMainnet |
| Arbitrum Mainnet | Coinbase.networks.ArbitrumMainnet |
| Optimism Mainnet | Coinbase.networks.OptimismMainnet |
Example:
typescript
let mainnetWallet = await Wallet.create({ networkId: Coinbase.networks.BaseMainnet });
let testnetWallet = await Wallet.create(); // Defaults to Base Sepolia
### Exporting a Wallet
Export wallet data for persistence.
typescript
let data = wallet.export();
Example:
typescript
let exportedData = wallet.export();
console.log("Exported wallet data:", exportedData);
### Importing a Wallet
Import a previously exported wallet.
typescript
let importedWallet = await Wallet.import(fetchedData);
Parameters:
- `fetchedData`: The exported wallet data object.
Example:
typescript
let storedData = await fetchWalletDataFromStorage();
let restoredWallet = await Wallet.import(storedData);
### Saving Wallet Seed Locally
Save the wallet seed to a local file (for development purposes only).
typescript
wallet.saveSeed(filePath, encrypt);
Parameters:
- `filePath`: String path where the seed will be saved.
- `encrypt`: Boolean indicating whether to encrypt the seed.
Example:
typescript
wallet.saveSeed('my_wallet_seed.json', true);
### Loading Wallet Seed
Load a previously saved wallet seed.
typescript
await wallet.loadSeed(filePath);
Parameters:
- `filePath`: String path to the saved seed file.
Example:
typescript
await wallet.loadSeed('my_wallet_seed.json');
## Address Management
### Getting the Default Address
Retrieve the default address of a wallet.
typescript
let address = await wallet.getDefaultAddress();
Example:
typescript
let defaultAddress = await wallet.getDefaultAddress();
console.log("Default address:", defaultAddress.toString());
### Creating a New Address
Create a new address within a wallet.
typescript
let newAddress = await wallet.createAddress();
Example:
typescript
let additionalAddress = await wallet.createAddress();
console.log("New address created:", additionalAddress.toString());
### Listing Addresses
List all addresses in a wallet.
typescript
let addresses = wallet.getAddresses();
Example:
typescript
let allAddresses = wallet.getAddresses();
allAddresses.forEach(address => console.log(address.toString()));
## Transfers
### Creating a Transfer
Initiate a transfer of assets from one wallet to another.
ETH's asset ID is Coinbase.assets.Eth
USDC's asset ID is Coinbase.assets.Usdc
WETH's asset ID is Coinbase.assets.Weth
typescript
let transfer = await wallet.createTransfer({
amount: number,
assetId: string,
destination: string | Wallet,
gasless?: boolean
});
Parameters:
- `amount`: Number representing the amount to transfer.
- `assetId`: String identifier of the asset to transfer (e.g., `Coinbase.assets.Eth`).
- `destination`: Destination wallet or address string.
- `gasless`: (Optional) Boolean to indicate if the transfer should be gasless (for supported assets).
Example:
typescript
let transfer = await wallet.createTransfer({
amount: 0.001,
assetId: Coinbase.assets.Eth,
destination: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
});
await transfer.wait();
### Checking Transfer Status
Check the status of a transfer.
typescript
let status = await transfer.getStatus();
Example:
typescript
let transferStatus = await transfer.getStatus();
console.log("Transfer status:", transferStatus);
## Trades
### Creating a Trade
Initiate a trade between two assets.
typescript
let trade = await wallet.createTrade({
amount: number,
fromAssetId: string,
toAssetId: string
});
Parameters:
- `amount`: Number representing the amount to trade.
- `fromAssetId`: String identifier of the asset to trade from.
- `toAssetId`: String identifier of the asset to trade to.
Example:
typescript
let trade = await wallet.createTrade({
amount: 0.1,
fromAssetId: Coinbase.assets.Eth,
toAssetId: Coinbase.assets.Usdc
});
await trade.wait();
### Checking Trade Status
Check the status of a trade.
typescript
let status = await trade.getStatus();
Example:
typescript
let tradeStatus = await trade.getStatus();
console.log("Trade status:", tradeStatus);
## Smart Contract Interactions
### Invoking a Contract
Invoke a method on a smart contract.
typescript
let contractInvocation = await wallet.invokeContract({
contractAddress: string,
method: string,
args: object,
abi?: object[],
amount?: number,
assetId?: string
});
Parameters:
- `contractAddress`: String address of the contract.
- `method`: String name of the method to invoke.
- `args`: Object containing method arguments.
- `abi`: (Optional) Array of objects describing the contract ABI.
- `amount`: (Optional) Number representing the amount of native asset to send with the transaction.
- `assetId`: (Optional) String identifier of the asset to send (for payable functions).
Example:
typescript
let contractInvocation = await wallet.invokeContract({
contractAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
method: "transfer",
args: {
to: "0xRecipientAddress",
value: "1000000000000000000" // 1 token with 18 decimals
},
abi: [{
"inputs": [
{ "name": "to", "type": "address" },
{ "name": "value", "type": "uint256" }
],
"name": "transfer",
"outputs": [{ "name": "", "type": "bool" }],
"type": "function"
}]
});
await contractInvocation.wait();
## Token Deployments
### Deploying an ERC-20 Token
Deploy a new ERC-20 token contract.
typescript
let erc20 = await wallet.deployToken({
name: string,
symbol: string,
totalSupply: number
});
Parameters:
- `name`: String name of the token.
- `symbol`: String symbol of the token.
- `totalSupply`: Number representing the total supply of tokens.
Example:
typescript
let myToken = await wallet.deployToken({
name: "My Token",
symbol: "MTK",
totalSupply: 1000000
});
console.log("Token deployed at:", myToken.getContractAddress());
### Deploying an ERC-721 Token (NFT)
Deploy a new ERC-721 token (NFT) contract.
typescript
let nft = await wallet.deployNFT({
name: string,
symbol: string,
baseURI: string
});
Parameters:
- `name`: String name of the NFT collection.
- `symbol`: String symbol of the NFT collection.
- `baseURI`: String base URI for token metadata.
Example:
typescript
let myNFT = await wallet.deployNFT({
name: "My NFT Collection",
symbol: "MNFT",
baseURI: "https://api.mynft.com/metadata/"
});
console.log("NFT contract deployed at:", myNFT.getContractAddress());
### Deploying an ERC-1155 Token (Multi-Token)
Deploy a new ERC-1155 token (Multi-Token) contract.
typescript
let multiToken = await wallet.deployMultiToken({
uri: string
});
Parameters:
- `uri`: String URI for token metadata.
Example:
typescript
let myMultiToken = await wallet.deployMultiToken({
uri: "https://api.mymultitoken.com/metadata/{id}.json"
});
console.log("Multi-Token contract deployed at:", myMultiToken.getContractAddress());
## Message Signing
### Signing a Message
Sign a message using EIP-191 standard.
typescript
import { hashMessage } from "@coinbase/coinbase-sdk";
let payloadSignature = await wallet.createPayloadSignature(hashMessage(message));
Parameters:
- `message`: String message to be signed.
Example:
typescript
let message = "Hello, Coinbase!";
let signature = await wallet.createPayloadSignature(hashMessage(message));
await signature.wait();
console.log("Signature:", signature.toString());
### Signing Typed Data
Sign typed structured data using EIP-712 standard.
typescript
import { hashTypedData } from "@coinbase/coinbase-sdk";
let payloadSignature = await wallet.createPayloadSignature(hashTypedData({
domain: object,
types: object,
primaryType: string,
message: object
}));
Parameters:
- `domain`: Object containing domain data.
- `types`: Object describing the structure of the data.
- `primaryType`: String name of the primary type being signed.
- `message`: Object containing the data to be signed.
Example:
typescript
let typedData = {
domain: {
name: "My dApp",
version: "1",
chainId: 1,
verifyingContract: "0x1234567890123456789012345678901234567890"
},
types: {
Person: [
{ name: "name", type: "string" },
{ name: "wallet", type: "address" }
]
},
primaryType: "Person",
message: {
name: "John Doe",
wallet: "0x0123456789012345678901234567890123456789"
}
};
let signature = await wallet.createPayloadSignature(hashTypedData(typedData));
await signature.wait();
console.log("Typed data signature:", signature.toString());
## Balances and Transactions
### Listing Balances
List balances for all assets in a wallet.
typescript
let balances = await wallet.listBalances();
Example:
typescript
let allBalances = await wallet.listBalances();
console.log("Wallet balances:", allBalances.toString());
### Getting Balance for Specific Asset
Get the balance of a specific asset in a wallet.
typescript
let balance = await wallet.getBalance(assetId);
Parameters:
- `assetId`: String identifier of the asset.
Example:
typescript
let ethBalance = await wallet.getBalance(Coinbase.assets.Eth);
console.log("ETH balance:", ethBalance.toString());
### Listing Transactions
List transactions for an address.
typescript
let transactions = await address.listTransactions(options);
Parameters:
- `options`: (Optional) Object containing listing options.
Example:
typescript
let recentTransactions = await address.listTransactions({ limit: 10 });
recentTransactions.forEach(tx => console.log(tx.toString()));
## Server-Signer Integration
### Verifying Server-Signer Assignment
Verify if a Server-Signer is assigned to your CDP project.
typescript
import { ServerSigner } from "@coinbase/coinbase-sdk";
let serverSigner = await ServerSigner.getDefault();
Example:
typescript
try {
let signer = await ServerSigner.getDefault();
console.log("Server-Signer is assigned:", signer);
} catch (error) {
console.error("No Server-Signer assigned:", error);
}
## Error Handling
The CDP SDK uses custom error types for different scenarios. Always wrap your SDK calls in try-catch blocks to handle potential errors gracefully.
Example:
typescript
import { TimeoutError } from '@coinbase/coinbase-sdk';
try {
let transfer = await wallet.createTransfer({
amount: 0.001,
assetId: Coinbase.assets.Eth,
destination: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
});
await transfer.wait();
} catch (error) {
if (error instanceof TimeoutError) {
console.log("Transfer timed out, check status later");
} else {
console.error("Error during transfer:", error);
}
}
Contract Reads
const result = await readContract({
networkId: "base-mainnet",
contractAddress: "0xContractAddress",
method: "balanceOf",
args: { account: "0xAddress" },
abi: [/* Optional ABI array */]
});
This comprehensive guide covers the major functionalities of the CDP SDK. For the most up-to-date and detailed information, always refer to the official CDP SDK documentation.
OnchainKit
Copy paste the following into an LLM or AI Agents like Cursor or Replit to help them easily understand the correct syntax of the OnchainKit, a frontend set of ready-to-use React components and Typescript utilities. You can also directly download the document for React and TypeScript.Copy
Ask AI
# OnchainKit Complete Reference Guide
## Core Setup
### Basic Installation
bash
npm install @coinbase/onchainkit
### Required Configuration
Core provider setup needed for all OnchainKit functionality:
typescript
import { OnchainKitProvider } from '@coinbase/onchainkit';
import { base } from 'wagmi/chains';
<OnchainKitProvider
apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}
chain={base}
config={{
appearance: {
name: "Your App Name",
logo: "https://your-logo-url.com/logo.png",
mode: "auto", // "auto" | "light" | "dark"
theme: "default" // "default" | "base" | "cyberpunk" | "hacker"
}
}}
>
{children}
</OnchainKitProvider>
## Components
### Identity Components
#### `<Avatar />`
Displays ENS or Basename avatar associated with Ethereum addresses.
typescript
import { Avatar } from '@coinbase/onchainkit/identity';
// Basic usage
<Avatar address="0x123..." />
// With chain specification
<Avatar address="0x123..." chain={base} />
// With custom styling
<Avatar
address="0x123..."
className="h-6 w-6"
loadingComponent={<LoadingSpinner />}
defaultComponent={<DefaultAvatar />}
/>
#### `<Name />`
Displays ENS or Basename associated with Ethereum addresses.
typescript
import { Name } from '@coinbase/onchainkit/identity';
// Basic usage
<Name address="0x123..." />
// With chain specification
<Name address="0x123..." chain={base} />
// With custom styling
<Name
address="0x123..."
className="text-lg font-bold"
/>
#### `<Address />`
Displays formatted Ethereum addresses.
typescript
import { Address } from '@coinbase/onchainkit/identity';
// Basic usage
<Address address="0x123..." />
// With slicing disabled
<Address address="0x123..." isSliced={false} />
// With custom styling
<Address
address="0x123..."
className="text-gray-600"
/>
### Wallet Components
#### `<Wallet />`
Main container for wallet functionality.
typescript
import {
Wallet,
ConnectWallet,
WalletDropdown,
WalletDropdownDisconnect
} from '@coinbase/onchainkit/wallet';
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
<WalletDropdown>
<Identity className="px-4 pt-3 pb-2" hasCopyAddressOnClick>
<Avatar />
<Name />
<Address />
<EthBalance />
</Identity>
<WalletDropdownDisconnect />
</WalletDropdown>
</Wallet>
### Transaction Components
#### `<Transaction />`
Handles complete transaction lifecycle.
typescript
import {
Transaction,
TransactionButton,
TransactionStatus
} from '@coinbase/onchainkit/transaction';
<Transaction
contracts={[{
address: contractAddress,
abi: contractAbi,
functionName: 'functionToCall',
args: [arg1, arg2]
}]}
onStatus={(status) => console.log(status)}
>
<TransactionButton />
<TransactionStatus />
</Transaction>
### Swap Components
#### `<Swap />`
Handles token swap functionality.
typescript
import {
Swap,
SwapAmountInput,
SwapButton,
SwapMessage
} from '@coinbase/onchainkit/swap';
<Swap>
<SwapAmountInput
label="Sell"
swappableTokens={tokens}
token={fromToken}
type="from"
/>
<SwapToggleButton />
<SwapAmountInput
label="Buy"
swappableTokens={tokens}
token={toToken}
type="to"
/>
<SwapButton />
<SwapMessage />
</Swap>
## Utilities
### Identity Utilities
#### `getName`
Retrieves name from onchain identity provider.
typescript
import { getName } from '@coinbase/onchainkit/identity';
const name = await getName({
address: "0x123...",
chain: base // optional
});
#### `getAddress`
Retrieves address from onchain identity provider.
typescript
import { getAddress } from '@coinbase/onchainkit/identity';
const address = await getAddress({
name: "name.eth",
chain: base // optional
});
### Frame Utilities
#### `getFrameMetadata`
Generates Frame metadata for use in Next.js.
typescript
import { getFrameMetadata } from '@coinbase/onchainkit/frame';
const frameMetadata = getFrameMetadata({
buttons: [
{ label: "Button 1" },
{ label: "Button 2", action: "link", target: "https://example.com" }
],
image: "https://example.com/image.png",
postUrl: "https://api.example.com/frame"
});
#### `getFrameMessage`
Validates and processes Frame interaction messages.
typescript
import { getFrameMessage } from '@coinbase/onchainkit/frame';
const { isValid, message } = await getFrameMessage(frameRequest, {
neynarApiKey: "optional-key",
castReactionContext: true,
followContext: true
});
### API Utilities
#### `getTokens`
Retrieves list of tokens on Base.
typescript
import { getTokens } from '@coinbase/onchainkit/api';
const tokens = await getTokens({
limit: "50",
page: "1",
search: "USDC"
});
#### `getSwapQuote`
Gets quote for token swap.
typescript
import { getSwapQuote } from '@coinbase/onchainkit/api';
const quote = await getSwapQuote({
from: fromToken,
to: toToken,
amount: "0.1",
useAggregator: false
});
## Type Definitions
### Common Types
typescript
type Token = {
address: string;
chainId: number;
decimals: number;
image: string | null;
name: string;
symbol: string;
};
type LifecycleStatus = {
statusName: 'init' | 'error' | 'success' | /* other status names */;
statusData: any; // Varies by status
};
type Transaction = {
chainId: number;
data: string;
gas: bigint;
to: string;
value: bigint;
};
## Error Handling
All components accept `onError` callbacks for handling errors:
typescript
<Component
onError={(error) => {
console.error(error.code, error.message);
// Handle error appropriately
}}
/>
## Best Practices
1. Always wrap your app with `OnchainKitProvider`
2. Handle all lifecycle status changes through `onStatus` callbacks
3. Use appropriate error handling for all async operations
4. Follow proper component hierarchy (e.g., `Wallet` containing `ConnectWallet`)
5. Implement proper type checking using provided TypeScript definitions
## Common Patterns
### Wallet Connection Flow
typescript
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
{isConnected && (
<WalletDropdown>
<Identity hasCopyAddressOnClick>
<Avatar />
<Name />
<Address />
</Identity>
<WalletDropdownDisconnect />
</WalletDropdown>
)}
</Wallet>
### Transaction Flow
typescript
<Transaction
contracts={contracts}
onStatus={(status) => {
switch(status.statusName) {
case 'success':
// Handle success
break;
case 'error':
// Handle error
break;
// Handle other states
}
}}
>
<TransactionButton />
<TransactionStatus />
</Transaction>
# OnchainKit Components Complete Reference
## Identity Components
### `<Avatar />`
Displays ENS or Basename avatar associated with Ethereum addresses.
Props (`AvatarReact`):
typescript
type AvatarReact = {
address?: Address | null; // The Ethereum address to fetch the avatar for
chain?: Chain; // Optional chain for domain resolution
className?: string; // Optional className override for top div element
loadingComponent?: JSX.Element; // Optional custom loading component
defaultComponent?: JSX.Element; // Optional custom default component when no avatar
children?: ReactNode; // Optional attestation badge
};
Example usage:
typescript
// Basic usage
<Avatar address="0x123..." />
// With loading and default states
<Avatar
address="0x123..."
chain={base}
className="h-12 w-12 rounded-full"
loadingComponent={<Spinner />}
defaultComponent={<DefaultAvatar />}
>
<Badge /> // Optional attestation badge
</Avatar>
### `<Name />`
Displays ENS or Basename associated with addresses.
Props (`NameReact`):
typescript
type NameReact = {
address?: Address | null; // Ethereum address to be displayed
children?: ReactNode; // Optional attestation badge
chain?: Chain; // Optional chain for domain resolution
className?: string; // Optional className override
} & HTMLAttributes<HTMLSpanElement>;
Example usage:
typescript
// Basic usage
<Name address="0x123..." />
// With attestation and custom styling
<Name
address="0x123..."
chain={base}
className="text-xl font-bold"
>
<Badge />
</Name>
### `<Identity />`
Context provider for identity components.
Props (`IdentityReact`):
typescript
type IdentityReact = {
address?: Address; // The Ethereum address
chain?: Chain; // Optional chain for resolution
children: ReactNode; // Child components
className?: string; // Optional styling
schemaId?: Address | null; // Schema for attestation
hasCopyAddressOnClick?: boolean;
};
Example usage:
typescript
<Identity
address="0x123..."
schemaId="0xschema..."
hasCopyAddressOnClick
>
<Avatar />
<Name>
<Badge />
</Name>
<Address />
</Identity>
## Wallet Components
### `<Wallet />`
Main container for wallet functionality.
Props (`WalletReact`):
typescript
type WalletReact = {
children: ReactNode;
};
### `<ConnectWallet />`
Handles wallet connection interface.
Props (`ConnectWalletReact`):
typescript
type ConnectWalletReact = {
children?: ReactNode;
className?: string;
text?: string;
withWalletAggregator?: boolean;
};
### `<WalletDropdown />`
Dropdown menu for wallet interactions.
Props (`WalletDropdownReact`):
typescript
type WalletDropdownReact = {
children: ReactNode;
className?: string;
};
Complete wallet example:
typescript
<Wallet>
<ConnectWallet withWalletAggregator>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
<WalletDropdown>
<Identity className="px-4 pt-3 pb-2" hasCopyAddressOnClick>
<Avatar />
<Name />
<Address />
<EthBalance />
</Identity>
<WalletDropdownBasename />
<WalletDropdownLink
icon="wallet"
href="https://example.com"
>
Wallet
</WalletDropdownLink>
<WalletDropdownDisconnect />
</WalletDropdown>
</Wallet>
## Transaction Components
### `<Transaction />`
Handles complete transaction lifecycle.
Props (`TransactionReact`):
typescript
type TransactionReact = {
calls?: Call[] | Promise<Call[]> | (() => Promise<Call[]>);
capabilities?: WalletCapabilities;
chainId?: number;
children: ReactNode;
className?: string;
contracts?: ContractFunctionParameters[];
onError?: (e: TransactionError) => void;
onStatus?: (lifecycleStatus: LifecycleStatus) => void;
onSuccess?: (response: TransactionResponse) => void;
};
### `<TransactionButton />`
Transaction initiation button.
Props (`TransactionButtonReact`):
typescript
type TransactionButtonReact = {
className?: string;
disabled?: boolean;
text?: string;
};
Complete transaction example:
typescript
<Transaction
contracts={[{
address: contractAddress,
abi: contractAbi,
functionName: 'functionName',
args: [arg1, arg2]
}]}
onStatus={(status) => {
if (status.statusName === 'success') {
console.log('Transaction successful');
}
}}
>
<TransactionButton text="Submit Transaction" />
<TransactionStatus>
<TransactionStatusLabel />
<TransactionStatusAction />
</TransactionStatus>
<TransactionToast />
</Transaction>
## Swap Components
### `<Swap />`
Handles token swap functionality.
Props (`SwapReact`):
typescript
type SwapReact = {
children: ReactNode;
className?: string;
config?: SwapConfig;
experimental?: {
useAggregator: boolean;
};
isSponsored?: boolean;
onError?: (error: SwapError) => void;
onStatus?: (lifecycleStatus: LifecycleStatus) => void;
onSuccess?: (receipt: TransactionReceipt) => void;
title?: string;
};
### `<SwapAmountInput />`
Input field for swap amounts.
Props (`SwapAmountInputReact`):
typescript
type SwapAmountInputReact = {
className?: string;
delayMs?: number;
label: string;
swappableTokens?: Token[];
token?: Token;
type: 'to' | 'from';
};
Complete swap example:
typescript
<Swap
isSponsored={true}
onStatus={(status) => {
if (status.statusName === 'success') {
console.log('Swap successful');
}
}}
>
<SwapAmountInput
label="Sell"
swappableTokens={tokens}
token={fromToken}
type="from"
/>
<SwapToggleButton />
<SwapAmountInput
label="Buy"
swappableTokens={tokens}
token={toToken}
type="to"
/>
<SwapButton />
<SwapMessage />
<SwapToast />
</Swap>
## Fund Components
### `<FundButton />`
Provides access to funding options.
Props (`FundButtonReact`):
typescript
type FundButtonReact = {
className?: string;
disabled?: boolean;
text?: string;
hideText?: boolean;
hideIcon?: boolean;
fundingUrl?: string;
openIn?: 'popup' | 'tab';
popupSize?: 'sm' | 'md' | 'lg';
rel?: string;
target?: string;
};
Example usage:
typescript
// Basic usage
<FundButton />
// Customized
<FundButton
text="Add Funds"
openIn="popup"
popupSize="lg"
fundingUrl={customUrl}
className="bg-blue-500 text-white"
/>
## Frame Components
### `<FrameMetadata />`
Handles Frame metadata for social platforms.
Props (`FrameMetadataReact`):
typescript
type FrameMetadataReact = FrameMetadataType & {
ogDescription?: string;
ogTitle?: string;
wrapper?: React.ComponentType<any>;
};
Example usage:
typescript
<FrameMetadata
buttons={[
{ label: 'Action 1' },
{
action: 'link',
label: 'Visit Site',
target: 'https://example.com'
}
]}
image={{
src: 'https://example.com/image.png',
aspectRatio: '1:1'
}}
input={{
text: 'Enter text...'
}}
postUrl="https://api.example.com/frame"
/>
## Component Combinations
### Identity with Wallet
typescript
<Identity address="0x123..." hasCopyAddressOnClick>
<Wallet>
<ConnectWallet>
<Avatar className="h-6 w-6" />
<Name />
</ConnectWallet>
<WalletDropdown>
<Avatar />
<Name>
<Badge />
</Name>
<Address />
<EthBalance />
<WalletDropdownDisconnect />
</WalletDropdown>
</Wallet>
</Identity>
### Transaction with Swap
typescript
<Transaction>
<Swap>
<SwapAmountInput type="from" token={tokenA} />
<SwapToggleButton />
<SwapAmountInput type="to" token={tokenB} />
<SwapButton />
<SwapMessage />
<TransactionStatus />
</Swap>
</Transaction>
### Common State Management Patterns
typescript
// Lifecycle status handling
const handleStatus = (status: LifecycleStatus) => {
switch (status.statusName) {
case 'init':
// Handle initialization
break;
case 'success':
// Handle success
break;
case 'error':
// Handle error
break;
default:
// Handle other states
}
};
// Using in components
<Transaction onStatus={handleStatus}>
{/* Component children */}
</Transaction>
# OnchainKit Checkout Component Reference
## Core Components
### `<Checkout />`
Main container for checkout functionality. Handles payment processing and transaction lifecycle.
Props (`CheckoutReact`):
typescript
type CheckoutReact = {
chargeHandler?: () => Promise<string>; // Custom charge creation handler
children: React.ReactNode; // Child components
className?: string; // Optional styling
isSponsored?: boolean; // Enable gas sponsorship
onStatus?: (status: LifecycleStatus) => void; // Status callback
productId?: string; // Coinbase Commerce product ID
};
### `<CheckoutButton />`
Initiates the checkout process.
Props (`CheckoutButtonReact`):
typescript
type CheckoutButtonReact = {
className?: string; // Optional styling
coinbaseBranded?: boolean; // Show Coinbase branding
disabled?: boolean; // Disable button
icon?: React.ReactNode; // Custom icon
text?: string; // Button text
};
### `<CheckoutStatus />`
Displays current checkout status.
Props (`CheckoutStatusReact`):
typescript
type CheckoutStatusReact = {
className?: string; // Optional styling
};
## Basic Implementation
typescript
import {
Checkout,
CheckoutButton,
CheckoutStatus
} from '@coinbase/onchainkit/checkout';
// Simple implementation with product ID
<Checkout productId="your-product-id">
<CheckoutButton />
<CheckoutStatus />
</Checkout>
// With Coinbase branding and custom text
<Checkout productId="your-product-id">
<CheckoutButton
coinbaseBranded
text="Pay with Crypto"
/>
<CheckoutStatus />
</Checkout>
## Advanced Implementation
### With Status Handling
typescript
import { Checkout, CheckoutButton } from '@coinbase/onchainkit/checkout';
import type { LifecycleStatus } from '@coinbase/onchainkit/checkout';
function CheckoutComponent() {
const handleStatus = async (status: LifecycleStatus) => {
const { statusName, statusData } = status;
switch (statusName) {
case 'success':
const { chargeId, transactionReceipt, receiptUrl } = statusData;
// Handle successful payment
break;
case 'error':
// Handle error
break;
case 'pending':
// Handle pending state
break;
}
};
return (
<Checkout
productId="your-product-id"
onStatus={handleStatus}
isSponsored={true}
>
<CheckoutButton coinbaseBranded />
<CheckoutStatus />
</Checkout>
);
}
### Custom Charge Handler (Shopping Cart)
typescript
import { Checkout, CheckoutButton } from '@coinbase/onchainkit/checkout';
function ShoppingCartCheckout() {
const createCharge = async () => {
// Create charge on your backend
const response = await fetch('api/createCharge', {
method: 'POST',
body: JSON.stringify({
// Cart details
items: cart.items,
total: cart.total
})
});
const data = await response.json();
return data.chargeId;
};
return (
<Checkout chargeHandler={createCharge}>
<CheckoutButton text="Complete Purchase" />
<CheckoutStatus />
</Checkout>
);
}
## Lifecycle Status Types
typescript
type LifecycleStatus =
| {
statusName: 'init';
statusData: LifecycleStatusDataShared;
}
| {
statusName: 'error';
statusData: TransactionError;
}
| {
statusName: 'fetchingData';
statusData: LifecycleStatusDataShared;
}
| {
statusName: 'ready';
statusData: {
chargeId: string;
contracts: ContractFunctionParameters[];
};
}
| {
statusName: 'pending';
statusData: LifecycleStatusDataShared;
}
| {
statusName: 'success';
statusData: {
transactionReceipts: TransactionReceipt[];
chargeId: string;
receiptUrl: string;
};
};
## Style Customization
### Basic Styling
typescript
<Checkout productId="your-product-id">
<CheckoutButton
className="bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded"
/>
<CheckoutStatus
className="mt-4 text-sm text-gray-600"
/>
</Checkout>
### With Themed Components
typescript
<OnchainKitProvider
config={{
appearance: {
theme: 'custom',
mode: 'dark'
}
}}
>
<Checkout productId="your-product-id">
<CheckoutButton coinbaseBranded />
<CheckoutStatus />
</Checkout>
</OnchainKitProvider>
## Best Practices
1. **Error Handling**
typescript
<Checkout
productId="your-product-id"
onStatus={(status) => {
if (status.statusName === 'error') {
const { code, message } = status.statusData;
// Handle specific error cases
switch (code) {
case 'INSUFFICIENT_FUNDS':
notifyUser('Insufficient funds for purchase');
break;
// Handle other error cases
}
}
}}
>
<CheckoutButton />
<CheckoutStatus />
</Checkout>
2. **Transaction Verification**
typescript
const verifyCharge = async (chargeId: string) => {
const response = await fetch(`https://api.commerce.coinbase.com/charges/${chargeId}`, {
headers: {
'X-CC-Api-Key': 'your_api_key',
'Content-Type': 'application/json'
}
});
return response.json();
};
<Checkout
productId="your-product-id"
onStatus={async (status) => {
if (status.statusName === 'success') {
const { chargeId } = status.statusData;
const verification = await verifyCharge(chargeId);
// Handle verification result
}
}}
>
<CheckoutButton />
<CheckoutStatus />
</Checkout>
3. **Custom Button States**
typescript
<Checkout productId="your-product-id">
<CheckoutButton
text={isLoading ? 'Processing...' : 'Complete Purchase'}
disabled={isLoading || !isValid}
className={`
${isLoading ? 'opacity-50 cursor-not-allowed' : ''}
${!isValid ? 'bg-gray-300' : 'bg-blue-500 hover:bg-blue-600'}
`}
/>
<CheckoutStatus />
</Checkout>