{
  "markdown": "# X402 Facilitator Proxy - Multi-Tenant Payment Gateway\n\n**A decentralized, autonomous payment infrastructure for API monetization on Base L2 with programmatic fee routing and agent-compatible settlement protocols.**\n\n## 🏗️ Architecture Overview\n\nThe 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.\n\n```\nx402-facilitator-proxy/\n├── src/                                    # Core Cloudflare Worker Engine\n│   ├── index.ts                           # Main proxy gateway endpoint\n│   └── backend/automation/\n│       └── sweeper.ts                     # Automated fee collection\n├── x402-client-sdk/                       # Core Interface Rails\n│   ├── src/\n│   │   ├── client-library.ts             # TypeScript SDK\n│   │   └── mcp-server.ts                 # Model Context Protocol Server\n│   ├── package.json                      # SDK dependencies\n│   └── tsconfig.json                     # TypeScript configuration\n└── templates/                             # Integration Templates\n    ├── express-middleware/\n    │   └── x402-guard.js                 # Merchant-Side API Gating\n    ├── langchain-ts/\n    │   ├── agent.ts                      # TypeScript Agent Template\n    │   ├── package.json                  # LangChain dependencies\n    │   └── README.md                     # Setup instructions\n    └── crewai-python/\n        └── agent.py                      # Python Agent Template\n```\n\n## 🚀 Core Components\n\n### 1. Cloudflare Worker Proxy Engine\n\nThe core backend (`src/index.ts`) operates as a serverless payment verification gateway deployed on Cloudflare's edge network:\n\n- **Endpoint**: `https://x402-facilitator-proxy.seob5285.workers.dev/api/v1/verify-and-settle`\n- **Platform Vault**: `0x2E3DADfb314718849A93c49A78618E586c3b2C60`\n- **Fee Structure**: Automated 1% platform fee routing\n\n**Key Features:**\n- Multi-tenant transaction verification\n- Base L2 USDC settlement validation\n- Automated fee splitting (99% to merchant, 1% to platform)\n- Edge-deployed for global low-latency access\n\n### 2. Model Context Protocol (MCP) Server\n\nThe MCP server (`x402-client-sdk/src/mcp-server.ts`) provides a standardized interface for AI agents to interact with the payment system:\n\n```bash\n# Start the MCP server locally via stdio\nnpm run mcp:start\n```\n\n**Protocol Features:**\n- Standard I/O communication interface\n- Agent-compatible payment tool registration\n- Automatic transaction handling and verification\n- Cross-platform AI framework compatibility\n\n### 3. Merchant-Side API Gating\n\nThe Express middleware (`templates/express-middleware/x402-guard.js`) enables merchants to protect APIs with HTTP 402 challenges:\n\n```javascript\nimport { x402TollboothGuard } from './templates/express-middleware/x402-guard.js';\n\napp.use('/api/premium', x402TollboothGuard(\"0.10\", \"0xYourWalletAddress\"));\n```\n\n**Middleware Behavior:**\n1. **Challenge**: Returns HTTP 402 with payment instructions when headers are missing\n2. **Verification**: Validates payment through the proxy gateway\n3. **Access**: Grants API access upon successful payment verification\n\n### 4. Autonomous Agent Templates\n\n#### TypeScript/LangChain Agent (`templates/langchain-ts/agent.ts`)\n```typescript\nimport { createPaymentAgent } from './templates/langchain-ts/agent.js';\n\nconst agent = await createPaymentAgent();\nconst result = await agent.invoke({\n  input: JSON.stringify({\n    agentPrivateKey: process.env.AGENT_PRIVATE_KEY,\n    developerWallet: \"0x742d35Cc6297C24aE0E4838C4667C02693C4cB36\",\n    amountUSD: \"0.10\"\n  })\n});\n```\n\n#### Python/CrewAI Agent (`templates/crewai-python/agent.py`)\n```python\nfrom templates.crewai_python.agent import X402PaymentAgent\n\nagent = X402PaymentAgent()\nresult = agent.process_payment({\n    \"agent_private_key\": os.getenv(\"AGENT_PRIVATE_KEY\"),\n    \"developer_wallet\": \"0x742d35Cc6297C24aE0E4838C4667C02693C4cB36\",\n    \"amount_usd\": \"0.10\"\n})\n```\n\n## 🔧 Quick Start\n\n### 1. Deploy the Proxy Engine\n```bash\nnpm install\nnpm run deploy\n```\n\n### 2. Setup the MCP Server\n```bash\ncd x402-client-sdk\nnpm install\nnpm run mcp:start\n```\n\n### 3. Integrate Merchant Middleware\n```bash\n# Copy the Express middleware to your project\ncp templates/express-middleware/x402-guard.js your-project/middleware/\n\n# Install in your Express app\nimport { x402TollboothGuard } from './middleware/x402-guard.js';\napp.use('/api/protected', x402TollboothGuard(\"0.05\", \"0xYourWallet\"));\n```\n\n### 4. Setup Agent Templates\n```bash\n# For TypeScript/LangChain agents\ncd templates/langchain-ts\nnpm install\nnpm run dev\n\n# For Python/CrewAI agents\ncd templates/crewai-python\npip install -r requirements.txt\npython agent.py\n```\n\n## 🔐 Security & Environment Variables\n\n### **Critical Security Guidelines**\n\n**⚠️ NEVER HARDCODE PRIVATE KEYS IN REPOSITORY FILES**\n\nAll sensitive credentials must be managed through secure environment variables:\n\n### Cloudflare Worker Environment (Production)\n```bash\n# Set via Cloudflare Workers dashboard or wrangler\nwrangler secret put FACILITATOR_PRIVATE_KEY\nwrangler secret put PLATFORM_VAULT_ADDRESS\n```\n\n### Local Development Environment\nCreate `.env` files for local testing:\n\n```env\n# .env (root directory - for Cloudflare Worker development)\nFACILITATOR_PRIVATE_KEY=0x1234567890abcdef...\nPLATFORM_VAULT_ADDRESS=0x2E3DADfb314718849A93c49A78618E586c3b2C60\n\n# Agent execution environments\nAGENT_PRIVATE_KEY=0xabcdef1234567890...\nOPENAI_API_KEY=sk-...\n```\n\n### Agent Runtime Security\n- **TypeScript Agents**: Use `process.env.AGENT_PRIVATE_KEY`\n- **Python Agents**: Use `os.getenv(\"AGENT_PRIVATE_KEY\")`\n- **MCP Server**: Loads keys from system environment at runtime\n\n## 🌐 Platform Reference\n\n### Core Infrastructure\n- **Verification Gateway**: `https://x402-facilitator-proxy.seob5285.workers.dev/api/v1/verify-and-settle`\n- **Platform Vault**: `0x2E3DADfb314718849A93c49A78618E586c3b2C60`\n- **Network**: Base L2 (Chain ID: 8453)\n- **Payment Token**: USDC (`0x833589fCD6eDb6E08f4c7C32d4f71b54bda02913`)\n\n### Fee Structure\n- **Merchant Revenue**: 99% of payment amount\n- **Platform Fee**: 1% automatically routed to platform vault\n- **Gas Optimization**: Batched transfers for cost efficiency\n\n## 📖 Integration Patterns\n\n### HTTP 402 Payment Flow\n\n1. **API Request**: Client attempts to access protected endpoint\n2. **Payment Challenge**: Server responds with HTTP 402 and payment instructions\n3. **Agent Processing**: Autonomous agent detects 402, executes USDC payment split\n4. **Verification**: Proxy gateway validates on-chain transaction\n5. **Access Granted**: Original API request succeeds with payment headers\n\n### Agent Integration Workflow\n\n```mermaid\ngraph TD\n    A[Agent API Call] --> B{HTTP 402?}\n    B -->|Yes| C[Parse Payment Requirements]\n    C --> D[Execute USDC Split Transfer]\n    D --> E[Submit to Proxy Gateway]\n    E --> F[Retry Original Request]\n    F --> G[Access Granted]\n    B -->|No| G\n```\n\n## 🛠️ Development Commands\n\n```bash\n# Core proxy development\nnpm run dev              # Start local development server\nnpm run deploy           # Deploy to Cloudflare Workers\nnpm run cf-typegen       # Generate Cloudflare types\n\n# SDK development\ncd x402-client-sdk\nnpm run build           # Build TypeScript SDK\nnpm run mcp:start       # Start MCP server\n\n# Template testing\ncd templates/langchain-ts\nnpm run dev            # Test TypeScript agent\n\ncd templates/crewai-python\npython agent.py        # Test Python agent\n\n# Automated fee collection\nnpm run sweep          # Execute fee sweeping automation\n```\n\n## 📚 Documentation\n\n- **[Client Integration Guide](CLIENT_INTEGRATION.md)**: Detailed integration instructions\n- **[LangChain Template README](templates/langchain-ts/README.md)**: TypeScript agent setup\n- **[API Reference](src/index.ts)**: Core gateway endpoints and responses\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branches for new integrations\n3. Test against Base L2 testnet before mainnet deployment\n4. Submit pull requests with comprehensive test coverage\n\n## 📄 License\n\nThis project is licensed under the MIT License - enabling open-source innovation while maintaining platform sustainability through programmatic fee routing.\n\n---\n\n**Built for the autonomous economy. Powered by Base L2. Secured by multi-tenant verification.**",
  "bytes": 8391,
  "sha": "99ee0c83dc5d1f42e3a871ab02d6434159c5bad004aeff8f2ed6197aadf8d756",
  "repo_slug": "seob5285-alt/x402-facilitator-proxy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_seob5285_alt_x402_facilitator__fa06f2de/readme"
}