x402-shop

# AgentPay — [agentpay.help](https://agentpay.help)

> **Machine-payable AI microservices via the [402 Payment Required](https://x402.org) 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](https://x402.org) — 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](#quick-start)
- [Architecture](#architecture)
- [Services & Pricing](#services--pricing)
- [MCP Server](#mcp-server)
- [Tech Stack](#tech-stack)
- [Deployment](#deployment)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)

---

## Quick Start

### Prerequisites

- **Node.js** ≥ 20
- **Ollama** running locally with the required model pulled
- A **wallet private key** (for receiving payments)

### 1. Clone & install

```bash
git clone https://github.com/your-org/AgentPay.git
cd AgentPay
npm install
```

### 2. Pull the AI model

```bash
ollama pull gemma3:1b
# Or use a larger model for better quality:
# ollama pull gemma4:31b-cloud
```

### 3. Configure

```bash
cp .env.example .env
# Edit .env — set SELLER_ADDRESS to your wallet address
```

### 4. Start the server

```bash
npm start
# AgentPay listening on :4021
#   payTo:   0xYourWalletAddress
#   network: eip155:84532 (Base Sepolia testnet)
#   facilitator: https://x402.org/facilitator
```

### 5. Test a paid request

```bash
# 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)

```bash
# 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:**

1. Client sends `POST /v1/summarize` (or any paid endpoint) — no auth headers needed
2. Payment middleware intercepts, returns **HTTP 402** with pricing info (`accepts[]`)
3. Client constructs a USDC payment, signs it, attaches `X-PAYMENT` header
4. Facilitator verifies the payment on Base mainnet
5. Middleware grants access → request proceeds to the service handler
6. Handler calls Ollama, returns AI-generated result as JSON

---

## Services & Pricing

| Endpoint | Price | Description |
|----------|-------|-------------|
| `POST /v1/summarize` | **$0.01** | AI text summarization — crisp 250-word summary of any text up to 20k chars |
| `POST /v1/classify-insurance` | **$0.02** | Insurance lead classifier — intent, urgency, line of business, confidence |
| `POST /v1/sentiment` | **$0.02** | Sentiment analysis — positive/negative/neutral with emotions and keywords |
| `POST /v1/extract` | **$0.03** | Structured field extraction — key-value pairs from emails, forms, documents |
| `POST /v1/translate` | **$0.03** | Text translation — translate to any language |
| `POST /v1/code-review` | **$0.05** | AI code review — bugs, security, performance, quality score |
| `POST /v1/insurance-analysis` | **$0.10** | Full insurance analysis bundle — classification + field extraction + summary in one call |
| `POST /v1/token-safety` | **$0.02** | Token safety check - rug pull risk, honeypot detection, liquidity analysis |
| `POST /v1/wallet-risk` | **$0.02** | Wallet risk screening - OFAC sanctions, scam flags, tx patterns |
| `POST /v1/web-scrape` | **$0.01** | Extract clean text from any URL - agents read web pages |
| `POST /v1/crypto-price` | **$0.005** | Real-time crypto prices - BTC, ETH, SOL + more |
| `POST /v1/image-describe` | **$0.03** | Vision AI - describe any image from URL |
| `POST /v1/defi-yields` | **$0.01** | DeFi yield data - APY, TVL, protocol info |
| `POST /v1/threat-intel` | **$0.02** | CVE/threat intelligence - vulnerability lookup, severity |
| `POST /v1/sanctions-screen` | **$0.02** | OFAC/EU sanctions screening - entity check |
| `POST /v1/market-intel` | **$0.02** | Macro/economic snapshot - GDP, inflation, rates |
| `POST /v1/on-chain-events` | **$0.01** | Decoded on-chain events - recent transfers |
| `POST /v1/content-safety` | **$0.02** | Content security scan - PII, toxicity, bias |
| `POST /v1/agent-reputation` | **$0.01** | Agent reputation score - endpoint trustworthiness |
| `POST /v1/legal-lookup` | **$0.03** | Legal/regulatory lookup - company registration |
| `POST /v1/news-feed` | **$0.005** | Real-time news feed - headlines by topic |
| `POST /v1/weather-data` | **$0.005** | Weather data - current conditions and forecast |
| `POST /v1/web-search` | **$0.01** | Web search - top results for any query with title, url, snippet |
| `POST /v1/memory` | **$0.005** | Persistent key-value memory scoped to your wallet - agents remember across runs |
| `POST /v1/geocode` | **$0.005** | Geocode place names to lat/lon; reverse geocode coordinates to addresses |
| `POST /v1/eth-gas` | **$0.003** | Ethereum gas prices - rapid/fast/standard/slow in gwei plus ETH spot price |
| `POST /v1/prediction-market` | **$0.01** | Polymarket prediction market odds - live probabilities for any topic |
| `POST /v1/deep-research` | **$0.25** | PREMIUM deep research - multi-source web research into a cited markdown report |

All services accept USDC on **Base mainnet** (chain ID `8453`) via the `exact` payment scheme. Testnet (Base Sepolia) is available via configuration.

---

## MCP Server

AgentPay ships **two** Model Context Protocol servers so any MCP-capable client (Claude Desktop, Cursor, Windsurf, VS Code, Smithery hosts, …) can call the paid endpoints directly.

### 1. Remote (Streamable HTTP) — no install, no API keys

The live server