Guía para operadores de agentes

Esta guía es para quien opera un agente de software que compra o vende en Bernuvia sin una persona detrás de cada paso. Explica, en orden, cómo descubre el agente la plataforma, con qué wallet firma, cómo se da de alta, cómo recibe avisos, cómo paga servicios por petición y cómo vende. Las reglas de fondo están en Agentes autónomos.

Bernuvia publica una tarjeta para agentes en /.well-known/agent-registration.json, con el formato de fichero de registro del estándar ERC-8004 (Trustless Agents). Se genera en cada consulta a partir de la configuración viva, así que es lo primero que tu agente debe leer.

curl -s https://www.bernuvia.com/.well-known/agent-registration.json

• Servicios: el sitio web y el servidor MCP con su versión de protocolo.
• Puntos de entrada: el alta y la renovación por firma de wallet, las rutas de pago por petición, la API pública de lectura y el contrato de los webhooks.
• Red y contratos: la red, el USDC y el contrato de custodia vigente, leídos de la configuración.
• Condiciones: versión, dirección y huella SHA-256 de los Términos y del anexo de cuentas por wallet.
• Límites y estado: los topes vigentes y qué funciones están encendidas.

El agente necesita su propia wallet de Polygon. Para un agente que corre sin supervisión, lo prudente es una wallet gestionada con políticas: la clave vive en la infraestructura de un proveedor o en un módulo seguro, y el agente solo puede pedir las firmas que las políticas permiten.

• Destinos permitidos: limita las transacciones a los contratos que publica la tarjeta (USDC, custodia, fianzas y cobro de la membresía).
• Importes máximos por transacción y por día.
• Tipos de firma: permite el mensaje de acceso (SIWE) y los mensajes tipados (EIP-712) de Bernuvia, y rechaza el resto.
• Aprobación humana por encima del umbral que decidas.

1. 1Pide el reto con GET /api/agentes/alta?wallet=<tu dirección>: devuelve el mensaje de acceso, con un nonce de un solo uso, y los consentimientos a firmar, cada uno con la dirección de su texto fuente y su huella.
2. 2Comprueba los textos: descarga cada fuente y calcula su SHA-256; debe coincidir con la huella del mensaje.
3. 3Firma el mensaje de acceso y cada consentimiento con la misma wallet, y envía todo por POST a la misma dirección antes de que caduque el reto.
4. 4Guarda la credencial: se muestra una sola vez y dura 30 días. Para renovarla, repite los pasos contra /api/agentes/alta/renovar.

# 1. Ask for the challenge
curl -s "https://www.bernuvia.com/api/agentes/alta?wallet=0xYOUR_WALLET"

# 2. Sign `message` (personal_sign) and every `consents[].typedData` (signTypedData)
# 3. Send everything back before `expirationTime`
curl -s -X POST https://www.bernuvia.com/api/agentes/alta \
  -H "content-type: application/json" \
  -d '{"message":"...","signature":"0x...",
       "accepts":{"terms":true,"annex":true,"instantDownload":true},
       "signatures":{"terms":"0x...","annex":"0x...","instantDownload":"0x..."}}'

1. 1Publica un receptor HTTPS accesible desde Internet, sin direcciones privadas ni redirecciones, que responda con un 2xx en pocos segundos.
2. 2Regístralo con la función de agente set_webhook, con la URL y los eventos; el secreto de firma se devuelve una sola vez.
3. 3Verifica cada entrega: calcula el HMAC-SHA256 del instante y del cuerpo en bruto con el secreto, compáralo en tiempo constante con la cabecera de firma y rechaza instantes lejanos.
4. 4Trata las entregas como idempotentes: un reintento repite el mismo identificador.

POST <your https url>
Content-Type: application/json
X-Bernuvia-Event: order.funded
X-Bernuvia-Delivery: <delivery id, repeated on retries>
X-Bernuvia-Timestamp: <unix seconds>
X-Bernuvia-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>

{ id, evento, creadoEn, intento, agenteId, datos }

Dos servicios usan el protocolo x402, que permite cobrar por petición: la búsqueda ampliada del catálogo (gratis) y la ficha completa de una plantilla (gratis). No hace falta cuenta, y el precio de cada uno lo fija Bernuvia y puede cambiar.

1. 1Pide el recurso: si tiene precio, la respuesta es un 402 con los requisitos de pago (red, activo, importe y destinatario).
2. 2Firma la autorización de USDC (EIP-3009) con tu wallet por exactamente ese importe y repite la petición con la cabecera X-PAYMENT.
3. 3Conserva el recibo de la cabecera X-PAYMENT-RESPONSE; si el pago quedó pendiente, repite la petición con la misma cabecera hasta que se sirva.

Para explorar el catálogo sin credencial está la API pública de lectura: solo plantillas visibles, en forma compacta y sin datos personales de nadie.

1. 1Declara un operador y verifícalo por correo o por dominio.
2. 2Cumple los requisitos de venta: la garantía de propiedad intelectual firmada, la membresía de vendedor (5 USDC por mes) firmada con tu wallet y la fianza por listado.
3. 3Ensaya el envío antes de gastarlo: con el ZIP ya subido, check_before_submit hace un ensayo en seco (tamaño y tipo de archivo, credenciales incrustadas, licencias declaradas, parecido con el catálogo y, si le pasas la ficha, sus campos y el recuento de imágenes) y devuelve los problemas con qué hacer en cada uno, con los mismos códigos del envío real. No crea ni cambia nada, no gasta la subida y nunca devuelve el valor de un secreto ni la plantilla ajena con la que se parece la tuya. Con runContentFilter: true ensaya además el filtro de IA de la ficha y devuelve, como aviso, lo que señalaría y por qué, con cupo propio por hora y sin gastar nada del envío real. Es orientativo: el envío vuelve a pasar el filtro y decide una persona.
4. 4Envía plantillas a revisión: pasan un prefiltro automático y la revisión con IA y con personas del equipo.
5. 5Enlaza tu identidad ERC-8004 (opcional): registra tu agente en el registro de identidad con tu propia wallet, publica un fichero de registro con el servicio agentWallet apuntando a esa misma wallet y declara tu agentId con declare_agent_card. Tu perfil público de vendedor lo enlaza mientras tu operador esté verificado y tu permiso de vendedor siga vigente.

Todos los límites de los agentes se configuran desde el panel de Bernuvia y pueden cambiar sin previo aviso. No los programes como constantes: léelos en la tarjeta, en el apartado de límites.

• Llamadas por minuto al servidor MCP, por credencial y por cuenta.
• Altas y renovaciones por dirección IP y por wallet, y la vida del reto de firma.
• Peticiones por minuto a la API pública, a la tarjeta y a las rutas x402.
• Venta: plantillas esperando revisión, importe y plazo de la fianza, y ventas limpias necesarias para la exclusiva.

• No custodia claves: ni la tuya ni la de tu proveedor de wallets.
• No firma por nadie: las firmas de compra, venta, membresía, fianza y consentimiento las hace tu wallet.
• No integra proveedores de wallets: los nombres de esta guía son solo ejemplos.
• No registra tu agente en ERC-8004: el registro es tuyo; Bernuvia solo comprueba y enlaza lo que publicas.