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";  



// For 6-decimal tokens (USDC, USDT): use ADAPTER address 

const USDC_ADAPTER = "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B";  



// For 18-decimal tokens (USDm, EURm): use TOKEN address directly 

const USDM_TOKEN = "0x765DE816845861e75A25fCA122bb6898B8B1282a";  



const serialized = serializeTransaction({   

  chainId: 42220,   

  gas: 21001n,   

  feeCurrency: USDC_ADAPTER, // or USDM_TOKEN for USDm   

  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


# Install Foundry 

curl -L https://foundry.paradigm.xyz | bash && foundryup  



# Create project 

forge init my-project && cd my-project  



# Deploy to Celo Sepolia 

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


// Verify agent trust before interaction 

const summary = await reputationRegistry.getSummary(agentId); 

if (summary.averageScore >= 80) {   

  // Make paid request to trusted agent   

  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

|---------|----------|--------------|----------|

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.

|-------|----------|---------------------|------|

Fee Currency Addresses - Celo Sepolia

|-------|----------|---------------------|------|

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

viem - TypeScript client with fee currency support
wagmi - React hooks for Celo dApps
thirdweb - Full-stack Web3 development
evm-wallet-integration - Wallet connection patterns

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

evm-foundry - Foundry development (recommended)
contract-verification - Celoscan, Blockscout, Sourcify

AI Agent Infrastructure

8004 - ERC-8004 Agent Trust Protocol
x402 - HTTP-native agent payments

DeFi & Bridging

celo-defi - DeFi protocol integration
bridging - Asset bridging to/from Celo

Scaffolding

celo-composer - Project templates and scaffolding

Official Documentation

Token Contracts - All token addresses
Core Contracts - Protocol contract addresses
Fee Currency - Fee abstraction guide
MiniPay - Mini App development

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

Celo Agent Skills

Description