Celo Agents Hackathon

Standalone guide for Celo hackathon builders using Cencori Agents.

The Goal

Build an agent that runs through Cencori and can optionally record proof of the run on Celo Sepolia.

The product hierarchy is simple:

Cencori = agent infrastructure
Celo = onchain economy and proof layer

Cencori handles the AI side: model routing, agent identity, logs, security, usage, cost, and billing infrastructure.

Celo handles the onchain side: stablecoin payments, receipts, identity, reputation, and low-cost settlement.

For the hackathon, the starter gives you a working pattern:

Agent task -> Cencori Gateway -> Run receipt -> Optional Celo Sepolia receipt hash

What You Will Build

By the end, you will have:

• A runnable Cencori-powered agent.
• A structured receipt for every agent run.
• A SHA-256 hash of that receipt.
• Optional Celo Sepolia onchain recording of the receipt hash.
• A clean base for adding x402 payments, MiniPay flows, or ERC-8004 reputation later.

Payments vs onchain proof (read this)

This starter has two separate layers:

The DEMO_PAYMENT_* env vars and the celo.payment_* fields in the receipt are storytelling metadata for judges (e.g. “this run would cost 0.05 USDC”). They are not sent to a payee onchain in this repo.

✓ Onchain today: proof that a run completed (receipt hash anchored)
✗ Not in scope yet: USDC transfer, x402 settlement, MiniPay send

If a builder’s explorer tx only shows recordRun, that is correct — they should not expect a USDC Transfer event from this starter.

Prerequisites

Required:

• Node.js 18 or newer.
• npm, pnpm, yarn, or bun.

Optional for real Cencori model calls:

• A Cencori account.
• A Cencori project API key: csk_....
• Provider access for the model you want to call.

Optional for Celo onchain recording:

• A Celo Sepolia wallet.
• Testnet funds for gas.
• A deployed AgentRunReceipts contract.

The first demo run does not require keys. It runs in simulation mode so you can start immediately.

1. Create The Starter

npx create-cencori-app my-celo-agent --template celo-agent
cd my-celo-agent

If the CLI asks to install dependencies, allow it. If you skipped installation, run:

npm install

2. Run The Demo Immediately

npm run demo

Expected simulation output:

Cencori x Celo Agent Receipt Demo
---------------------------------
Run: cencori-celo-...
Cencori request: sim_...
Receipt hash: 0x...
Receipt file: .../output/cencori-celo-....json
Onchain recorded: no (simulation mode)
Note: Missing CELO_PRIVATE_KEY or CELO_RECEIPTS_CONTRACT. Receipt generated locally but not recorded onchain.

This proves the local agent flow works.

3. Understand The Generated Files

my-celo-agent/
├── contracts/
│   └── AgentRunReceipts.sol
├── src/
│   ├── cencori-agent.mjs
│   ├── celo-record.mjs
│   ├── env.mjs
│   ├── index.mjs
│   └── receipt.mjs
├── .env
├── .env.example
├── .gitignore
├── package.json
└── README.md

Important files:

• src/index.mjs: runs the full demo.
• src/cencori-agent.mjs: sends the agent task through Cencori or simulates without a key.
• src/receipt.mjs: creates canonical receipt JSON and hashes it.
• src/celo-record.mjs: records the receipt hash on Celo Sepolia when configured.
• contracts/AgentRunReceipts.sol: tiny event contract for receipt proof.
• output/: generated local receipts.

4. Add Cencori

Path A — Project API key only (fastest)

Open .env and set:

CENCORI_API_KEY=csk_...
CENCORI_AGENT_ID=
CENCORI_BASE_URL=https://api.cencori.com/v1
CENCORI_MODEL=claude-sonnet-4-5

Leave CENCORI_AGENT_ID empty. The starter will not send X-Agent-ID, so your project key works without creating a dashboard agent first.

Path B — Dashboard agent (shadow mode, live feed, config from UI)

