celo-chain-intel

A paid MCP server: Celo chain-intelligence tools that other AI agents call and pay for per request, settled in stablecoins over x402 on Celo.

No API keys, no accounts, no subscriptions. An agent calls a tool, gets a 402 with the price, signs an EIP-3009 authorization, and retries. Funds move directly from buyer to seller; the facilitator pays the gas.

Why this shape

Two of the hackathon's four tracks are volume metrics (Most x402 Payments, Most Revenue Generated), so the tools are priced sub-cent to be called constantly rather than expensively. The customers are other agents — including other hackathon entries, which all need Celo data and none of which want to build RPC plumbing.

Tools

Tool	Price	What it does
celo_gas	$0.0002	Gas price, latest block, cost of an ERC20 transfer
celo_token_info	$0.0005	ERC20 name / symbol / decimals / supply
celo_balances	$0.001	CELO + USDC/USDT/cUSD/cEUR balances, flagging which are x402-settleable
celo_transaction	$0.001	Transaction summary by hash
x402_probe	$0.002	Given any URL, report whether it is x402-payable and on what terms — without paying

x402_probe is the one with no equivalent elsewhere. x402 has no discovery mechanism: the only way to learn an endpoint's price is to call it and read the 402. This does that safely and normalises the answer, including whether Celo's facilitator can actually settle those terms.

Quick start

npm install
cp .env.example .env
# set PAY_TO_ADDRESS to the Celo address that should receive payments
npm run dev

Then, free of charge:

curl localhost:3000/                    # service card: tools + prices
curl localhost:3000/health              # also checks the facilitator is live
curl -X POST localhost:3000/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Trigger a payment challenge:

curl -i "localhost:3000/v1/tools/celo_gas"   # -> 402 with the terms

Pay it end to end (needs a throwaway key holding a little USDC on Celo):

BUYER_PRIVATE_KEY=0x... npm run buyer -- celo_gas
BUYER_PRIVATE_KEY=0x... npm run buyer -- celo_balances '{"address":"0x..."}'

Scripts

Command	Purpose
npm run dev	Run the server with reload
npm run smoke	Exercise every tool against live Celo. Spends nothing
npm run verify-sig	Prove the EIP-3009 payload + EIP-712 domain are correct, using an unfunded key. Spends nothing
npm run buyer	Full buy: 402 → sign → retry → settle. Spends USDC
npm run typecheck	tsc --noEmit

How payment works here

agent → tools/call (no X-PAYMENT)
      ← 402 + accepts[] (scheme, network, asset, amount, payTo, EIP-712 domain)
  agent signs EIP-3009 TransferWithAuthorization
agent → tools/call with X-PAYMENT: base64(payload)
      → facilitator /verify   (off-chain: signature + balance simulation)
      → run the tool
      → facilitator /settle   (on-chain: facilitator submits, pays gas)
      ← result + X-PAYMENT-RESPONSE receipt

The tool runs before settlement, deliberately. A tool that throws never calls settle(), so a failing call costs the buyer nothing. If the tool succeeds but settlement fails, the result is withheld rather than given away — the response is a 402, not a silent freebie.

initialize, tools/list and ping are always free: a buyer has to be able to discover what exists and what it costs before paying for anything.

Findings that contradict the published docs

These were verified against the live facilitator on 2026-07-29 and each one would otherwise have silently broken the build.

1. The documented facilitator URL is wrong. docs.celo.org says https://x402.celo.org. That host serves the marketing SPA — it returns text/html for GET /supported and 405 for POST /verify. The JSON API is at https://api.x402.celo.org. src/x402/facilitator.ts detects a non-JSON response and says so explicitly, because the natural failure mode is an opaque JSON.parse error.

2. upto (dynamic/metered pricing) is not supported. Live /supported advertises only scheme: "exact". The docs' per-token metered-billing example cannot work against this facilitator today.

3. No testnet. /supported lists only eip155:42220 (v2) and celo (v1), despite the docs describing Celo Sepolia support. End-to-end settlement testing requires mainnet — which is why the sub-cent pricing and the two spend-nothing verification scripts exist.

4. x402-express@1.2.0 cannot target Celo at all. Its Network enum is abstract, base, base-sepolia, avalanche, avalanche-fuji, iotex, solana, solana-devnet, sei, sei-testnet, polygon, polygon-amoy, peaq, story, educhain, skale-base-sepolia — no celo, no eip155:42220. The docs' x402-express snippet fails Zod validation before any request is made. Same applies to the x402 client library, which is why scripts/buyer.ts signs with viem directly. This server implements the protocol against the facilitator's HTTP API instead.

5. The USDC address in the docs has an invalid EIP-55 checksum. 0xcEBA9300f2b948710d2653dD7B07f33A8B32118C — correct is 0xcebA9300f2b948710d2653dD7B07f33A8B32118C. getAddress() normalises it silently, so this only surfaces at a strict validation boundary.

6. cUSD cannot be used for x402 payments. Mento's StableTokenV2 implements only EIP-2612 permit, not the EIP-3009 transferWithAuthorization the facilitator settles with. Celo's flagship stablecoin is therefore unusable as an x402 asset; settlement uses USDC. celo_balances still reports cUSD but flags x402Settleable: false.

Also worth knowing: /verify answers with HTTP 400 and a well-formed verdict body when a payment is bad. Treating non-2xx as a transport error turns an underfunded buyer into a confusing 502; post() distinguishes a verdict from a real failure so the buyer gets a 402 naming the reason.

Verification status

Piece	Status
Free MCP discovery (initialize, tools/list, ping)	Verified
All five tools against live Celo mainnet	Verified via npm run smoke
402 challenge on both MCP and REST, with correct terms	Verified
EIP-3009 payload + EIP-712 domain accepted by the facilitator	Verified via npm run verify-sig — rejected only for insufficient_funds, meaning signature recovery and payload parsing both succeeded
Underfunded buyer receives a clean 402 naming the reason	Verified
On-chain settlement moving real funds	Not yet run — needs a funded key. This is the one path no test here covers.

Deployment note

PUBLIC_BASE_URL must match the URL buyers actually call. Payment requirements bind the signed authorization to the resource URL, so leaving it as localhost:3000 behind a tunnel or deploy will fail at settlement.

Listing copy

For the marketplace form:

celo-chain-intel — A paid MCP server giving AI agents instant Celo chain intelligence: balances, token metadata, gas, transaction lookups, and x402 endpoint discovery. No API keys and no signup — agents pay per call in stablecoins over x402, from $0.0002. Includes x402_probe, which tells an agent what any endpoint charges before it commits to paying.

Contact and logo still need to be supplied by you.