Agentic Economy Boilerplate

The Rosetta Stone for Agentic Payments - One vending machine, multiple protocol implementations + production utilities

Get from zero to working agentic payments in 5 minutes with our battle-tested boilerplate examples.

🎯 Quick Start

🔥 The 5-Minute Challenge

Pick any protocol and get a working payment agent running:

# Clone this repository
git clone https://github.com/xpaysh/agentic-economy-boilerplate
cd agentic-economy-boilerplate

# Choose your adventure:
cd x402-vending-machine && npm install && npm start          # Crypto micropayments ✅
cd ap2-vending-machine && npm install && npm start           # Enterprise authorization ✅
cd acp-vending-machine && npm install && npm start           # Consumer checkout ✅
cd mastercard-vending-machine && npm install && npm start    # TradFi integration ✅

# Your vending machine is now live! 🎉

🐳 Or Use Docker

# Start all vending machines + Redis with one command
docker-compose up

# Or start individual services
docker-compose up x402-vending
docker-compose up mastercard-vending

# For development (just Redis + Redis Commander)
docker-compose -f docker-compose.dev.yml up

✨ What's New

🎁 Production-Ready Shared Utilities

All vending machines now have access to enterprise-grade utilities:

• 📦 Storage Layer: Redis with automatic in-memory fallback
• 🛡️ Security Suite: Rate limiting, agent detection, input sanitization
• 🧪 Testing Framework: Mock agents, payment helpers, comprehensive fixtures
• 🐳 Docker Infrastructure: Production & development compose files
• 📊 Middleware: Logging, error handling, CORS, Helmet

See shared/ for complete documentation on all utilities.

🏗️ What You'll Build

Each example implements the same Digital Vending Machine that:

• ✅ Accepts payments via different protocols
• ✅ Dispenses digital products (JSON responses)
• ✅ Handles errors gracefully
• ✅ Includes security best practices
• ✅ Provides detailed logging
• ✅ NEW: Uses production-ready shared utilities

The Power: Compare protocols side-by-side with identical functionality.

📦 Available Implementations

✅ x402 Vending Machine

Protocol: Coinbase x402 Best For: Crypto micropayments, AI agent APIs Features: HTTP 402 status code, instant settlement, zero fees Status: ✅ Production Ready (with shared utilities)

cd x402-vending-machine
curl http://localhost:3000/inventory
curl http://localhost:3000/buy/classic-cola
# Returns: 402 Payment Required with x402 headers

Full Documentation

✅ AP2 Vending Machine

Protocol: Google Agent Payments Protocol (AP2) Best For: Enterprise workflows, auditable payments Features: Verifiable credentials, mandate-based authorization, audit trails Status: ✅ Working (can be upgraded with shared utilities)

cd ap2-vending-machine
npm start
# Accepts AP2 credentials and multi-rail payments

Full Documentation

✅ ACP Vending Machine

Protocol: OpenAI Agentic Commerce Protocol (ACP) Best For: Consumer AI commerce, chat interfaces Features: Stripe integration, fraud prevention, AI agent detection Status: ✅ Working (can be upgraded with shared utilities)

cd acp-vending-machine
npm start
# Provides ChatGPT-style checkout experience

Full Documentation

✅ Mastercard Vending Machine

Protocol: Mastercard Agent Pay Best For: Traditional finance integration, global card payments Features: Card processing (Visa/MC/Amex), agent authorization, webhooks Status: ✅ Production Ready (with shared utilities)

cd mastercard-vending-machine
npm install && npm start
# Processes card payments for AI agents

Key Features:

• Traditional card payment processing (Visa, Mastercard, Amex, Discover)
• Payment sessions with 15-minute expiry
• Agent authorization whitelist
• Webhook support for real-time notifications
• Mock mode for development
• Full Mastercard API integration

Full Documentation

🚧 Coming Soon

Pay3 Vending Machine

Protocol: Pay3 Stablecoin Protocol Best For: DeFi integration, cross-chain payments Status: 📋 Planned

Hybrid Examples

Multi-Protocol Smart Agents Status: 📋 Planned

See how advanced agents switch between protocols:

