agent-payment-x402

Ejecución de Pagos de Agente (x402)

Permite que los agentes de IA realicen pagos controlados por políticas con controles de gasto integrados. Utiliza el protocolo de pago HTTP x402 y herramientas MCP para que los agentes puedan pagar por servicios externos, APIs u otros agentes sin riesgo de custodia.

Cuándo Usarlo

Úsalo cuando: tu agente necesite pagar por una llamada API, comprar un servicio, liquidar con otro agente, imponer límites de gasto por tarea o administrar una billetera sin custodia. Se combina naturalmente con las habilidades cost-aware-llm-pipeline y security-review.

Árbol de Decisión

Elige la ruta de integración según si tu agente está comprando acceso a una API de pago o cobrando a otros por una:

Necesidad	Ruta Recomendada
El agente paga una API con 402 en Base u otra cadena compatible con agentwallet	Usa agentwallet-sdk como servidor de pago MCP con una política de gasto estricta
El agente paga una API con 402 en X Layer	Usa OKX Agent Payments Protocol de okx/onchainos-skills; okx-x402-payment es un alias heredado obsoleto
API en TypeScript cobra a agentes	Usa la documentación del SDK de vendedor de OKX Payments para Express, Hono, Fastify o Next.js
API en Go cobra a agentes	Usa la documentación del SDK de vendedor de OKX Payments para Gin, Echo o net/http
API en Rust cobra a agentes	Usa la documentación del SDK de vendedor de OKX Payments para Axum
API en Java cobra a agentes	Usa la documentación del SDK de vendedor de OKX Payments para Spring Boot 2/3, Java EE o Jakarta
API en Python cobra a agentes	Consulta el repositorio actual de OKX Payments antes de implementar; es posible que no haya una guía de vendedor para Python

Redes Compatibles

• agentwallet-sdk: usa la documentación del paquete para confirmar la cobertura de red actual antes de la producción. Base Sepolia es el valor predeterminado de desarrollo más seguro; Base mainnet es la ruta de producción señalada en la habilidad original.
• OKX Payments / X Layer: la documentación actual del vendedor apunta a X Layer (eip155:196) y liquidación con USDT0. Obtén la documentación actual del SDK antes de generar código de producción, ya que los paquetes de pago y el comportamiento del facilitador pueden cambiar rápidamente.

Cómo Funciona

Protocolo x402

x402 extiende HTTP 402 (Pago Requerido) en un flujo negociable por máquina. Cuando un servidor devuelve 402, la herramienta de pago del agente negocia el precio, verifica el presupuesto, firma una transacción y reintenta solo dentro del límite de política y confirmación establecido por el orquestador.

Controles de Gasto

Cada llamada a una herramienta de pago aplica una SpendingPolicy:

• Presupuesto por tarea — gasto máximo para una sola acción del agente
• Presupuesto por sesión — límite acumulativo en toda una sesión
• Destinatarios en lista blanca — restringe qué direcciones/servicios puede pagar el agente
• Límites de tasa — máximo de transacciones por minuto/hora

Billeteras Sin Custodia

Los agentes poseen sus propias claves a través de cuentas inteligentes ERC-4337. El orquestador establece la política antes de la delegación; el agente solo puede gastar dentro de los límites. Sin fondos mancomunados, sin riesgo de custodia.

Integración MCP

La capa de pago expone herramientas MCP estándar que encajan en cualquier configuración de Claude Code o arnés de agente.

Nota de seguridad: Siempre fija la versión del paquete. Esta herramienta administra claves privadas — las instalaciones de npx sin fijar introducen riesgo en la cadena de suministro.

Opción A: agentwallet-sdk (Base / multi-cadena)

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["[email protected]"]
    }
  }
}

Herramientas Disponibles (llamables por el agente)

Herramienta	Propósito
get_balance	Verificar saldo de la billetera del agente
send_payment	Enviar pago a una dirección o ENS
check_spending	Consultar el presupuesto restante
list_transactions	Registro de auditoría de todos los pagos

Nota: La política de gasto la establece el orquestador antes de delegar al agente, no el agente mismo. Esto evita que los agentes aumenten sus propios límites de gasto. Configura la política mediante set_policy en tu capa de orquestación o en un enlace previo a la tarea, nunca como una herramienta llamable por el agente.

Opción B: OKX Agent Payments Protocol (X Layer)

Usa esta ruta para X Layer x402, Pago Multiparte (MPP), pago por sesión, cargo y flujos de cargo A2A.

Para flujos de agente comprador:

1. Instala o referencia el repositorio actual de okx/onchainos-skills.
2. Usa skills/okx-agent-payments-protocol/SKILL.md como despachador.
3. Trata skills/okx-x402-payment/SKILL.md como un alias de compatibilidad obsoleto, no como la habilidad canónica.
4. Exige confirmación explícita del usuario antes de verificaciones de estado de la billetera o acciones de pago. No ocultes la ejecución del pago detrás de una llamada de herramienta genérica.

Para flujos de API de vendedor, obtén la guía específica del lenguaje más reciente antes de generar código:

