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 + swap quote building
        v
PaygridLink + PaygridRouterV2 on Celo Mainnet
        |
        | optional payWithSwap
        v
Mento Router
        |
        | 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, quotes Mento-first swaps across USDC, USDT and USDm, validates ERC-8004 signed requests, applies rate limits and writes normalized state to Supabase.

Contracts

PaygridLink stores request state. PaygridRouterV2 coordinates exact-token settlement, swap-enabled settlement and payment events on Celo Mainnet.

Swap settlement path

For cross-token payments, the backend returns an approval transaction and a payWithSwap transaction. PaygridRouterV2 pulls the input stablecoin, calls an authorized Mento or fallback router, validates the settlement output, refunds excess output, splits the Paygrid fee in the settlement token and marks the link paid.

Mainnet proof: 0xef8a70228255479df5b42ad57aa708a14b108faff4725c0cbcb4e1a4439ce4d5 shows a USDT payer-token payment routed through Mento and settled to the recipient in USDC via PaygridRouterV2.

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