• amount < $1 → x402 (micropayments)
• enterprise + audit_required → AP2 (compliance)
• chat_context + consumer → ACP (UX)
• cross_border + cards → Mastercard (global reach)

🛠️ Project Structure

agentic-economy-boilerplate/
├── shared/                            # 🎁 NEW: Production-ready utilities
│   ├── storage/                       #   Redis + in-memory storage
│   ├── middleware/                    #   Rate limiting, agent detection, security
│   ├── testing/                       #   Mock agents, fixtures, test helpers
│   └── docker/                        #   Dockerfile templates
├── x402-vending-machine/              # ✅ HTTP 402 crypto payments
├── ap2-vending-machine/               # ✅ Google AP2 enterprise
├── acp-vending-machine/               # ✅ OpenAI + Stripe consumer
├── mastercard-vending-machine/        # ✅ Mastercard TradFi
├── visa-tap-vending-machine/          # 📋 Visa Trusted Agent Protocol (planned)
├── ack-vending-machine/               # 📋 Agent Commerce Kit (planned)
├── aep2-vending-machine/              # 📋 Agent Embedded Payment Protocol (planned)
├── a2a-x402-vending-machine/          # 📋 Google A2A + x402 hybrid (planned)
├── hybrid-examples/                   # 📋 Multi-protocol examples (deferred)
├── docker-compose.yml                 # 🐳 Production deployment
├── docker-compose.dev.yml             # 🐳 Development environment
└── .env.example                       # 📝 Environment template

🔧 Setup Requirements

Prerequisites

• Node.js 18+ (all examples)
• Docker (optional, for containerized deployment)
• Git (for cloning)
• Redis (optional, for production storage - Docker Compose includes it)

Protocol-Specific Requirements

Protocol	Additional Requirements
x402	Crypto wallet (Base/Ethereum)
AP2	Google Cloud account, enterprise credentials
ACP	OpenAI API key, Stripe account
Mastercard	Mastercard developer account (or use mock mode)

Environment Setup

Copy and configure the environment template:

# Root level (shared config)
cp .env.example .env

# Protocol-specific
cd x402-vending-machine && cp .env.example .env
cd mastercard-vending-machine && cp .env.example .env
# Edit .env files with your configuration

📚 Documentation

Getting Started

• Docker Quickstart - Get running with Docker in 2 minutes
• Testing Guide - How to test vending machines and agents
• Production Deployment - Deploy to production safely

Shared Utilities

• Storage Layer - Redis + in-memory storage
• Middleware Suite - Rate limiting, security, logging
• Testing Utilities - Mock agents & test helpers

Protocol Examples

• x402 README - Crypto micropayments
• AP2 README - Enterprise authorization
• ACP README - Consumer checkout
• Mastercard README - Card payments

Planned Protocols

• Visa TAP - Visa Trusted Agent Protocol
• ACK - Agent Commerce Kit
• AEP2 - Agent Embedded Payment Protocol
• A2A + x402 - Google A2A with x402 payments

🎯 Real-World Use Cases

x402 Examples

• AI API Monetization: Charge per API call with crypto
• Data Streaming: Real-time feeds with micropayments
• Content Access: Paywall without subscriptions

AP2 Examples

• Enterprise Procurement: Automated B2B purchasing
• Compliance Workflows: Auditable agent transactions
• Multi-Party Payments: Complex payment flows

ACP Examples

• Conversational Commerce: Shop within ChatGPT
• AI Shopping Assistants: Automated purchase agents
• Consumer Marketplaces: AI-driven product discovery

Mastercard Examples

• Traditional Integration: Work with existing card infrastructure
• Global Payments: Accept payments worldwide
• Enterprise Agents: Corporate card processing for AI agents
• Hybrid Systems: Bridge crypto and traditional finance

🔐 Security Features

Every example includes:

• ✅ Input validation and sanitization (via shared middleware)
• ✅ Rate limiting to prevent abuse (configurable per agent type)
• ✅ Agent detection with trust classification
• ✅ Audit logging for all transactions
• ✅ Error handling with proper status codes
• ✅ Environment variable protection
• ✅ Helmet security headers and CORS configuration
• ✅ API key authentication (optional)
• ✅ Signature verification (optional)

