---
name: celo
description: Use when building EVM-compatible dApps, AI agents, or blockchain
  infrastructure on Celo L2. Reach for this skill when developers need to deploy
  smart contracts, integrate wallets, implement fee abstraction, operate nodes,
  or build payment applications with stablecoins.
metadata:
  mintlify-proj: celo
  version: "1.0"
---

# Celo Skill

## Product Summary

Celo is an Ethereum Layer 2 blockchain optimized for real-world payments, AI agents, and financial applications. It is fully EVM-compatible with 1-second block finality, sub-cent transaction fees, and native support for stablecoin payments and fee abstraction (paying gas in USDC, USDT, or other ERC20 tokens instead of CELO).

**Key files and commands:**
- `npx @celo/celo-composer@latest create` — scaffold a new Celo app with Next.js frontend and optional smart contracts
- `celocli` — command-line tool for interacting with Celo protocol contracts, accounts, governance, and staking
- `viem` — recommended Web3 library with native CIP-64 support for fee abstraction
- RPC endpoints: `https://forno.celo.org` (mainnet), `https://forno.celo-sepolia.celo-testnet.org` (testnet)
- Testnet faucet: `https://faucet.celo.org/celo-sepolia` (Celo Sepolia, chain ID 11142220)

**Primary docs:** https://docs.celo.org

## When to Use

Reach for this skill when:
- **Building dApps** — scaffolding a new app, integrating wallet connection, deploying smart contracts, or adding fee abstraction
- **AI agents** — building autonomous agents that pay for services in stablecoins, use x402 or MPP for HTTP-native payments, or manage a single-token treasury
- **Payment applications** — implementing stablecoin transfers, remittances, or merchant payments without requiring users to hold CELO
- **Node operations** — running a full node, archive node, or public RPC endpoint on Celo L2
- **Contract verification** — verifying deployed contracts on Blockscout or Celoscan
- **Wallet integration** — connecting users via MetaMask, Ledger, MiniPay, Valora, or other EVM wallets
- **Indexing blockchain data** — querying contract events and state with The Graph, Envio, SubQuery, or other indexers
- **Cross-chain operations** — bridging assets between Ethereum and Celo, or using cross-chain messaging

## Quick Reference

### Celo Composer Templates

| Template | Use Case | Includes |
|----------|----------|----------|
| `basic` | Standard web app | Next.js, Tailwind, wallet connector (RainbowKit default) |
| `farcaster-miniapp` | Farcaster Mini App | Farcaster SDK, wallet setup |
| `minipay` | Mobile-first app | MiniPay wallet integration, mobile UI |
| `ai-chat` | AI chat application | Standalone Next.js chat app |
| `x402` | Paid API | x402 endpoint, buyer script, USDC payments |

### CLI Installation & Setup

```bash
# Install via Homebrew (macOS/Linux)
brew tap celo-org/brew && brew install celocli

# Or via npm
npm install -g @celo/celocli

# Configure node endpoint
celocli config:set --node=https://forno.celo.org

# Verify connection
celocli config:get
```

### Web3 Libraries

| Library | Celo Support | Use Case |
|---------|--------------|----------|
| **viem** | Native CIP-64 | Recommended for all apps and agents; fee abstraction built-in |
| **ethers.js** | Wrapper available | Legacy support; use Celo Ethers.js wrapper for fee abstraction |
| **web3.js** | Plugin available | Legacy support; use @celo/web3-plugin-transaction-types |
| **ContractKit** | Deprecated | Internal use only; migrate to viem |

### Fee Abstraction Quick Setup (viem)

```typescript
import { createWalletClient, http } from "viem";
import { celoSepolia } from "viem/chains";

const client = createWalletClient({
  account,
  chain: celoSepolia,
  transport: http(),
});

// Pay gas in USDC instead of CELO
await client.writeContract({
  address: contractAddress,
  abi: contractAbi,
  functionName: "transfer",
  args: [to, amount],
  feeCurrency: "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B", // USDC adapter on Sepolia
});
```

### Network Configuration

| Network | Chain ID | RPC Endpoint | Faucet | Block Explorer |
|---------|----------|--------------|--------|----------------|
| **Celo Mainnet** | 42220 | https://forno.celo.org | — | https://celo.blockscout.com |
| **Celo Sepolia** | 11142220 | https://forno.celo-sepolia.celo-testnet.org | https://faucet.celo.org/celo-sepolia | https://celo-sepolia.blockscout.com |

### Core Contract Addresses (Mainnet)

| Contract | Address |
|----------|---------|
| CELO (native token) | 0x471EcE3750Da237f93B8E339c536989b8978a438 |
| cUSD (stablecoin) | 0xEF4d55D6dE8e8d73232827Cd1e9b2F2dBb45bC80 |
| USDC (via adapter) | 0xcebA9300f2b948710d2653dD7B07f33A8B32118C |
| FeeCurrencyDirectory | 0xb0Fe4466f288A3BbE5C2736B081B2021080DF703 |
| Registry | 0x000000000000000000000000000000000000ce10 |

## Decision Guidance

### When to Use X vs Y

| Decision | Use X When | Use Y When |
|----------|-----------|-----------|
| **Wallet library** | Building a new app or need fee abstraction support | Integrating into existing Ethereum app without fee abstraction |
| **viem** | Building agents, need fee abstraction, or starting fresh | Maintaining legacy ethers.js codebase |
| **Celo Composer** | Starting a new Celo project from scratch | Integrating Celo into existing non-Celo app |
| **Hardhat vs Foundry** | Prefer JavaScript/TypeScript tooling, need Ignition modules | Prefer Rust-like speed, advanced testing, or Solidity-native workflow |
| **Fee abstraction** | Users hold only stablecoins, building payment app, or AI agent | Users already hold CELO or prefer simplicity |
| **Testnet** | Testing before mainnet deployment | Experimenting with new features or learning |
| **Full node vs Archive node** | Serving RPC queries, running validator | Need historical state access or analytics |

