name: celo-dev
description: End-to-end Celo development playbook (Feb 2026). Prefer viem for all client/transaction code (native fee currency support via CIP-64). Use thirdweb for wallet connection and React dApps. Foundry for smart contract development. Covers fee abstraction (pay gas in USDC/USDT/USDm), MiniPay Mini Apps, stablecoin integration, and AI agent infrastructure (ERC-8004 trust + x402 payments).
user-invocable: true
Celo Development Skill (viem-first)
What this Skill is for
Use this Skill when the user asks for:
-
Celo dApp UI work (React / Next.js)
-
Wallet connection + fee currency selection
-
Transactions paying gas in stablecoins (USDC, USDT, USDm)
-
MiniPay Mini App development
-
Smart contract development, testing, and deployment
-
Stablecoin integration (Mento + bridged)
-
AI agent infrastructure (ERC-8004 identity/reputation, x402 payments)
Default stack decisions (opinionated)
1. Client SDK: viem first
-
viem is REQUIRED for fee abstraction (ethers.js/web3.js don't support feeCurrency)
-
Use viem/celo for Celo-specific transaction serialization
-
Never use ethers.js for new Celo projects
import { createWalletClient, custom } from "viem";
import { celo } from "viem/chains";
const walletClient = createWalletClient({
chain: celo,
transport: custom(window.ethereum),
});
2. UI & Wallets: thirdweb
-
Use thirdweb SDK for wallet connection and React components
-
ConnectButton supports 500+ wallets including MiniPay
-
Built-in support for Celo chains
import { ConnectButton } from "thirdweb/react";
import { celo } from "thirdweb/chains";
<ConnectButton client={client} chain={celo} />
3. Fee Abstraction: always offer stablecoin gas
Celo's killer feature: pay gas fees in ERC-20 tokens without paymasters or relayers.
-
Use adapter addresses for 6-decimal tokens (USDC, USDT) - adapters normalize decimals
-
Use token addresses directly for 18-decimal tokens (USDm, EURm, REALm) - no adapter needed
-
Requires viem (ethers.js/web3.js don't support feeCurrency)
-
Only works with Celo-native wallets (MiniPay) or custom implementations
import { serializeTransaction } from "viem/celo";
import { parseGwei, parseEther } from "viem";
const USDC_ADAPTER = "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B";
const USDM_TOKEN = "0x765DE816845861e75A25fCA122bb6898B8B1282a";
const serialized = serializeTransaction({
chainId: 42220,
gas: 21001n,
feeCurrency: USDC_ADAPTER,
maxFeePerGas: parseGwei("20"),
maxPriorityFeePerGas: parseGwei("2"),
nonce: 69,
to: "0x1234512345123451234512345123451234512345",
value: parseEther("0.01"),
});
4. Smart Contracts: Foundry
-
Use Foundry (forge, cast, anvil) for all contract development
-
Fast compilation, powerful testing, built-in fuzzing
-
Native Celo verification support via Celoscan API
curl -L https://foundry.paradigm.xyz | bash && foundryup
forge init my-project && cd my-project
forge script script/Deploy.s.sol \
--rpc-url https://forno.celo-sepolia.celo-testnet.org \
--broadcast --verify
5. MiniPay: mobile-first stablecoin UX
-
Detect MiniPay via window.ethereum?.isMiniPay
-
Users have stablecoins (USDm, USDC), not CELO
-
Hide "Connect Wallet" button - connection is implicit
-
Test via MiniPay Site Tester with ngrok
function isMiniPay(): boolean {
return typeof window !== "undefined" &&
window.ethereum?.isMiniPay === true;
}
6. AI Agents: ERC-8004 + x402
For AI agent development on Celo:
-
ERC-8004: On-chain identity, reputation, and trust verification
-
x402: HTTP-native micropayments with stablecoins
const summary = await reputationRegistry.getSummary(agentId);
if (summary.averageScore >= 80) {
const response = await fetchWithPayment(serviceUrl);
}
Operating procedure
1. Classify the task layer
| Layer | Tools |
|-------|-------|
| UI/wallet/hooks | viem + thirdweb |
| Scripts/backend | viem directly |
| Smart contracts | Foundry (forge) |
| MiniPay apps | MiniPay detection + stablecoin UX |
| AI agents | ERC-8004 + x402 |
2. Pick the right fee currency approach
| Scenario | Approach |
|----------|----------|
| User has MiniPay | Offer fee currency selection |
| User has MetaMask | Must pay in CELO (no fee abstraction) |
| Server-side/scripts | Always use fee currency with viem |
3. Implement with Celo-specific correctness
Always be explicit about:
-
Network: Mainnet (42220) vs Sepolia (11142220)
-
Fee currency: Adapter address (6-decimal) vs token address (18-decimal)
-
Wallet compatibility: MiniPay supports fee abstraction, MetaMask does not
4. Add tests
-
Test both CELO and fee currency transactions separately
-
Test wallet connection with MiniPay detection
-
For contracts, use forge test with fuzzing
-
For MiniPay apps, test in Site Tester on real device
5. Deliverables
When implementing changes, provide:
-
Exact files changed
-
Commands to install/build/test/deploy
-
Fee currency addresses used (mainnet vs testnet)
-
Wallet compatibility notes
Quick reference
Networks
| Network | Chain ID | RPC Endpoint | Explorer |
|---------|----------|--------------|----------|
| Mainnet | 42220 | https://forno.celo.org | https://celoscan.io |
| Sepolia | 11142220 | https://forno.celo-sepolia.celo-testnet.org | https://sepolia.celoscan.io |
Fee Currency Addresses - Mainnet
Why adapters? Celo's gas calculations use 18 decimals internally. Tokens with different decimals (like USDC/USDT with 6 decimals) need adapter contracts to normalize the decimal conversion. Native Mento stablecoins (USDm, EURm, REALm) are already 18 decimals, so you use their token address directly.
| Token | Decimals | feeCurrency Address | Type |
|-------|----------|---------------------|------|
| USDC | 6 | 0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B | Adapter |
| USDT | 6 | 0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72 | Adapter |
| USDm | 18 | 0x765DE816845861e75A25fCA122bb6898B8B1282a | Token (no adapter needed) |
| EURm | 18 | 0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73 | Token (no adapter needed) |
| REALm | 18 | 0xe8537a3d056DA446677B9E9d6c5dB704EaAb4787 | Token (no adapter needed) |
Fee Currency Addresses - Celo Sepolia
| Token | Decimals | feeCurrency Address | Type |
|-------|----------|---------------------|------|
| USDC | 6 | 0x4822e58de6f5e485eF90df51C41CE01721331dC0 | Adapter |
| USDm | 18 | 0xdE9e4C3ce781b4bA68120d6261cbad65ce0aB00b | Token (no adapter needed) |
| EURm | 18 | 0xA99dC247d6b7B2E3ab48a1fEE101b83cD6aCd82a | Token (no adapter needed) |
Core Protocol Contracts - Mainnet
| Contract | Address |
|----------|---------|
| CELO Token | 0x471EcE3750Da237f93B8E339c536989b8978a438 |
| FeeCurrencyDirectory | 0x15F344b9E6c3Cb6F0376A36A64928b13F62C6276 |
| Registry | 0x000000000000000000000000000000000000ce10 |
Stablecoin Tokens - Mainnet
| Token | Address | Decimals |
|-------|---------|----------|
| USDm | 0x765DE816845861e75A25fCA122bb6898B8B1282a | 18 |
| EURm | 0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73 | 18 |
| USDC | 0xcebA9300f2b948710d2653dD7B07f33A8B32118C | 6 |
| USDT | 0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e | 6 |
Progressive disclosure (read when needed)
Detailed documentation for each topic is available in the celo-org/agent-skills repository:
Client & Frontend
Celo Features
-
fee-abstraction - Pay gas with stablecoins
-
minipay-integration - MiniPay Mini App development
-
celo-stablecoins - USDT, USDC, USDm, EURm, BRLm, XOFm, KESm, PHPm, COPm, NGNm, GHSm, GBPm, ZARm, CADm, AUDm, CHFm, JPYm, BRLA, VCHF, VEUR, VGBP, USDGLO, agEURA + COPM
-
celo-rpc - Blockchain interaction via RPC
Smart Contracts
AI Agent Infrastructure
DeFi & Bridging
Scaffolding
Official Documentation
Why Celo?
-
Fee abstraction: Pay gas in stablecoins without paymasters
-
Sub-second finality: ~1 second block times
-
Low fees: Gas costs under $0.001
-
Mobile-first: MiniPay with 12.6M activations
-
AI-native: ERC-8004 trust + x402 payments built for agents
-
Stablecoin ecosystem: Native USDT, USDC, USDm, EURm, BRLm, XOFm, KESm, PHPm, COPm, NGNm, GHSm, GBPm, ZARm, CADm, AUDm, CHFm, JPYm, BRLA, VCHF, VEUR, VGBP, USDGLO, agEURA + COPM
