Kernel8901/ai-agent-skills-classification

Protocolo de Pago x402

x402 permite pagos instantáneos en stablecoins directamente sobre HTTP usando el código de estado 402 Payment Required. Perfecto para que agentes de IA paguen por APIs, datos o cómputo bajo demanda.

Inicio rápido

Instalar SDK

npm install x402
# o
pnpm add x402

Configuración del entorno

# Almacena la clave privada de la wallet de forma segura
export WALLET_PRIVATE_KEY="0x..."

# Opcional: especificar RPC de red
export BASE_RPC_URL="https://mainnet.base.org"

Cómo funciona x402

1. Solicitud → El cliente llama a una API de pago
2. Respuesta 402 → El servidor devuelve los detalles de pago en el encabezado PAYMENT-REQUIRED
3. Pagar y reintentar → El cliente firma el pago y reintenta con el encabezado PAYMENT-SIGNATURE
4. Acceso → El servidor verifica, liquida y devuelve el recurso

Usar el cliente x402

TypeScript/Node.js

import { x402Client } from 'x402';

const client = x402Client({
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'base', // o 'ethereum', 'arbitrum', etc.
});

// Manejo automático de 402
const response = await client.fetch('https://api.example.com/paid-endpoint');
const data = await response.json();

Con envoltorio fetch

import { wrapFetch } from 'x402';

const fetch402 = wrapFetch(fetch, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
});

// Úsalo como fetch normal - los 402 se manejan automáticamente
const res = await fetch402('https://paid-api.com/data');

Flujo manual (curl)

Paso 1: Descubrir requisitos de pago

curl -i https://api.example.com/paid-resource
# Devuelve 402 con encabezado PAYMENT-REQUIRED (JSON en base64)

Paso 2: Decodificar detalles de pago

# El encabezado PAYMENT-REQUIRED contiene JSON codificado en base64:
# {
#   "amount": "1000000",      # 1 USDC (6 decimales)
#   "currency": "USDC",
#   "network": "base",
#   "recipient": "0x...",
#   "scheme": "exact"
# }

Paso 3: Firmar y pagar

# Usa la CLI o SDK de x402 para crear la firma de pago
npx x402 pay \
  --amount 1000000 \
  --recipient 0x... \
  --network base

Paso 4: Reintentar con comprobante

curl -H "PAYMENT-SIGNATURE: <payload_base64>" \
  https://api.example.com/paid-resource

Patrones comunes

Pagar por llamadas a API

// API del clima que cuesta 0.001 USDC por llamada
const weather = await client.fetch('https://weather-api.x402.org/forecast?city=NYC');

Pagar por inferencia de IA

// API LLM con precio por token
const completion = await client.fetch('https://llm.example.com/v1/chat', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'Hola' }),
});

Verificar saldo antes de pagar

import { getBalance } from 'x402';

const balance = await getBalance({
  address: walletAddress,
  network: 'base',
  token: 'USDC',
});

if (balance < requiredAmount) {
  console.log('Saldo USDC insuficiente');
}

Redes soportadas

Red	Chain ID	Estado
Base	8453	✅ Primaria
Ethereum	1	✅ Soportada
Arbitrum	42161	✅ Soportada
Optimism	10	✅ Soportada
Polygon	137	✅ Soportada

Esquemas de pago

• exact: Pagar una cantidad fija (ej., $0.01 por llamada a API)
• upto: Pagar hasta un máximo según uso (ej., tokens LLM)
• subscription: Acceso basado en wallet con sesiones (V2)

Manejo de errores

try {
  const res = await client.fetch(url);
} catch (err) {
  if (err.code === 'INSUFFICIENT_BALANCE') {
    // Necesita fondear la wallet
  } else if (err.code === 'PAYMENT_FAILED') {
    // La transacción falló en la cadena
  } else if (err.code === 'INVALID_PAYMENT_REQUIREMENTS') {
    // El servidor envió una respuesta 402 mal formada
  }
}

Notas de seguridad

• Nunca expongas claves privadas en registros o chats
• Usa variables de entorno para las credenciales de la wallet
• Prefiere op run o similar para inyección de secretos
• Revisa los montos de pago antes de confirmar transacciones grandes

Funcionalidades V2 (Dic 2025)

• Identidad basada en wallet: Evita repagar en cada llamada con sesiones
• Autodescubrimiento: Las APIs exponen metadatos de pago en /.well-known/x402
• Multi-facilitador: Elige entre procesadores de pago
• Estándares CAIP: Identificadores universales de cadena/activo

Recursos

• Especificación: https://github.com/coinbase/x402
• Documentación: https://docs.cdp.coinbase.com/x402
• APIs demo: https://www.x402.org