1. In Cencori, open your project → Agents → create an agent.
2. Copy the agent UUID and the cake_ agent API key from the agent page.
3. Set in .env:

CENCORI_API_KEY=cake_...
CENCORI_AGENT_ID=<your-agent-uuid>

The starter sends X-Agent-ID only when CENCORI_AGENT_ID is a real UUID (not placeholders like demo-agent).

Notes

• CENCORI_MODEL must be enabled for your project (configure Providers if you get a provider error).
• See Payments vs onchain proof — DEMO_PAYMENT_* does not move funds.

Run again:

npm run demo

Now the agent should call Cencori instead of returning the simulated response.

5. Deploy The Celo Receipt Contract

The generated contract is intentionally small:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;
 
contract AgentRunReceipts {
    event AgentRunRecorded(
        bytes32 indexed receiptHash,
        string indexed externalRunId,
        address indexed recorder,
        string receiptURI
    );
 
    function recordRun(
        bytes32 receiptHash,
        string calldata externalRunId,
        string calldata receiptURI
    ) external {
        emit AgentRunRecorded(receiptHash, externalRunId, msg.sender, receiptURI);
    }
}

Deploy contracts/AgentRunReceipts.sol to Celo Sepolia.

Celo Sepolia details:

Chain ID: 11142220
RPC: https://forno.celo-sepolia.celo-testnet.org
Explorer: https://celo-sepolia.blockscout.com

You can deploy with Remix, Foundry, Hardhat, or any Solidity deployment tool you prefer.

6. Enable Onchain Recording

After deploying the contract, update .env:

CELO_RPC_URL=https://forno.celo-sepolia.celo-testnet.org
CELO_PRIVATE_KEY=0x...
CELO_RECEIPTS_CONTRACT=0x...
CELO_EXPLORER_URL=https://celo-sepolia.blockscout.com

Then run:

npm run demo

Expected onchain output:

Onchain recorded: yes
Celo explorer: https://celo-sepolia.blockscout.com/tx/0x...

7. What To Show Judges

Show these four things:

• The agent task running through Cencori.
• The generated receipt file in output/ (point out celo.payment_* as planned payment metadata).
• The receipt hash printed in the terminal.
• The Celo Sepolia explorer transaction for recordRun (proof), not a USDC transfer.

Strong demo sentence:

This agent runs through Cencori for model routing, safety, observability, and spend control, then anchors a verifiable receipt hash on Celo Sepolia. Payment fields in the receipt describe intent; actual stablecoin settlement is the next layer (x402 / transfers).

Real-World Use Cases

Where x402, MiniPay, And ERC-8004 Fit

This starter focuses on receipts first because receipts are the simplest proof primitive.

Next layers:

• x402: use when an API, tool, or agent action should require payment before execution.
• MiniPay: use when the end user is a MiniPay wallet user.
• ERC-8004: use when your agent needs public identity, validation, or reputation.

Keep the stack clean:

Cencori controls the agent run.
Celo proves and settles agent activity.

Safety Rules

• Do not commit .env.
• Do not use a mainnet private key for hackathon testing.
• Use Celo Sepolia while building.
• Do not move real user funds without human approval.
• Keep full receipts in durable storage if you depend on the hash later.
• In production, use an HTTPS or IPFS receipt URI instead of a local file:// path.

Troubleshooting

Command Reference

# Create starter
npx create-cencori-app my-celo-agent --template celo-agent
 
# Enter project
cd my-celo-agent
 
# Install dependencies if needed
npm install
 
# Run demo
npm run demo
 
# Inspect generated receipts
ls output

Submission Checklist

• The app runs with npm run demo.
• The project includes a clear agent use case.
• The terminal prints a receipt hash.
• output/ contains at least one receipt JSON file.
• If using Celo, the demo prints a Celo Sepolia explorer link.
• The README or demo explains why both Cencori and Celo are used.

Links

• Cencori
• Celo
• Celo Sepolia Explorer
• Celo Build with AI
• ERC-8004
• x402