x402 Facilitator Proxy MCP server

X402 Facilitator Proxy - Multi-Tenant Payment Gateway

A decentralized, autonomous payment infrastructure for API monetization on Base L2 with programmatic fee routing and agent-compatible settlement protocols.

🏗️ Architecture Overview

The X402 Facilitator Proxy implements a complete multi-tenant payment gateway that enables merchants to monetize APIs through HTTP 402 "Payment Required" responses, while autonomous agents can seamlessly settle transactions using USDC on Base L2.

x402-facilitator-proxy/
├── src/                                    # Core Cloudflare Worker Engine
│   ├── index.ts                           # Main proxy gateway endpoint
│   └── backend/automation/
│       └── sweeper.ts                     # Automated fee collection
├── x402-client-sdk/                       # Core Interface Rails
│   ├── src/
│   │   ├── client-library.ts             # TypeScript SDK
│   │   └── mcp-server.ts                 # Model Context Protocol Server
│   ├── package.json                      # SDK dependencies
│   └── tsconfig.json                     # TypeScript configuration
└── templates/                             # Integration Templates
    ├── express-middleware/
    │   └── x402-guard.js                 # Merchant-Side API Gating
    ├── langchain-ts/
    │   ├── agent.ts                      # TypeScript Agent Template
    │   ├── package.json                  # LangChain dependencies
    │   └── README.md                     # Setup instructions
    └── crewai-python/
        └── agent.py                      # Python Agent Template

🚀 Core Components

1. Cloudflare Worker Proxy Engine

The core backend (src/index.ts) operates as a serverless payment verification gateway deployed on Cloudflare's edge network:

• Endpoint: https://x402-facilitator-proxy.seob5285.workers.dev/api/v1/verify-and-settle
• Platform Vault: 0x2E3DADfb314718849A93c49A78618E586c3b2C60
• Fee Structure: Automated 1% platform fee routing

Key Features:

• Multi-tenant transaction verification
• Base L2 USDC settlement validation
• Automated fee splitting (99% to merchant, 1% to platform)
• Edge-deployed for global low-latency access

2. Model Context Protocol (MCP) Server

The MCP server (x402-client-sdk/src/mcp-server.ts) provides a standardized interface for AI agents to interact with the payment system:

# Start the MCP server locally via stdio
npm run mcp:start

Protocol Features:

• Standard I/O communication interface
• Agent-compatible payment tool registration
• Automatic transaction handling and verification
• Cross-platform AI framework compatibility

3. Merchant-Side API Gating

The Express middleware (templates/express-middleware/x402-guard.js) enables merchants to protect APIs with HTTP 402 challenges:

import { x402TollboothGuard } from './templates/express-middleware/x402-guard.js';

app.use('/api/premium', x402TollboothGuard("0.10", "0xYourWalletAddress"));

Middleware Behavior:

1. Challenge: Returns HTTP 402 with payment instructions when headers are missing
2. Verification: Validates payment through the proxy gateway
3. Access: Grants API access upon successful payment verification

4. Autonomous Agent Templates

TypeScript/LangChain Agent (templates/langchain-ts/agent.ts)

import { createPaymentAgent } from './templates/langchain-ts/agent.js';

const agent = await createPaymentAgent();
const result = await agent.invoke({
  input: JSON.stringify({
    agentPrivateKey: process.env.AGENT_PRIVATE_KEY,
    developerWallet: "0x742d35Cc6297C24aE0E4838C4667C02693C4cB36",
    amountUSD: "0.10"
  })
});

Python/CrewAI Agent (templates/crewai-python/agent.py)

from templates.crewai_python.agent import X402PaymentAgent

Shortened. The full README is on GitHub.