AgentPay

Microsserviços de IA pagos por chamada via protocolo x402. 22 serviços: sumarização de texto, tradução, revisão de código, análise de sentimentos, análise de seguros, segurança cripto, rendimentos DeFi, inteligência de ameaças. USDC na Base.

GitHubExperimente este MCPPatrocinado

Documentação

AgentPay — agentpay.help

Microserviços de IA pagáveis por máquina via protocolo 402 Payment Required (x402 / MPP)

Sem contas. Sem chaves de API. Sem OAuth. Pague por chamada em USDC na Base.

AgentPay é uma implementação de referência open-source do Machine Payments Protocol — envolvendo modelos de IA locais atrás de um paywall HTTP 402 para que agentes de IA (e humanos) possam pagar por computação por requisição usando stablecoins.

Construído com Express 5, @x402/express e modelos Gemma servidos por Ollama. Ativo na mainnet da Base com o facilitador PayAI.

Início Rápido

Pré-requisitos

Node.js ≥ 20
Ollama rodando localmente com o modelo necessário baixado
Uma chave privada de carteira (para receber pagamentos)

1. Clone e instale

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

2. Baixe o modelo de IA

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. Inicie o servidor

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

5. Teste uma requisição paga

# 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. Compre um serviço (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

Arquitetura

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

Como funciona:

O cliente envia POST /v1/summarize (ou qualquer endpoint pago) — sem necessidade de cabeçalhos de autenticação
O middleware de pagamento intercepta e retorna HTTP 402 com informações de preço (accepts[])
O cliente constrói um pagamento em USDC, assina e anexa o cabeçalho X-PAYMENT
O facilitador verifica o pagamento na mainnet da Base
O middleware concede acesso → a requisição prossegue para o manipulador do serviço
O manipulador chama o Ollama e retorna o resultado gerado por IA como JSON

Serviços e Preços

Endpoint	Preço	Descrição
`POST /v1/summarize`	$0,01	Resumir texto (200–20.000 caracteres). Retorna um resumo de ~250 palavras.
`POST /v1/classify-insurance`	$0,02	Classificar leads de seguros: intenção, urgência, ramo de atuação, pontuação de confiança.
`POST /v1/sentiment`	$0,02	Análise de sentimento: positivo/negativo/neutro com emoções e palavras-chave.
`POST /v1/extract`	$0,03	Extrair campos estruturados chave-valor de texto bruto (e-mails, formulários, documentos).
`POST /v1/translate`	$0,03	Tradução de texto para qualquer idioma.
`POST /v1/code-review`	$0,05	Revisão de código por IA: bugs, problemas de segurança, desempenho, análise de qualidade.
`POST /v1/insurance-analysis`	$0,10	⭐ PACOTE COMPLETO — classificação + extração + resumo em uma única chamada.

Todos os serviços aceitam USDC na mainnet da Base (chain ID 8453) via esquema de pagamento exact. A testnet (Base Sepolia) está disponível via configuração.

Stack Tecnológico

Componente	Tecnologia
Runtime	Node.js ≥ 20 (ESM)
Servidor HTTP	Express 5.2
Protocolo de Pagamento	`@x402/express` 2.22, `@x402/evm`, `@x402/fetch`, `@x402/extensions`
Blockchain	Base (OP Stack L2), stablecoin USDC
Facilitador	Facilitador x402 PayAI (`x402.org/facilitator`)
Runtime de IA	Ollama (inferência local)
LLM	Gemma 3 1B (padrão) / Gemma 4 31B (recomendado)
Carteira	`viem` (biblioteca cliente Ethereum)
Configuração	dotenv

Implantação

Desenvolvimento Local

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