## Workflow

### 1. Scaffold a New Celo App

```bash
npx @celo/celo-composer@latest create my-app \
  --template basic \
  --wallet-provider rainbowkit \
  --contracts hardhat \
  --yes

cd my-app
pnpm install
pnpm dev
```

Verify: Open `http://localhost:3000`, click **Connect Wallet**, and confirm the wallet connects.

### 2. Configure Wallet Connection

Copy `.env.template` to `.env` and fill in wallet provider credentials:

```bash
cp apps/web/.env.template apps/web/.env
# Add NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID from Reown (formerly WalletConnect)
# Or NEXT_PUBLIC_THIRDWEB_CLIENT_ID if using thirdweb
```

### 3. Deploy a Smart Contract

**With Hardhat:**

```bash
cd apps/contracts
npx hardhat compile
npx hardhat ignition deploy ./ignition/modules/Lock.ts --network celo-sepolia
```

**With Foundry:**

```bash
cd apps/contracts
forge build
forge script script/Deploy.s.sol --rpc-url https://forno.celo-sepolia.celo-testnet.org --broadcast
```

### 4. Verify Contract on Block Explorer

**Hardhat + Hardhat plugin:**

```bash
npx hardhat verify --network celo-sepolia <CONTRACT_ADDRESS> <CONSTRUCTOR_ARGS>
```

**Foundry:**

```bash
forge verify-contract \
  --chain-id 11142220 \
  --etherscan-api-key <CELOSCAN_API_KEY> \
  <CONTRACT_ADDRESS> \
  src/MyContract.sol:MyContract
```

### 5. Implement Fee Abstraction

Check the [Fee Currencies](/build/tools/contracts/fee-currencies) page for current token and adapter addresses. Use the adapter address (not token address) for 6-decimal tokens like USDC:

```typescript
const USDC_ADAPTER = "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B"; // Sepolia
await client.writeContract({
  // ... contract details ...
  feeCurrency: USDC_ADAPTER,
});
```

### 6. Run a Node

```bash
git clone https://github.com/celo-org/celo-l2-node-docker-compose
cd celo-l2-node-docker-compose
cp .env.example .env
# Edit .env with your L1 RPC endpoint and other config
docker-compose up -d
```

Monitor sync: `docker-compose logs -f op-node`

## Common Gotchas

- **Fee abstraction requires wallet support** — MetaMask drops the `feeCurrency` field; use MiniPay, Valora, Ledger Live, or a library-level wrapper. Test with the actual wallet your users will use.
- **Adapter vs token address** — USDC, USDT, and USA₮ require the adapter address (6 decimals → 18 decimals), not the token address. Using the token address silently fails.
- **ContractKit is deprecated** — Do not use for new projects. Migrate existing code to viem or ethers.js.
- **op-geth is no longer supported** — Nodes still running op-geth can follow the wrong chain. Use op-reth instead.
- **Testnet state resets** — Celo Sepolia is a fresh testnet; do not rely on state from Alfajores.
- **Gas price with fee abstraction** — Use `eth_gasPrice` with the token address parameter, not `publicClient.getGasPrice()`, when paying in alternate currencies.
- **Ledger + EIP-712** — For Safe multisig or other EIP-712 transactions, open the Eth Recovery app on your Ledger, not the Celo app.
- **Missing wallet connection** — If `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` is not set, WalletConnect flows fail silently; browser-extension wallets still work.
- **Port 3000 already in use** — Celo Composer does not fail; it takes the next free port. Always read the terminal output.

## Verification Checklist

Before submitting work:

- [ ] App scaffolded with `celo-composer` and runs locally (`pnpm dev`)
- [ ] Wallet connects and displays user address
- [ ] Smart contracts compile without errors (`pnpm contracts:compile`)
- [ ] Contracts deploy to testnet and transaction hash is recorded
- [ ] Contract verified on Blockscout or Celoscan
- [ ] Fee abstraction (if used) specifies adapter address, not token address
- [ ] `.env` file is configured with wallet provider credentials
- [ ] Node endpoint is set and verified (`celocli config:get`)
- [ ] Testnet funds obtained from faucet and balance confirmed
- [ ] Transaction signed with correct wallet (check CIP-64 support if using fee abstraction)
- [ ] No hardcoded private keys in code; use environment variables
- [ ] Tested on Celo Sepolia before deploying to mainnet

## Resources

**Comprehensive navigation:** https://docs.celo.org/llms.txt

**Critical pages:**
- [Quickstart with Celo Composer](/build/quickstart) — scaffold and run your first app
- [Fee Abstraction Guide](/build/fee-abstraction/overview) — pay gas in stablecoins
- [Celo CLI Overview](/build/tools/libraries-sdks/cli/index) — interact with protocol contracts and accounts
- [viem Library](/build/tools/libraries-sdks/viem/index) — Web3 library with native Celo support
- [Node Operator Guide](/operate/operators/overview) — run a full node or archive node
- [Build with AI Agents](/build/agents/overview) — autonomous agents with stablecoin payments

---

> For additional documentation and navigation, see: https://docs.celo.org/llms.txt