Machine-payable AI microservices via the 402 Payment Required protocol (x402 / MPP)
No accounts. No API keys. No OAuth. Pay per call in USDC on Base.
AgentPay is an open-source reference implementation of the Machine Payments Protocol β wrapping local AI models behind an HTTP 402 paywall so that AI agents (and humans) can pay for compute on a per-request basis using stablecoins.
Built with Express 5, @x402/express, and Ollama-served Gemma models. Live on Base mainnet with the PayAI facilitator.
Table of Contents
Quick Start
Prerequisites
- Node.js β₯ 20
- Ollama running locally with the required model pulled
- A wallet private key (for receiving payments)
1. Clone & install
git clone https://github.com/your-org/AgentPay.git
cd AgentPay
npm install
2. Pull the AI model
ollama pull gemma3:1b
# Or use a larger model for better quality:
# ollama pull gemma4:31b-cloud
3. Configure
cp .env.example .env
# Edit .env β set SELLER_ADDRESS to your wallet address
4. Start the server
npm start
# AgentPay listening on :4021
# payTo: 0xYourWalletAddress
# network: eip155:84532 (Base Sepolia testnet)
# facilitator: https://x402.org/facilitator
5. Test a paid request
# Unpaid request β HTTP 402 (paywall)
curl -s -o /dev/null -w "%{http_code}" -X POST https://agentpay.help/v1/summarize \
-H 'Content-Type: application/json' \
-d '{"text":"Machine Payments Protocol lets AI agents pay for API calls using the HTTP 402 status code."}'
# β 402
# Automated test (requires buyer wallet with USDC)
npm run test:402
6. Buy a service (buyer client)
# Set your buyer private key in .env
echo "BUYER_PK=0xYourPrivateKey" >> .env
# Run the buyer script
npm run buyer -- /v1/summarize ./payload.json
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AgentPay Architecture β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββ HTTP POST βββββββββββββββββββββββββββββ β
β β Client β βββββββββββββββΊ β Express 5 Server β β
β β (Agent / β (no auth) β (port 4021) β β
β β Human) β β β β
β ββββββββββββ β βββββββββββββββββββββββ β β
β β β β Payment Middleware β β β
β β β β (@x402/express) β β β
β β β β β β β
β β βββ HTTP 402 ββββββββ β β’ Validates x402 β β β
β β (paywall) β β payment headers β β β
β β β β β’ Verifies on-chain β β β
β β ββββ signed payment βΊβ β via facilitator β β β
β β (USDC) β β β β β
β β β ββββββββββββ¬βββββββββββ β β
β β βββ 200 OK ββββββββββ β β β
β β (result JSON) β ββββββββββββΌβββββββββββ β β
β β β β Service Handlers β β β
β β β β β β β
β β β β /v1/summarize β β β
β β β β /v1/classify-ins β β β
β β β β /v1/extract β β β
β β β ββββββββββββ¬βββββββββββ β β
β β βββββββββββββββΌββββββββββββββ β
β β β β
β β ββββββββΌβββββββ β
β β β Ollama β β
β β β (local LLM) β β
β β β gemma3:1b β β
β β βββββββββββββββ β
β β β
β ββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Payment Flow (x402) β β
β β β β
β β Client βββΊ HTTP 402 βββΊ Facilitator βββΊ On-Chain βββΊ β β
β β β (PayAI) Base Mainnet β β
β β βΌ (USDC) β β
β β Payment Required β β
β β (price + accepts[]) β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Free Endpoints (no paywall) β β
β β β’ / β Landing page (HTML) β β
β β β’ /health β Health check β β
β β β’ /stats β Revenue & usage stats β β
β β β’ /.well-known/x402 β Machine-readable service catalog β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Data Layer β β
β β β’ data/ledger.json β Append-only payment ledger β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
How it works:
- Client sends
POST /v1/summarize (or any paid endpoint) β no auth headers needed
- Payment middleware intercepts, returns HTTP 402 with pricing info (
accepts[])
- Client constructs a USDC payment, signs it, attaches
X-PAYMENT header
- Facilitator verifies the payment on Base mainnet
- Middleware grants access β request proceeds to the service handler
- Handler calls Ollama, returns AI-generated result as JSON
Services & Pricing
| Endpoint | Price | Description |
|---|
POST /v1/summarize | $0.01 | Summarize text (200β20,000 chars). Returns a ~250-word summary. |
POST /v1/classify-insurance | $0.02 | Classify insurance leads: intent, urgency, line-of-business, confidence score. |
POST /v1/sentiment | $0.02 | Sentiment analysis: positive/negative/neutral with emotions and keywords. |
POST /v1/extract | $0.03 | Extract structured key-value fields from raw text (emails, forms, documents). |
POST /v1/translate | $0.03 | Text translation to any language. |
POST /v1/code-review | $0.05 | AI code review: bugs, security issues, performance, quality analysis. |
POST /v1/insurance-analysis | $0.10 | β FULL BUNDLE β classification + extraction + summary in one call. |
All services accept USDC on Base mainnet (chain ID 8453) via the exact payment scheme. Testnet (Base Sepolia) is available via configuration.
Tech Stack
| Component | Technology |
|---|
| Runtime | Node.js β₯ 20 (ESM) |
| HTTP Server | Express 5.2 |
| Payment Protocol | @x402/express 2.22, @x402/evm, @x402/fetch, @x402/extensions |
| Blockchain | Base (OP Stack L2), USDC stablecoin |
| Facilitator | PayAI x402 facilitator (x402.org/facilitator) |
| AI Runtime | Ollama (local inference) |
| LLM | Gemma 3 1B (default) / Gemma 4 31B (recommended) |
| Wallet | viem (Ethereum client library) |
| Config | dotenv |
Deployment
Local Development
# Base Sepolia testnet (recommended for development)
cp .env.example .env
# Edit .env: PAYMENT_NETWORK=eip155:84532
npm start
Production (Base Mainnet)
# Edit .env for mainnet
PAYMENT_NETWORK=eip155:8453 # Base mainnet
SELLER_ADDRESS=0xYourMainnetWallet
OLLAMA_URL=http://127.0.0.1:11434
MODEL_SUMMARIZE=gemma4:31b-cloud # Use larger model for quality
MODEL_CLASSIFY=gemma4:31b-cloud
MODEL_EXTRACT=gemma4:31b-cloud
Docker (recommended for production)
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY src/ ./src/
COPY data/ ./data/
EXPOSE 4021
HEALTHCHECK CMD curl -f https://agentpay.help/health || exit 1
CMD ["node", "src/server.js"]
Environment Variables
| Variable | Required | Default | Description |
|---|
PORT | No | 4021 | Server port |
SELLER_ADDRESS | Yes | β | Wallet address to receive USDC payments |
PAYMENT_NETWORK | No | eip155:84532 | Blockchain network (eip155:8453 for mainnet) |
FACILITATOR_URL | No | https://x402.org/facilitator | x402 facilitator endpoint |
OLLAMA_URL | No | http://127.0.0.1:11434 | Ollama API base URL |
MODEL_SUMMARIZE | No | gemma3:1b | Model for summarize endpoint |
MODEL_CLASSIFY | No | gemma3:1b | Model for classify-insurance endpoint |
MODEL_EXTRACT | No | gemma3:1b | Model for extract endpoint |
PUBLIC_URL | No | β | Public URL for discovery metadata |
API Reference
Free Endpoints
GET /
Landing page with service catalog and usage stats.
GET /health
Health check.
{ "ok": true, "ts": "2025-01-01T00:00:00.000Z" }
GET /stats
Revenue and usage statistics.