xFour.xyz - x402 Payments using MNEE

Inspiration

AI agents are becoming autonomous economic actors, but they lack the infrastructure to transact. When an AI agent needs to pay for an API, fetch data, or access compute resources, it hits a wall—traditional payment systems require human intervention for every transaction.

We asked ourselves: What if AI agents could pay for services as seamlessly as they make HTTP requests?

The x402 HTTP status code ("Payment Required") has existed since 1997 but was never widely implemented. We saw an opportunity to bring it to life for the agentic era—creating a standard protocol where agents can autonomously handle payments using MNEE stablecoin on Ethereum.

What it does

xFour is a programmable payment gateway that enables AI agents to transact autonomously using MNEE stablecoin (ERC20) on Ethereum. It implements the x402 protocol, turning the dormant HTTP 402 status code into a practical payment flow.

For AI Agents (consumers):

Drop-in SDK (@x402/agent) that wraps fetch and automatically handles payment flows
When an API returns 402, the SDK gets a quote, executes payment via MNEE, and retries with proof
Budget controls, daily/monthly limits, and allowed provider lists

For API Providers (merchants):

Server SDK (@x402/server) with middleware for Express, Next.js, and other frameworks
Set prices per-endpoint or dynamically based on request complexity
Receive payments directly to your Ethereum wallet

Dashboard features:

Workspace isolation for teams/organizations
API key management with secure hashed storage
Real-time payment activity and analytics
Treasury smart contracts with on-chain spending limits
Per-API-key spending policies enforced at the contract level

How we built it

Frontend: Next.js 15 with React and Tailwind CSS for a real-time dashboard experience.

Backend: Convex for real-time database operations, business logic, and instant subscription updates. The reactive nature of Convex means payment status updates appear instantly in the dashboard.

Smart Contracts (Solidity):

Treasury.sol: Non-custodial treasury contract per workspace. Holds MNEE tokens and enforces spending limits (per-transaction, daily, monthly) for each API key on-chain.
TreasuryFactory.sol: Factory contract that deploys new Treasury contracts for workspaces.
X402Gateway.sol: Central gateway contract that executes payments across all treasuries. Uses nonces to prevent replay attacks.
TestMNEE.sol: ERC20 test token deployed on Sepolia for development (mainnet MNEE at 0x8ccedbAe4916b79da7F3F612EfB2EB93A2bFD6cF).

Payment Flow:

Agent makes request → API returns 402 with x402 headers
SDK calls /quote to validate against spending policies (checks on-chain limits)
If approved, SDK calls /pay to execute MNEE transfer
Gateway calls X402Gateway.executePayment() → Treasury transfers ERC20 MNEE to recipient
Agent retries original request with proof header (transaction hash)

Security:

Non-custodial treasuries—workspaces deploy their own smart contracts
API key hashes stored on-chain (keccak256), spending limits enforced by contract
Role-based access: ADMIN_ROLE for workspace owners, GATEWAY_ROLE for the x402 gateway
ReentrancyGuard and Pausable patterns for contract safety
Clerk for authentication with workspace-level isolation

MNEE Integration (Ethereum ERC20):

Standard ERC20 interface with 18 decimals
SafeERC20 for secure token transfers
Testnet faucet built into TestMNEE contract (1000 tMNEE per hour)
Synchronous transaction confirmation on Ethereum

Challenges we ran into

On-Chain Spending Limits: Designing a contract architecture that enforces spending limits per API key while remaining gas-efficient. We implemented daily/monthly period resets that happen lazily on each transaction to avoid expensive cron-like patterns.

Non-Custodial Design: We wanted workspaces to truly own their funds. This led to the Treasury-per-workspace pattern where each organization deploys their own contract and the gateway only has permission to execute authorized payments.

Convex + EVM Integration: Convex httpActions can't make external blockchain calls directly with wallets. We built the payment execution logic in Next.js API routes that call the contracts via ethers.js/viem.

x402 Header Standardization: There's no official standard for x402 headers. We defined our own schema (X-402-Invoice-Id, X-402-Amount, X-402-Pay-To, X-402-Network) and documented it clearly.

Gas Optimization: Batch payment execution was critical for reducing costs when processing multiple payments. The batchExecutePayments() function can process many payments in a single transaction.

Accomplishments that we're proud of

Working SDK packages (@x402/agent and @x402/server) that make integration trivial
Production-ready smart contracts with comprehensive security patterns (AccessControl, ReentrancyGuard, Pausable)
On-chain spending limits that enforce policies without trusting the backend
Real-time dashboard with live payment activity streaming via Convex subscriptions
Complete payment flow from 402 response → quote → pay → retry, all automated
Non-custodial architecture—workspaces control their own treasury contracts
Clean developer experience—agents can start paying for APIs with 5 lines of code

What we learned

Ethereum ERC20 provides a robust, well-audited foundation for programmable payments with strong tooling (ethers.js, viem, OpenZeppelin)
On-chain policy enforcement is more powerful than off-chain—spending limits can't be bypassed even if the backend is compromised
HTTP 402 is a sleeping giant that becomes powerful when combined with stablecoins and AI agents
Real-time backends (Convex) transform the UX for payment dashboards—no polling, no stale data
Factory pattern in Solidity enables scalable multi-tenant architectures where each workspace has isolated funds
The agentic economy is real—AI systems increasingly need to autonomously acquire resources

What's next for xFour.xyz - x402 Payments using MNEE

Provider Marketplace: A registry where API providers can list x402-enabled endpoints and agents can discover paid services
Advanced Policies: Time-based limits, approval workflows, multi-sig treasury controls
Analytics & Insights: Cost optimization suggestions, usage patterns, spend forecasting
MCP Integration: Native support for Model Context Protocol so LLMs can discover and use paid tools
Streaming Payments: For long-running agent tasks, enable per-second or per-token billing using payment channels
L2 Deployment: Deploy on Base, Arbitrum, or other L2s for lower gas costs on high-frequency micropayments
Cross-Chain Support: Extend the architecture to support MNEE on multiple chains with bridge integration

Technological Implementation

Production-ready smart contracts with OpenZeppelin security patterns (AccessControl, ReentrancyGuard, Pausable)
On-chain spending limits enforced at the contract level—can't be bypassed even if the backend is compromised
Non-custodial treasury architecture where each workspace deploys their own contract
Working SDK packages (@x402/agent and @x402/server) for seamless integration
Gas-optimised batch payment execution for high-frequency micropayments

Design & User Experience

Real-time dashboard with live payment activity streaming—no polling, no stale data
Agents can start paying for APIs with just a few lines of code
Clean workspace isolation for teams and organisations
Intuitive API key management with configurable spending policies