AgentPay

Microservicios de IA de pago por llamada mediante el protocolo x402. 22 servicios: resumen de texto, traducción, revisión de código, análisis de sentimiento, análisis de seguros, seguridad cripto, rendimientos DeFi, inteligencia de amenazas. USDC en Base.

GitHubPrueba este MCPPatrocinado

Documentación

AgentPay — agentpay.help

Microservicios de IA pagables por máquina mediante el protocolo 402 Payment Required (x402 / MPP)

Sin cuentas. Sin claves API. Sin OAuth. Paga por llamada en USDC en Base.

AgentPay es una implementación de referencia de código abierto del Machine Payments Protocol — que envuelve modelos de IA locales detrás de un muro de pago HTTP 402 para que los agentes de IA (y los humanos) puedan pagar por cómputo por solicitud usando stablecoins.

Construido con Express 5, @x402/express y modelos Gemma servidos por Ollama. En vivo en la red principal de Base con el facilitador PayAI.

Inicio Rápido

Requisitos Previos

Node.js ≥ 20
Ollama ejecutándose localmente con el modelo requerido descargado
Una clave privada de wallet (para recibir pagos)

1. Clonar e instalar

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

2. Descargar el modelo de IA

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

3. Configurar

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

4. Iniciar el servidor

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

5. Probar una solicitud de pago

# 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. Comprar un servicio (cliente comprador)

# Set your buyer private key in .env
echo "BUYER_PK=0xYourPrivateKey" >> .env

# Run the buyer script
npm run buyer -- /v1/summarize ./payload.json

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                        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        │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Cómo funciona:

El cliente envía POST /v1/summarize (o cualquier endpoint de pago) — sin necesidad de cabeceras de autenticación
El middleware de pago intercepta y devuelve HTTP 402 con información de precios (accepts[])
El cliente construye un pago USDC, lo firma y adjunta la cabecera X-PAYMENT
El facilitador verifica el pago en la red principal de Base
El middleware concede acceso → la solicitud procede al manejador del servicio
El manejador llama a Ollama y devuelve el resultado generado por IA como JSON

Servicios y Precios

Endpoint	Precio	Descripción
`POST /v1/summarize`	$0.01	Resumir texto (200–20,000 caracteres). Devuelve un resumen de ~250 palabras.
`POST /v1/classify-insurance`	$0.02	Clasificar leads de seguros: intención, urgencia, línea de negocio, puntuación de confianza.
`POST /v1/sentiment`	$0.02	Análisis de sentimiento: positivo/negativo/neutral con emociones y palabras clave.
`POST /v1/extract`	$0.03	Extraer campos estructurados clave-valor de texto sin formato (correos, formularios, documentos).
`POST /v1/translate`	$0.03	Traducción de texto a cualquier idioma.
`POST /v1/code-review`	$0.05	Revisión de código con IA: errores, problemas de seguridad, rendimiento, análisis de calidad.
`POST /v1/insurance-analysis`	$0.10	⭐ PAQUETE COMPLETO — clasificación + extracción + resumen en una sola llamada.

Todos los servicios aceptan USDC en la red principal de Base (ID de cadena 8453) mediante el esquema de pago exact. La red de prueba (Base Sepolia) está disponible mediante configuración.

Stack Tecnológico

Componente	Tecnología
Runtime	Node.js ≥ 20 (ESM)
Servidor HTTP	Express 5.2
Protocolo de Pago	`@x402/express` 2.22, `@x402/evm`, `@x402/fetch`, `@x402/extensions`
Blockchain	Base (OP Stack L2), stablecoin USDC
Facilitador	Facilitador x402 de PayAI (`x402.org/facilitator`)
Runtime de IA	Ollama (inferencia local)
LLM	Gemma 3 1B (predeterminado) / Gemma 4 31B (recomendado)
Wallet	`viem` (biblioteca cliente de Ethereum)
Configuración	dotenv

Despliegue

Desarrollo Local

# Base Sepolia testnet (recommended for development)
cp .env.example .env
# Edit .env: PAYMENT_NETWORK=eip155:84532
npm start

Producción (Red Principal de Base)

# 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 (recomendado para producción)

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"]

Variables de Entorno

Variable	Requerida	Predeterminado	Descripción
`PORT`	No	`4021`	Puerto del servidor
`SELLER_ADDRESS`	Sí	—	Dirección de wallet para recibir pagos USDC
`PAYMENT_NETWORK`	No	`eip155:84532`	Red blockchain (`eip155:8453` para red principal)
`FACILITATOR_URL`	No	`https://x402.org/facilitator`	Endpoint del facilitador x402
`OLLAMA_URL`	No	`http://127.0.0.1:11434`	URL base de la API de Ollama
`MODEL_SUMMARIZE`	No	`gemma3:1b`	Modelo para el endpoint de resumen
`MODEL_CLASSIFY`	No	`gemma3:1b`	Modelo para el endpoint de clasificación de seguros
`MODEL_EXTRACT`	No	`gemma3:1b`	Modelo para el endpoint de extracción
`PUBLIC_URL`	No	—	URL pública para metadatos de descubrimiento

Referencia de API

Endpoints Gratuitos

`GET /`

Página de inicio con catálogo de servicios y estadísticas de uso.

`GET /health`

Verificación de salud.

{ "ok": true, "ts": "2025-01-01T00:00:00.000Z" }

`GET /stats`

Estadísticas de ingresos y uso.

{
  "requests_paid": 42,
  "gross_usd": 0.84,
  "by_service": { "summarize": 0.42, "classify-insurance": 0.28, "extract": 0.14 },
  "last_20": [...]
}