Tiempo de ejecución	Guía actual
TypeScript	https://raw.githubusercontent.com/okx/payments/main/typescript/SELLER.md
Go	https://raw.githubusercontent.com/okx/payments/main/go/x402/SELLER.md
Rust	https://raw.githubusercontent.com/okx/payments/main/rust/x402/SELLER.md
Java	https://raw.githubusercontent.com/okx/payments/main/java/SELLER.md

No copies ejemplos de documentaciones antiguas sin verificar el repositorio actual de OKX. La guía actual de OKX usa okx-agent-payments-protocol como despachador, y ahora hay documentación para vendedor en Java.

Ejemplos

Cumplimiento de presupuesto en un cliente MCP

Al construir un orquestador que llama al servidor MCP agentpay, aplica los presupuestos antes de despachar llamadas de herramientas pagadas.

Requisitos previos: Instala el paquete antes de agregar la configuración MCP — npx sin -y solicitará confirmación en entornos no interactivos, lo que hará que el servidor se cuelgue: npm install -g [email protected]

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 1. Valida las credenciales antes de construir el transporte.
  //    Una clave faltante debe fallar de inmediato — nunca permitas que el subproceso se inicie sin autenticación.
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY no está configurada — rechazando iniciar el servidor de pagos");
  }

  // Conéctate al servidor MCP agentpay a través del transporte stdio.
  // Incluye solo en la lista blanca las variables de entorno que el servidor necesita — nunca reenvíes todo process.env
  // a un subproceso de terceros que administra claves privadas.
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["[email protected]"],
    env: {
      PATH: process.env.PATH ?? "",
      NODE_ENV: process.env.NODE_ENV ?? "production",
      WALLET_PRIVATE_KEY: walletKey,
    },
  });
  const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
  await agentpay.connect(transport);

  // 2. Establece la política de gasto antes de delegar al agente.
  //    Siempre verifica el éxito — un fallo silencioso significa que no hay controles activos.
  const policyResult = await agentpay.callTool({
    name: "set_policy",
    arguments: {
      per_task_budget: 0.50,
      per_session_budget: 5.00,
      allowlisted_recipients: ["api.example.com"],
    },
  });
  if (policyResult.isError) {
    throw new Error(
      `Error al establecer la política de gasto — no delegues: ${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. Usa preToolCheck antes de cualquier acción pagada
  await preToolCheck(agentpay, 0.01);
}

// Enlace previo a la herramienta: cumplimiento de presupuesto con cierre seguro con cuatro rutas de error distintas.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Ruta 1: Rechazar entrada inválida (NaN/Infinity evita la comparación <)
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`apiCost inválido: ${apiCost} — acción bloqueada`);
  }

  // Ruta 2: Fallo de transporte/conectividad
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Servicio de pago inalcanzable — acción bloqueada: ${err}`);
  }

  // Ruta 3: La herramienta devolvió un error (por ejemplo, fallo de autenticación, billetera no inicializada)
  if (result.isError) {
    throw new Error(
      `check_spending falló — acción bloqueada: ${JSON.stringify(result.content)}`
    );
  }

  // Ruta 4: Analizar y validar la forma de la respuesta
  let remaining: number;
  try {
    const parsed = JSON.parse(
      (result.content as Array<{ text: string }>)[0].text
    );
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("campo 'remaining' faltante o no finito");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending devolvió un formato inesperado — acción bloqueada: ${err}`
    );
  }

  // Ruta 5: Presupuesto excedido
  if (remaining < apiCost) {
    throw new Error(
      `Presupuesto excedido: se necesitan $${apiCost} pero solo quedan $${remaining}`
    );
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

Mejores Prácticas

• Establece presupuestos antes de delegar: Al generar subagentes, adjunta una SpendingPolicy a través de tu capa de orquestación. Nunca le des a un agente gasto ilimitado.
• Fija tus dependencias: Siempre especifica una versión exacta en tu configuración MCP (por ejemplo, [email protected]). Verifica la integridad del paquete antes de implementar en producción.
• Registros de auditoría: Usa list_transactions en enlaces posteriores a la tarea para registrar qué se gastó y por qué.
• Cierre seguro: Si la herramienta de pago es inalcanzable, bloquea la acción pagada — no recurras al acceso sin medición.
• Combínalo con security-review: Las herramientas de pago tienen privilegios elevados. Aplica el mismo escrutinio que al acceso al shell.
• Prueba primero con testnets: Usa Base Sepolia para desarrollo; cambia a Base mainnet para producción.

Referencia de Producción

• npm: agentwallet-sdk
• Integrado en NVIDIA NeMo Agent Toolkit: PR #17 — herramienta de pago x402 para los ejemplos de agente de NVIDIA
• Especificación del protocolo: x402.org
• SDKs de OKX Payments: okx/payments — integraciones de vendedor en TypeScript, Go, Rust y Java para X Layer x402
• Habilidad OKX Agent Payments Protocol: okx/onchainos-skills
• Resumen de OKX Payments: web3.okx.com/onchainos/dev-docs/payments/overview