agent-payment-x402

Ejecución de Pagos de Agente (x402)

Permite a los agentes de IA realizar pagos con control de políticas y 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, hacer cumplir límites de gasto por tarea, o gestionar una billetera no custodiada. Se combina naturalmente con los skills de 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 bloqueo 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 bloqueo 402 en X Layer	Usa el Protocolo de Pagos de OKX Agent desde okx/onchainos-skills; okx-x402-payment es un alias heredado obsoleto
API TypeScript cobra a agentes	Usa la documentación del SDK de vendedor OKX Payments TypeScript para Express, Hono, Fastify o Next.js
API Go cobra a agentes	Usa la documentación del SDK de vendedor OKX Payments Go para Gin, Echo o net/http
API Rust cobra a agentes	Usa la documentación del SDK de vendedor OKX Payments Rust para Axum
API Java cobra a agentes	Usa la documentación del SDK de vendedor OKX Payments Java para Spring Boot 2/3, Java EE o Jakarta
API Python cobra a agentes	Verifica el repositorio actual de OKX Payments antes de la implementación; es posible que no haya una guía de vendedor Python disponible

Redes Soportadas

• agentwallet-sdk: consulta la documentación del paquete para confirmar la cobertura de red actual antes de producción. Base Sepolia es la opción de desarrollo más segura; Base mainnet es la ruta de producción indicada por el skill original.
• OKX Payments / X Layer: la documentación de vendedor actual apunta a X Layer (eip155:196) y liquidación 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) a un flujo negociable entre máquinas. 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 la 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 No Custodiadas

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 comunes, sin riesgo de custodia.

Integración MCP

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

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

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

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

Herramientas Disponibles (invocables por el agente)

Herramienta	Propósito
get_balance	Consultar el 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 es establecida por el orquestador antes de delegar al agente, no por 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 hook previo a la tarea, nunca como una herramienta invocable por el agente.

Opción B: Protocolo de Pagos de OKX Agent (X Layer)

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

Para flujos de agente del lado 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 el skill canónico.
4. Exige confirmación explícita del usuario antes de verificaciones de estado de billetera o acciones de pago. No ocultes la ejecución de pagos detrás de una llamada genérica a una herramienta.

Para flujos de API del lado vendedor, obtén la guía más reciente específica del lenguaje 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 documentación antigua sin verificar el repositorio actual de OKX. La guía actual de OKX usa okx-agent-payments-protocol como despachador, y la documentación de vendedor Java ya está disponible.

Ejemplos

Aplicación de presupuesto en un cliente MCP

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

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 inmediatamente — 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 en la lista blanca solo las variables de entorno que el servidor necesita — nunca reenvíes todo process.env
  // a un subproceso de terceros que gestiona 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 delegar: ${JSON.stringify(policyResult.content)}`
    );
  }

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

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

  // Ruta 2: Error 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;
});

Buenas Prácticas

• Establece presupuestos antes de la delegación: Al generar subagentes, asigna una SpendingPolicy a través de tu capa de orquestación. Nunca le des a un agente un 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 hooks posteriores a la tarea para registrar qué se gastó y por qué.
• Bloqueo en caso de fallo: Si la herramienta de pago no está disponible, bloquea la acción de pago — no recurras a acceso sin medición.
• Combínalo con security-review: Las herramientas de pago son de alto privilegio. Aplica el mismo escrutinio que al acceso al shell.
• Prueba primero en 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 TypeScript, Go, Rust y Java para x402 en X Layer
• Skill del Protocolo de Pagos de OKX Agent: okx/onchainos-skills
• Resumen de OKX Payments: web3.okx.com/onchainos/dev-docs/payments/overview