Produção (Mainnet da 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 produção)

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

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`PORT`	Não	`4021`	Porta do servidor
`SELLER_ADDRESS`	Sim	—	Endereço da carteira para receber pagamentos em USDC
`PAYMENT_NETWORK`	Não	`eip155:84532`	Rede blockchain (`eip155:8453` para mainnet)
`FACILITATOR_URL`	Não	`https://x402.org/facilitator`	Endpoint do facilitador x402
`OLLAMA_URL`	Não	`http://127.0.0.1:11434`	URL base da API do Ollama
`MODEL_SUMMARIZE`	Não	`gemma3:1b`	Modelo para o endpoint de resumo
`MODEL_CLASSIFY`	Não	`gemma3:1b`	Modelo para o endpoint de classificação de seguros
`MODEL_EXTRACT`	Não	`gemma3:1b`	Modelo para o endpoint de extração
`PUBLIC_URL`	Não	—	URL pública para metadados de descoberta

Referência da API

Endpoints Gratuitos

`GET /`

Página inicial com catálogo de serviços e estatísticas de uso.

`GET /health`

Verificação de saúde.

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

`GET /stats`

Estatísticas de receita e 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 serviços legível por máquina (extensão de descoberta Bazaar). Use para descoberta automatizada de serviços 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 Pagos

Todos os endpoints pagos exigem um pagamento x402 válido no cabeçalho X-PAYMENT. Requisições não pagas recebem HTTP 402 Payment Required.

`POST /v1/summarize` — $0,01

Resumir texto em uma saída concisa de ~250 palavras.

Requisição:

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

Resposta (200 OK):

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

Erros:

400 — Campo text ausente ou texto excede 20.000 caracteres
402 — Pagamento necessário (veja protocolo x402)
502 — Falha no modelo de IA upstream

`POST /v1/classify-insurance` — $0,02

Classificar um lead de seguro ou mensagem de cliente.

Requisição:

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

Resposta (200 OK):

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

Valores possíveis:

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

`POST /v1/extract` — $0,03

Extrair campos estruturados de texto bruto (e-mails, formulários, documentos).

Requisição:

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

Resposta (200 OK):

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

Se fields for omitido, todos os pares chave-valor extraíveis são retornados.

Biblioteca Cliente (Comprador)

Use @x402/fetch para lidar automaticamente com o fluxo 402 → pagamento → nova tentativa:

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);

Contribuição

Contribuições são bem-vindas! Esta é uma implementação de referência open-source do protocolo x402 / MPP.

Configuração de Desenvolvimento

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

Adicionando um Novo Serviço

Defina a entrada do middleware de pagamento em src/server.js dentro da chamada paymentMiddleware()
Adicione o manipulador de rota após o bloco do middleware
Registre o endpoint na descoberta /.well-known/x402
Adicione ao HTML da página inicial

Diretrizes

Mantenha simples. Esta é uma implementação de referência — clareza acima de complexidade.
Teste na Base Sepolia primeiro. Use a testnet antes de ir para a mainnet.
Use pacotes @x402/. Não reinvente a verificação de pagamentos.
Ledger somente anexação. Nunca modifique data/ledger.json — apenas anexe.

Reportando Problemas

Abra uma issue no GitHub com:

Passos para reproduzir
Comportamento esperado vs. real
Ambiente (versão do Node, SO, modelo usado)

Licença

MIT

Recursos

Especificação do Protocolo x402 — O Machine Payments Protocol
Facilitador PayAI — Serviço de verificação de pagamentos
Rede Base — OP Stack L2 onde os pagamentos em USDC são liquidados
Ollama — Motor de inferência LLM local
viem — Cliente Ethereum em TypeScript

AgentPay

Documentação

AgentPay — agentpay.help

Sumário

Início Rápido

Pré-requisitos

1. Clone e instale

2. Baixe o modelo de IA

3. Configure

4. Inicie o servidor

5. Teste uma requisição paga

6. Compre um serviço (cliente comprador)

Arquitetura

Serviços e Preços

Stack Tecnológico

Implantação

Desenvolvimento Local

Produção (Mainnet da Base)

Docker (recomendado para produção)

Variáveis de Ambiente

Referência da API

Endpoints Gratuitos

GET /

GET /health

GET /stats

GET /.well-known/x402

Endpoints Pagos

POST /v1/summarize — $0,01

POST /v1/classify-insurance — $0,02

POST /v1/extract — $0,03

Biblioteca Cliente (Comprador)

Contribuição

Configuração de Desenvolvimento

Adicionando um Novo Serviço

Diretrizes

Reportando Problemas

Licença

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