`GET /.well-known/x402`

Catálogo de servicios legible por máquina (extensión de descubrimiento Bazaar). Úsalo para el descubrimiento automatizado de servicios por agentes de IA.

{
  "name": "AgentPay",
  "description": "Pay-per-call AI microservices (x402 / MPP)",
  "endpoints": [
    { "path": "/v1/summarize", "method": "POST", "price": "$0.01", "description": "Summarize text (200-20k chars)" },
    { "path": "/v1/classify-insurance", "method": "POST", "price": "$0.02", "description": "Insurance lead classification" },
    { "path": "/v1/extract", "method": "POST", "price": "$0.03", "description": "Structured field extraction" }
  ]
}

Endpoints de Pago

Todos los endpoints de pago requieren un pago x402 válido en la cabecera X-PAYMENT. Las solicitudes no pagadas reciben HTTP 402 Payment Required.

`POST /v1/summarize` — $0.01

Resumir texto en una salida concisa de ~250 palabras.

Solicitud:

{
  "text": "Your text to summarize (200-20000 characters)..."
}

Respuesta (200 OK):

{
  "summary": "The text discusses...",
  "words": 247
}

Errores:

400 — Falta el campo text o el texto supera los 20,000 caracteres
402 — Pago requerido (ver protocolo x402)
502 — El modelo de IA ascendente falló

`POST /v1/classify-insurance` — $0.02

Clasificar un lead de seguros o mensaje de cliente.

Solicitud:

{
  "text": "I was in a car accident last week and need to file a claim urgently..."
}

Respuesta (200 OK):

{
  "intent": "claim",
  "urgency": "high",
  "line": "auto",
  "confidence": 0.92
}

Valores posibles:

intent: quote_request | renewal | claim | complaint | other
urgency: low | medium | high
line: auto | home | life | health | commercial | other

`POST /v1/extract` — $0.03

Extraer campos estructurados de texto sin formato (correos, formularios, documentos).

Solicitud:

{
  "text": "From: john@example.com\nSubject: Policy #12345 renewal\nDear customer, your auto policy expires on March 15...",
  "fields": ["email", "policy_number", "expiry_date"]
}

Respuesta (200 OK):

{
  "email": "john@example.com",
  "policy_number": "12345",
  "expiry_date": "March 15"
}

Si se omite fields, se devuelven todos los pares clave-valor extraíbles.

Biblioteca Cliente (Comprador)

Usa @x402/fetch para manejar automáticamente el flujo 402 → pago → reintento:

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.BUYER_PK);
const client = x402Client.fromConfig({
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(signer) }],
});

const payFetch = wrapFetchWithPayment(globalThis.fetch, client);

// This automatically handles the 402 → payment → retry flow
const res = await payFetch("https://agentpay.help/v1/summarize", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "Your text here..." }),
});

const result = await res.json();
console.log(result.summary);

Contribuciones

¡Las contribuciones son bienvenidas! Esta es una implementación de referencia de código abierto del protocolo x402 / MPP.

Configuración de Desarrollo

git clone https://github.com/your-org/AgentPay.git
cd AgentPay
npm install
cp .env.example .env
# Edit .env with your test wallet and Base Sepolia settings
npm start

Añadir un Nuevo Servicio

Define la entrada del middleware de pago en src/server.js dentro de la llamada paymentMiddleware()
Añade el manejador de ruta después del bloque de middleware
Registra el endpoint en el descubrimiento /.well-known/x402
Añádelo al HTML de la página de inicio

Directrices

Mantenlo simple. Esta es una implementación de referencia — claridad sobre complejidad.
Prueba primero en Base Sepolia. Usa la red de prueba antes de pasar a la red principal.
Usa paquetes @x402/. No reinventes la verificación de pagos.
Libro mayor de solo añadidura. Nunca modifiques data/ledger.json — solo añade.

Reportar Problemas

Abre un issue en GitHub con:

Pasos para reproducir
Comportamiento esperado vs. real
Entorno (versión de Node, sistema operativo, modelo usado)

Licencia

MIT

Recursos

Especificación del Protocolo x402 — El Protocolo de Pagos por Máquina
Facilitador PayAI — Servicio de verificación de pagos
Red Base — OP Stack L2 donde se liquidan los pagos USDC
Ollama — Motor de inferencia LLM local
viem — Cliente TypeScript de Ethereum

AgentPay

Documentación

AgentPay — agentpay.help

Tabla de Contenidos

Inicio Rápido

Requisitos Previos

1. Clonar e instalar

2. Descargar el modelo de IA

3. Configurar

4. Iniciar el servidor

5. Probar una solicitud de pago

6. Comprar un servicio (cliente comprador)

Arquitectura

Servicios y Precios

Stack Tecnológico

Despliegue

Desarrollo Local

Producción (Red Principal de Base)

Docker (recomendado para producción)

Variables de Entorno

Referencia de API

Endpoints Gratuitos

GET /

GET /health

GET /stats

GET /.well-known/x402

Endpoints de Pago

POST /v1/summarize — $0.01

POST /v1/classify-insurance — $0.02

POST /v1/extract — $0.03

Biblioteca Cliente (Comprador)

Contribuciones

Configuración de Desarrollo

Añadir un Nuevo Servicio

Directrices

Reportar Problemas

Licencia

Recursos

`GET /`

`GET /health`

`GET /stats`

`GET /.well-known/x402`

`POST /v1/summarize` — $0.01

`POST /v1/classify-insurance` — $0.02

`POST /v1/extract` — $0.03