cLang - LangGraph Celo Agent Template

A professional, modular template for building AI agents with LangGraph that interact with the Celo blockchain. Features a modern React frontend with Atomic Design principles and a robust FastAPI backend.

📝 Description

This template provides a scalable foundation for creating Web3 AI agents that can:

• Query token balances on Celo blockchain
• Transfer ERC-20 tokens
• Interact with users through a chat interface
• Handle complex blockchain operations through natural language

Built with professional development practices - modular architecture, TypeScript, CSS Modules, and comprehensive error handling.

🏗️ Architecture

• Backend: FastAPI + LangGraph for agent orchestration
• Frontend: React + TypeScript + Vite with Atomic Design
• Styling: Tailwind CSS v4 + CSS Modules + Design System
• Blockchain: Celo blockchain integration (Alfajores testnet)

🚀 Installation Guide

Prerequisites

• Python 3.8+ - Download here
• Node.js 16+ - Download here
• AI API Key - Anthropic, OpenAI, or Grok account
• Celo Wallet - Create testnet wallet

Step 1: Fork & Clone

# Fork this repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/langgraph-celo-agent-template.git
cd langgraph-celo-agent-template

Step 2: Backend Setup

cd backend

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or for Windows:
# venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Create environment configuration
cp .env.example .env

# Edit .env file with your credentials:
# Required:
#   AI_PROVIDER=anthropic  # Options: anthropic, openai, grok
#   ANTHROPIC_API_KEY=your_key_here  # or OPENAI_API_KEY or GROK_API_KEY
#   CELO_RPC_URL=https://alfajores-forno.celo-testnet.org
#   PRIVATE_KEY=0x...  # Your Celo wallet private key
#   PUBLIC_ADDRESS=0x...  # Your Celo wallet address
#   ERC20_CONTRACT_ADDRESS=0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1  # CELO testnet

# Start the backend server
uvicorn server.api:app --reload

Step 3: Frontend Setup (New Terminal)

cd frontend

# Install Node.js dependencies
npm install

# Configure frontend environment (optional)
cp .env.example .env
# Edit .env if needed:
#   VITE_BACKEND_URL=http://localhost:8000

# Start the development server
npm run dev

Step 4: Access Your Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

🔑 Getting Your Credentials

AI API Keys

• Anthropic: Get key at console.anthropic.com
• OpenAI: Get key at platform.openai.com
• Grok: Get key at console.x.ai

Celo Testnet Setup

1. Install MetaMask or Valora
2. Add Alfajores testnet:
   • Network: Alfajores Testnet
   • RPC: https://alfajores-forno.celo-testnet.org
   • Chain ID: 44787
   • Symbol: CELO
3. Get testnet funds at faucet.celo.org
4. Export your private key from wallet settings

🛠️ Environment Variables

Backend (.env)

# AI Configuration (choose one)
AI_PROVIDER=anthropic  # Options: anthropic, openai, grok
ANTHROPIC_API_KEY=your_anthropic_key
# or
# AI_PROVIDER=openai
# OPENAI_API_KEY=your_openai_key
# or
# AI_PROVIDER=grok
# GROK_API_KEY=your_grok_key

# Celo Blockchain
CELO_RPC_URL=https://alfajores-forno.celo-testnet.org
PRIVATE_KEY=0x_your_private_key
PUBLIC_ADDRESS=0x_your_wallet_address
ERC20_CONTRACT_ADDRESS=0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1

Frontend (.env) - Optional

VITE_BACKEND_URL=http://localhost:8000

🎯 Use Cases

Perfect for:

• Learning Web3 + AI integration
• Building blockchain-aware chatbots
• Prototyping DeFi automation tools
• Educational Web3 development

📄 License

MIT License - feel free to extend and adapt for your projects.