Cerberus: On-Chain Payment Firewall for AI Agents

Cerberus is a three-layer payment firewall for AI agents. Before funds move, we verify identity via MCP, screen recipients, and enforce spending policy on-chain—where rules cannot be bypassed.

Comment

Inspiration

Agent wallets and payment rails are arriving fast. Watching Cloudflare’s agent-wallet direction and tracing a typical “agent pays for me” flow, one gap stood out: autonomy without a clear safety gate.

If an agent can move funds, three questions must be answered every time—not only once at setup:

  1. Identity — Who are you?
  2. Risk control — Who are you paying, and is this behavior normal?
  3. Execution — Is this authorized, and is there a verifiable record?

Cerberus is not trying to replace agent wallets or payment protocols. It is a payment firewall that sits in front of them—so agents stay autonomous, while users keep control that cannot be quietly bypassed.

What it does

Cerberus evaluates every agent payment request through three sequential gates:

1 · Identity — Who is paying?
Registered agent + Challenge-Response (blocks forged agent IDs).

2 · Risk — Is this request shady?
Off-chain blacklist, per-tx amount limits, frequency checks, and prompt-injection heuristics.

3 · Execution — Does on-chain Policy allow it?
Budget sandbox + Policy.validate (whitelist + maxPerTx) before settlement.

Product shape (all three, not pick-one):

  1. MCP servers — tools real agents can call (mcp-identity, mcp-payment-guard, mcp-execution)
  2. Smart contracts — Policy, PaymentGateway, AgentRegistry, MockUSDC
  3. Demo web — localhost demo with five scenarios + MetaMask approve + pay

Soft vs hard defense

Blacklist lives off-chain (fast MCP screen; demo seeds one known scam address). Whitelist lives on-chain (owner-authorized merchants only; agents cannot add payees). Configuring the whitelist is a policy transaction; PaymentGateway.pay is a separate settlement transaction signed in the user’s wallet.

Demo scenarios

  1. Stop forged agents (Layer 1)
  2. Stop scam / prompt injection (Layer 2)
  3. Stop non-whitelisted payees (Layer 3 on-chain Policy)
  4. Allow a clean payment (all layers pass → optional MetaMask pay)
  5. Stop over-limit amount (editable per-tx limit)

Pitch line: MCP lets the agent check smartly; on-chain Policy makes rules unbypassable; events are independently verifiable.

How we built it

Monorepo

packages/core — shared three-layer firewall (evaluate / evaluateAsync) + viem chain client packages/mcp-* — three MCP servers over stdio (Zod-validated tools) packages/contracts — Hardhat + Solidity 0.8.24 (Policy, PaymentGateway, AgentRegistry, MockUSDC) apps/demo — Next.js App Router, REST APIs, wagmi/viem wallet UI

Read path vs write path

Read (no gas): Demo backend calls Policy.validateWithReason(to, amount) via viem readContract inside Layer 3. Write (gas + signature): After approval, the browser uses wagmi to MockUSDC.approve then PaymentGateway.pay. The gateway re-checks Policy on-chain and emits PaymentAttempt / PaymentExecuted.

Agent identity in the demo

We do not spin up a live LLM agent in the web UI. The demo uses a registered identity agent-shopping-001 (Shopping Agent) and HTTP calls that exercise the same firewall a real agent would hit through MCP.

agentId hashing

Deploy uses ethers.id(...); the app uses keccak256(stringToBytes(...))—same Keccak-256 of UTF-8 bytes.

Networks

Local Hardhat (31337) for fast iteration Base Sepolia (84532) for public-testnet demos and BaseScan events

Challenges we ran into

  1. Simulated vs real chain without two products — Layer 3 needs both a sync path for MCP stdio and an async RPC path for the demo. We kept one Policy mental model and dual verifyExecution / verifyExecutionAsync implementations.
  2. Soft blacklist vs hard whitelist — Putting everything on-chain would be slow and inflexible; putting everything off-chain would be bypassable. We split: MCP risk feed for speed, on-chain allow-list for money.
  3. Demo clarity — Judges must see which gate fired. We shaped five capability scenarios around the layers (not random buttons) and exposed editable per-tx limits so “over limit” is interactive.
  4. Wallet UX on a local chain — MetaMask needs Localhost 8545, the correct chainId, and a funded Hardhat account with minted mUSDC. Deploy scripts write .env.local and mint to Account #0 to reduce setup friction.
  5. Hash consistency — agentId must match across Solidity, Hardhat, and the frontend; we standardized on Keccak-256 of the UTF-8 string and verified it end-to-end.

Accomplishments that we're proud of

An end-to-end three-gate story that is runnable in minutes (simulated) and switchable to real on-chain Policy reads + gateway pays. MCP + contracts + demo shipped as one coherent product narrative for Track 2 (Web3 + AI Agent + real scenario). Five demo scenarios that map 1:1 to defenses judges can click and explain. smoke-pay plus API checks validating whitelist allow/deny, amount limits, and hash alignment. Clear separation of policy configuration (whitelist) vs settlement (wallet pay)—easy to defend in a pitch.

What we learned

Agent payments need defense in depth: clever off-chain checks are not enough if settlement has no hard floor. Allow-lists beat deny-lists for funds: blacklist is a soft filter; whitelist is the unskippable rule. MCP is a natural interface for agents to query risk tooling without giving them permission to rewrite policy. Hackathon demos win when each click proves one claim—identity, risk, on-chain policy, success, amount limit. Local Hardhat + MetaMask is powerful but brittle; automating env + minting in deploy scripts is essential.

What's next for Cerberus: On-Chain Payment Firewall for AI Agents

Wire Layer 1 to on-chain AgentRegistry.isRegistered (helper already exists in core). Owner UX to manage whitelist / maxPerTx from the demo wallet (user-authorized merchants). Plug a real agent runtime into the MCP servers (agent → MCP → firewall → wallet). Production-grade challenge signatures and a replaceable threat-intel blacklist backend. Hardhat unit tests + light e2e; optional Base Sepolia public demo link for judges. Explore standards alignment (e.g. agent identity registries) via adapters—not a rewrite of the three gates.

Built With

Share this project:

Updates

Submission history