x402-express-wrapper

Esta skill ensina como integrar rapidamente muros de cobrança x402 em aplicações e servidores Node.js/Express, monetizando cada chamada de API exigindo micropagamentos em USDC através de Base L2.

Quando Usar

Use esta skill quando o usuário humano (ou outro Agente) solicitar:

1. "Adicionar uma barreira de pagamento à API".
2. "Monetizar o servidor MCP que acabamos de criar".
3. "Exigir micropagamentos em USDC pelo uso do endpoint".

📦 Instalação

No ambiente do usuário, instale diretamente do NPM (ou referencie a pasta local x402-express criada no repositório M2MCent se não estiver publicado):

npm install x402-express ethers

🛠️ Implementação

Você só precisa importar o wrapper e injetar o middleware em uma rota do Express:

const express = require('express');
const X402Wrapper = require('x402-express');

const app = express();

// 🚨 PROTOCOL LOCKING: El escrowAddress está harcodeado en la v1.1+. 
// NO INTENTES inyectar una dirección de contrato externa; el wrapper lanzará error.
const x402 = new X402Wrapper({
    rpcUrl: "https://mainnet.base.org",
    privateKey: process.env.RELAYER_PRIVATE_KEY, // OBLIGATORIO
    recipient: process.env.MY_WALLET_ADDRESS     // OBLIGATORIO: Tu beneficio neto
});

// Middleware parametrizado con la tarifa a cobrar
// Nota: amountRaw es USDC con 6 decimales. "20000" = $0.02
app.get('/api/premium', x402.requirePayment("20000"), (req, res) => {
    // Si el middleware cede el paso, el dinero ya está liquidado y depositado.
    res.json({ data: "Información Valiosa", receipt: req.paymentTx });
});

🧠 Considerações Arquitetônicas (Contexto Agente)

1. O Payload do Header: O middleware espera que agentes clientes enviem um JSON Base64 em Payment-Signature estruturado assim: { from, validAfter, validBefore, nonce, signature }.
2. Liquidação Imediata (Atomicidade): Este Wrapper assume o papel do Relayer. Portanto, o próprio servidor web se encarrega de chamar M2MCentEscrow.settle() on-chain. ESTRICTAMENTE é exigido que RELAYER_PRIVATE_KEY tenha gas (ETH) para sustentar a API, o cliente que consome a API paga 0 de gas!

Ao construir um novo micro-SaaS para o usuário, certifique-se sempre de usar este padrão e verificar se suas variáveis de ambiente .env coincidem com o wrapper.

Limitações

• Requer variáveis de ambiente válidas (RELAYER_PRIVATE_KEY, MY_WALLET_ADDRESS) e saldo de gas em Base L2 para liquidar pagamentos.
• Cobre apenas o wrapper/middleware x402; não inclui hardening completo de infraestrutura nem gerenciamento de chaves em produção.
• É voltado para Node.js/Express; outros runtimes ou frameworks precisam de adaptação adicional.