Technical architecture

System flow

AI Agent / Builder Runtime
        |
        | MCP JSON-RPC
        v
Celo PayGrid MCP HTTP
        |
        | ERC-8004 signed backend request
        v
Celo PayGrid Backend API
        |
        | viem contract writes / reads
        v
PaygridLink + PaygridRouter on Celo Mainnet
        |
        | PaymentReceived event
        v
Indexer
        |
        | normalized payment state
        v
Supabase
        |
        | payment lookup / verification
        v
MCP verify_payment + Frontend checkout status

Components

MCP HTTP service

The MCP service exposes JSON-RPC tools, serves public metadata, protects write tools with an API key and signs protected backend requests with the configured agent key.

Backend API

The backend creates payment requests, reads state, prepares transaction payloads, validates ERC-8004 signed requests, applies rate limits and writes normalized state to Supabase.

Contracts

PaygridLink stores request state. PaygridRouter coordinates settlement and emits payment events on Celo Mainnet.

Indexer

The indexer watches PaymentReceived events from the router and updates confirmed payment records.

Supabase

Supabase stores agents, payment links, payments, onramp sessions, users and migration state.

Trust boundaries

ERC-8004 signed request format

paygrid:erc8004:<agentId>:<address>:<METHOD>:<path>:<timestamp>:<nonce>

Deployment shape