Security Checklist

• Environment variables configured
• Rate limits set appropriately
• Audit logging enabled
• HTTPS enforced in production
• Input validation active
• Agent detection configured
• Redis password set (if using Redis)
• Error handling tested

🧪 Testing

Using Shared Testing Utilities

const { MockAgentClient, fixtures, paymentHelpers } = require('./shared/testing');

// Create a mock AI agent
const agent = new MockAgentClient('openai');

// Use test fixtures
const product = fixtures.products.coffee;

// Test payment flow
const result = await paymentHelpers.testPaymentFlow({
  protocol: 'x402',
  amount: product.price,
  productId: product.id
});

Run Tests

# Install shared utilities first
cd shared && npm install && cd ..

# Run vending machine tests
cd x402-vending-machine
npm test

# Run with coverage
npm run test:coverage

See Testing Guide for comprehensive testing documentation.

🚀 Deployment

Local Development

# Start individual vending machine
cd x402-vending-machine
npm run dev

# Or use Docker for full stack
docker-compose -f docker-compose.dev.yml up

Production with Docker

# Start all services (Redis + all vending machines)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Environment Variables

# Storage Configuration
USE_REDIS=true
REDIS_URL=redis://localhost:6379

# Security
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

# Logging
LOG_LEVEL=info
NODE_ENV=production

See Production Deployment Guide for complete instructions.

📊 Monitoring & Analytics

Built-in Analytics

Each vending machine includes:

• Transaction volume and success rates
• Response times and error rates
• Agent detection statistics
• Storage backend status (Redis vs in-memory)

Access Analytics

# x402
curl http://localhost:3000/analytics

# Mastercard
curl http://localhost:3003/api/analytics

Integration Options

• Datadog: APM and infrastructure monitoring
• New Relic: Application performance monitoring
• Prometheus: Metrics collection with shared middleware
• Winston: File and console logging (built-in)

🤝 Contributing

We welcome contributions! Here's how to help:

Add New Protocol Examples

1. Fork the repository
2. Use shared/ utilities for consistency
3. Create new directory: {protocol}-vending-machine/
4. Follow the structure of existing examples
5. Add comprehensive README, Dockerfile, and .env.example
6. Submit pull request

Improve Shared Utilities

• Add new middleware (caching, compression, etc.)
• Enhance testing framework
• Improve storage adapters
• Add more mock agent behaviors

Improve Existing Examples

• Integrate shared utilities into AP2 and ACP
• Add real blockchain verification (x402)
• Enhance security implementations
• Optimize performance

Contribution Guidelines

• Follow existing code style
• Use shared utilities when possible
• Add tests for new functionality
• Update documentation
• Include security considerations

🔗 Related Resources

Documentation

• Docker Quickstart
• Testing Guide
• Production Deployment
• Shared Utilities Documentation

External Resources

• Awesome Agentic Economy - Complete protocol guide
• Coinbase x402 Spec
• Google AP2 Documentation
• OpenAI ACP Spec
• Mastercard Developer Portal

📈 Roadmap

Current (v1.0)

• ✅ 4 working protocol implementations
• ✅ Production-ready shared utilities
• ✅ Docker deployment infrastructure
• ✅ Comprehensive testing framework

Coming Soon (v1.1)

• 📋 Pay3 stablecoin implementation
• 📋 Hybrid multi-protocol examples
• 📋 Real blockchain verification (x402)
• 📋 Complete AP2/ACP shared utility integration

Future (v2.0)

• 📋 Agent-to-agent payment coordination
• 📋 Cross-protocol arbitrage examples
• 📋 Advanced monitoring dashboards
• 📋 Production deployment templates (K8s, Terraform)

📄 License

MIT License - feel free to use these examples in your projects!

---

🚀 Ready to build the future of autonomous payments?

1. Quick Start: docker-compose up - Get all vending machines running
2. Learn: Browse protocol READMEs
3. Build: Use shared utilities for production features
4. Deploy: Follow the production guide

Having issues? Check our Docker Quickstart or Testing Guide for help.