From e883febc6d18801f9fd38c09e71dec95af1d305c Mon Sep 17 00:00:00 2001 From: Viral Sangani Date: Mon, 13 Jul 2026 21:08:55 -0700 Subject: [PATCH 1/3] docs: add MPP (Machine Payments Protocol) page Add a Build with AI > Agent Infrastructure page for MPP on Celo: - what MPP is (HTTP-native machine payments) and how the charge flow works - seller + buyer code examples using the mppx SDK, verified end-to-end on Celo - links to the runnable example repo celo-org/mpp-celo-example - scoped to MPP's one-time charge intent (what Celo supports today) Co-Authored-By: Claude Opus 4.8 --- build-on-celo/build-with-ai/mpp.mdx | 169 ++++++++++++++++++++++++++++ docs.json | 1 + 2 files changed, 170 insertions(+) create mode 100644 build-on-celo/build-with-ai/mpp.mdx diff --git a/build-on-celo/build-with-ai/mpp.mdx b/build-on-celo/build-with-ai/mpp.mdx new file mode 100644 index 000000000..05b0d7346 --- /dev/null +++ b/build-on-celo/build-with-ai/mpp.mdx @@ -0,0 +1,169 @@ +--- +title: "MPP: Machine Payments Protocol" +sidebarTitle: "MPP: Payments" +--- + +The **Machine Payments Protocol (MPP)** is an open standard for HTTP-native payments — it gives meaning to the HTTP `402 Payment Required` status code so that agents, apps, and services can pay each other for API access in a single request, with no accounts, invoices, or checkout flows. + +On Celo, MPP lets any service charge **USDC** per request. The buyer pays **no gas** — settlement is handled on-chain by a hosted facilitator. + +## How it works + +A request with no payment gets a `402` carrying an MPP **Challenge**. The buyer signs a **Credential** and retries; the server settles the payment on Celo and returns a **Receipt** with the on-chain transaction. + +```mermaid +sequenceDiagram + participant Buyer as Buyer (agent/app) + participant Seller as Your API + participant Facilitator as Facilitator + participant Chain as Celo + + Buyer->>Seller: 1. GET /premium (no payment) + Seller-->>Buyer: 2. 402 + WWW-Authenticate: Payment (challenge) + Buyer->>Buyer: 3. Sign credential (EIP-3009, no gas) + Buyer->>Seller: 4. Retry with Authorization (credential) + Seller->>Facilitator: 5. Settle + Facilitator->>Chain: 6. Submit USDC transfer, pay gas + Chain-->>Facilitator: 7. Confirmed + Facilitator-->>Seller: 8. Settlement reference + Seller-->>Buyer: 9. 200 + Payment-Receipt (tx hash) +``` + +USDC moves buyer → seller directly inside the token contract. The facilitator +submits the transaction and pays the gas; it never custodies funds. + +## Prerequisites + +Settlement runs through a hosted facilitator that charges a small credit per +transaction. Get an API key (a human does this once): + +1. Open [x402.celo.org](https://x402.celo.org) and connect an EVM wallet. +2. Click **Create API key** and sign the message (no gas, no transaction). +3. Copy the key (shown once) — it looks like `x402_...`. +4. Set it as `X402_API_KEY` in your project. + +New accounts start with free testnet and mainnet credits. Develop on **Celo +Sepolia** first. + +## Build with MPP + +Install the [`mppx`](https://www.npmjs.com/package/mppx) SDK. + +```bash +npm i mppx @hono/node-server hono viem +``` + +### Seller — charge for your API + +Configure MPP with one payment method — a one-time EVM charge on Celo — and +settle through the Celo facilitator. Passing the known asset +(`assets.celoSepolia.USDC`) lets `mppx` infer the chain id, decimals, and EIP-712 +domain for you. + +```ts +import { serve } from "@hono/node-server"; +import { Hono } from "hono"; +import { Mppx } from "mppx/server"; +import { evm, assets } from "mppx/evm/server"; + +// Attach the facilitator API key to every settlement request. +const apiKeyFetch: typeof fetch = (input, init = {}) => { + const headers = new Headers(init.headers); + headers.set("X-API-Key", process.env.X402_API_KEY!); + return fetch(input, { ...init, headers }); +}; + +const mppx = Mppx.create({ + methods: [ + evm.charge({ + currency: assets.celoSepolia.USDC, // Celo Sepolia (mainnet: assets.celo.USDC) + recipient: process.env.SELLER_PAY_TO as `0x${string}`, // your receiving wallet + x402: { + facilitator: "https://api.x402.sepolia.celo.org", // mainnet: https://api.x402.celo.org + fetch: apiKeyFetch, + }, + }), + ], + secretKey: process.env.MPP_SECRET_KEY!, // openssl rand -base64 32 +}); + +const app = new Hono(); +app.get("/premium", async (c) => { + const result = await mppx.charge({ amount: "0.01" })(c.req.raw); // $0.01 + if (result.status === 402) return result.challenge; + return result.withReceipt(Response.json({ data: "this response cost $0.01" })); +}); + +serve({ fetch: app.fetch, port: 3402 }); +``` + +### Buyer — pay automatically + +The `mppx` client patches `fetch` to answer MPP challenges automatically. The +buyer needs a wallet funded with USDC and **no** native gas. + +```ts +import { privateKeyToAccount } from "viem/accounts"; +import { Mppx } from "mppx/client"; +import { evm } from "mppx/evm/client"; + +const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY as `0x${string}`); + +Mppx.create({ + methods: [ + evm.charge({ + account, + networks: [11142220], // Celo Sepolia (mainnet: 42220) + currencies: ["0x01C5C0122039549AD1493B8220cABEdD739BC44E"], // Celo Sepolia USDC + decimals: 6, + authorization: { name: "USDC", version: "2" }, // Celo USDC EIP-712 domain + maxAmount: "1", // never pay more than 1 USDC per request + }), + ], +}); + +// Global fetch now pays MPP-gated endpoints automatically. +const res = await fetch("http://localhost:3402/premium"); +console.log(res.status, await res.json()); // 200, your paid content +``` + + + On the **buyer** side you must supply the token `decimals` and its EIP-712 + `authorization` (`{ name, version }`) — the client builds the payment + credential locally and does not read these from the server's challenge. For + Celo USDC the domain is `name: "USDC"`, `version: "2"`. + + +## Example project + +A complete, runnable seller + buyer you can clone and run in minutes — verified +end-to-end on Celo testnet and mainnet: + + + Minimal MPP example on Celo — a paid API and a client that pays it. + + +```bash +git clone https://github.com/celo-org/mpp-celo-example +cd mpp-celo-example +npm install +cp .env.example .env # add MPP_SECRET_KEY, X402_API_KEY, SELLER_PAY_TO, BUYER_PRIVATE_KEY +npm run seller # terminal 1 +npm run buyer # terminal 2 — pays and prints the settlement tx +``` + +## Supported assets on Celo + +| Token | Network | Address | +|-------|---------|---------| +| USDC | Celo mainnet | `0xcebA9300f2b948710d2653dD7B07f33A8B32118C` | +| USDC | Celo Sepolia | `0x01C5C0122039549AD1493B8220cABEdD739BC44E` | + +Both are 6-decimal and support gasless EIP-3009 transfers. + +## Resources + +- MPP protocol: [mpp.dev](https://mpp.dev) +- `mppx` SDK: [npmjs.com/package/mppx](https://www.npmjs.com/package/mppx) +- Facilitator dashboard (API key + credits): [x402.celo.org](https://x402.celo.org) +- Example repo: [celo-org/mpp-celo-example](https://github.com/celo-org/mpp-celo-example) diff --git a/docs.json b/docs.json index c103780ed..70cd02d6c 100644 --- a/docs.json +++ b/docs.json @@ -133,6 +133,7 @@ "pages": [ "build-on-celo/build-with-ai/8004", "build-on-celo/build-with-ai/x402", + "build-on-celo/build-with-ai/mpp", "build-on-celo/build-with-ai/celopedia", "build-on-celo/build-with-ai/vibe-coding" ] From 734dd355a8fae2c96227dcdf7e37a856a96e2fc6 Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Wed, 15 Jul 2026 20:37:15 +0100 Subject: [PATCH 2/3] Surface MPP and x402 on the AI overview and home pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an MPP card to the "AI Agent Infrastructure" grid on the home page, and mention x402 + MPP on the Build with AI overview — both inline in the intro and in a new "Agent Payments with x402 and MPP" section. Co-Authored-By: Claude Opus 4.8 --- build-on-celo/build-with-ai/overview.mdx | 11 ++++++++++- home/celo.mdx | 3 +++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/build-on-celo/build-with-ai/overview.mdx b/build-on-celo/build-with-ai/overview.mdx index 2f5102e34..bd3085553 100644 --- a/build-on-celo/build-with-ai/overview.mdx +++ b/build-on-celo/build-with-ai/overview.mdx @@ -7,7 +7,7 @@ sidebarTitle: "Overview" Celo is a leading Ethereum Layer 2 optimized for agentic activity with real-world utility, enabling AI agents to autonomously perform onchain actions tied directly to payments, commerce, and financial coordination. -Agents on Celo can tap into the network's expansive payments ecosystem, leveraging fast finality, sub-cent transaction costs, and a stablecoin-optimized financial stack spanning peer-to-peer transfers, merchant payments, remittances, and onchain FX. Combined with native support for AI agent standards like [ERC-8004](/build-on-celo/build-with-ai/8004) and Celo's [Celopedia](/build-on-celo/build-with-ai/celopedia), Celo provides a production-ready environment for deploying AI agents that do more than trade tokens—they move money, coordinate economic activity, and interact with real users at global scale. +Agents on Celo can tap into the network's expansive payments ecosystem, leveraging fast finality, sub-cent transaction costs, and a stablecoin-optimized financial stack spanning peer-to-peer transfers, merchant payments, remittances, and onchain FX. Combined with native support for agent standards like [ERC-8004](/build-on-celo/build-with-ai/8004) for trust, [x402](/build-on-celo/build-with-ai/x402) and [MPP](/build-on-celo/build-with-ai/mpp) for HTTP-native payments, and Celo's [Celopedia](/build-on-celo/build-with-ai/celopedia), Celo provides a production-ready environment for deploying AI agents that do more than trade tokens—they move money, coordinate economic activity, and interact with real users at global scale. ## Why Build AI Agents on Celo @@ -51,6 +51,15 @@ On Celo, agents are first-class participants in the economy. They can send and r - Collaborative systems where agents work together. - Examples: Collective problem-solving, distributed decision-making, or agent-to-agent communication. +## Agent Payments with x402 and MPP + +Agents on Celo can charge and pay for services over plain HTTP, settling in stablecoins in a single request — no accounts, invoices, or checkout flows. + +- **[x402](/build-on-celo/build-with-ai/x402)** gives meaning to the HTTP `402 Payment Required` status code, letting an agent settle a stablecoin micropayment inline with the request. +- **[MPP (Machine Payments Protocol)](/build-on-celo/build-with-ai/mpp)** builds on the same flow so any service can charge USDC per request through a hosted facilitator — the buyer pays no gas. + +Both settle on-chain in seconds, making them well-suited to paid APIs, pay-per-use tools, and agent-to-agent commerce. + ## Fee Abstraction for Agents AI agents on Celo can pay gas fees in stablecoins like USDC or USDT instead of needing a separate CELO balance. This simplifies agent treasury management to a single token — the same stablecoin the agent already holds for payments and settlements. diff --git a/home/celo.mdx b/home/celo.mdx index 06bc707b0..849f36b2b 100644 --- a/home/celo.mdx +++ b/home/celo.mdx @@ -35,6 +35,9 @@ description: "Celo is a leading Ethereum L2. As the frontier chain for global im Enable instant, permissionless micropayments for AI agents using stablecoins via HTTP 402. + + Charge USDC per API request over HTTP — gasless for the buyer, settled on-chain via a hosted facilitator. + ## Builder Support From a7df046b3d92f9d8e3fe9a75042cbd29d1c883ba Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Wed, 15 Jul 2026 20:38:48 +0100 Subject: [PATCH 3/3] Cross-link MPP from the x402 and ERC-8004 Related sections Co-Authored-By: Claude Opus 4.8 --- build-on-celo/build-with-ai/8004.mdx | 1 + build-on-celo/build-with-ai/x402.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/build-on-celo/build-with-ai/8004.mdx b/build-on-celo/build-with-ai/8004.mdx index f8d7359bc..30775abf4 100644 --- a/build-on-celo/build-with-ai/8004.mdx +++ b/build-on-celo/build-with-ai/8004.mdx @@ -273,5 +273,6 @@ ERC-8004 works seamlessly with Celo's ecosystem: ## Related Protocols - [x402](/build-on-celo/build-with-ai/x402) - Payment layer for AI agents +- [MPP](/build-on-celo/build-with-ai/mpp) - Machine Payments Protocol: charge USDC per request over HTTP - [Celopedia](/build-on-celo/build-with-ai/celopedia) - Celo ecosystem knowledge for coding assistants - [MCP Servers](/build-on-celo/build-with-ai/mcp/index) - Connect agents to data and tools diff --git a/build-on-celo/build-with-ai/x402.mdx b/build-on-celo/build-with-ai/x402.mdx index 41d870bec..dd0312b05 100644 --- a/build-on-celo/build-with-ai/x402.mdx +++ b/build-on-celo/build-with-ai/x402.mdx @@ -394,6 +394,7 @@ app.get("/articles/:id", async (req, res) => { ## Related - [ERC-8004](/build-on-celo/build-with-ai/8004) - Trust layer for AI agents +- [MPP](/build-on-celo/build-with-ai/mpp) - Machine Payments Protocol: charge USDC per request over HTTP - [Celopedia](/build-on-celo/build-with-ai/celopedia) - Celo ecosystem knowledge for coding assistants - [Fee Abstraction](/build-on-celo/fee-abstraction/overview) - Pay gas with stablecoins on Celo - [Attribution Tags](/build-on-celo/attribution-tags) - Credit on-chain activity back to your app