← Back to The Celo Times

Agent Integration Guide

Build AI Agents on CeloTimes

CeloTimes exposes APIs that AI agents can use to access curated Celo ecosystem intelligence — news, tweets, governance proposals, on-chain stats, and price data. First 10 API calls are free, then 0.001 cUSD per request via x402.

Available API Endpoints

GET/api/articlesx402 protected

Fetch curated Celo ecosystem news articles. Includes title, summary, source, category, and publish date.

curl "https://useful-falcon-671.convex.site/api/articles?limit=10" \
  -H "x-wallet-address: 0xYourAddress"
Params: limit(default: 20)  | Headers: x-wallet-address, x-payment-tx (after free tier)
POST/api/classifyLocal LLM (Ollama)

Classify articles into Celo ecosystem categories using local Ollama qwen2.5:1.5b model. Returns improved titles and summaries.

curl -X POST "/api/classify" \
  -H "Content-Type: application/json" \
  -d '{
    "articles": [{
      "id": "1",
      "title": "Opera proposes 160M CELO stake",
      "summary": "Browser maker seeks partnership..."
    }]
  }'
GET/api/classify/status

Check Ollama LLM connectivity and model availability.

curl "/api/classify/status"

x402 Payment Protocol

CeloTimes uses the x402 protocol for API monetization on Celo. The first 10 requests per wallet address are free. After that, each request costs 0.001 cUSD — paid on-chain and verified via Blockscout.

Step 1: Make a request

curl "https://useful-falcon-671.convex.site/api/articles" \
  -H "x-wallet-address: 0xYourAddress"

# Response includes usage info:
# { "usage": { "requests": 11, "freeRemaining": 0 } }
# If over limit: HTTP 402 with payment instructions

Step 2: Pay 0.001 cUSD on Celo

# Send 0.001 cUSD to the payment address
# cUSD contract: 0x765DE816845861e75A25fCA122bb6898B8B1282a
# Recipient: 0x000000000000000000000000000000000000dEaD
# Amount: 1000000000000000 (1e15 wei = 0.001 cUSD)

# Use Celo fee abstraction — pay gas in cUSD too!

Step 3: Retry with payment proof

curl "https://useful-falcon-671.convex.site/api/articles" \
  -H "x-wallet-address: 0xYourAddress" \
  -H "x-payment-tx: 0xYourTxHash"

# Payment is verified on-chain via Blockscout
# If valid: articles returned
# If invalid: 402 with error details

Agent Architecture

CeloTimes runs an autonomous AI agent loop every hour:

👁 Perceive

  • • Parallel AI → Web news search
  • • xAI Grok → X/Twitter KOL tweets
  • • CoinGecko → CELO price feed
  • • Blockscout → On-chain stats + epochs
  • • Celo Forum → Governance proposals

🧠 Reason

  • • Categorize (DeFi/Governance/Ecosystem/Market)
  • • Deduplicate via URL hash
  • • Score articles (recency + source + image + diversity)
  • • Select featured article with reasoning
  • • Local LLM classification (Ollama qwen2.5)

⚡ Act

  • • Store curated data in Convex DB
  • • Update featured article
  • • Generate thumbnails (Gemini)
  • • Clean old data (30-day retention)

📡 Respond

  • • Serve via real-time Convex subscriptions
  • • x402 API for agent consumption
  • • Newspaper-style UI for humans
  • • MiniPay optimized for mobile

For Agent Developers

Use as an MCP Tool

AI agents (Claude, GPT, etc.) can use the CeloTimes API as a tool to get real-time Celo ecosystem intelligence during conversations.

{
  "name": "celo_times_news",
  "description": "Get curated Celo ecosystem news, tweets, and on-chain data",
  "parameters": {
    "limit": { "type": "number", "default": 10 },
    "wallet_address": { "type": "string" }
  },
  "endpoint": "https://useful-falcon-671.convex.site/api/articles"
}

Build Trading / Governance Agents

Use CeloTimes data to power agents that:

  • • Monitor governance proposals and auto-vote based on criteria
  • • Track ecosystem partnerships for investment signals
  • • Aggregate DeFi protocol updates for yield optimization
  • • Generate daily ecosystem reports for DAOs
  • • Alert on breaking news via Telegram/Discord bots

Celo Integration Points

  • • x402 Payments: Pay per API call with cUSD on Celo
  • • Fee Abstraction: Gas paid in cUSD, no CELO needed
  • • Blockscout Verification: On-chain tx verification for payments
  • • MiniPay Ready: Mobile-first for emerging market agents
  • • Wallet Connect: RainbowKit + Celo chain for tipping

Response Format

// GET /api/articles?limit=2
{
  "data": [
    {
      "_id": "abc123",
      "title": "Opera Proposes 160M CELO Token Stake",
      "summary": "Browser maker seeks to become key network stakeholder...",
      "sourceUrl": "https://theblock.co/...",
      "sourceName": "theblock.co",
      "category": "ecosystem",
      "publishedAt": 1774115521033,
      "featured": true
    }
  ],
  "usage": {
    "requests": 1,
    "freeRemaining": 9
  }
}

Built for the Celo “Build Agents for the Real World” Hackathon

← Back to The Celo Times