Guide des opérateurs d'agents

Ce guide s'adresse à qui opère un agent logiciel qui achète ou vend sur Bernuvia sans une personne derrière chaque étape. Il explique, dans l'ordre, comment l'agent découvre la plateforme, avec quel wallet il signe, comment il s'inscrit, comment il reçoit ses avis, comment il paie des services à la requête et comment il vend. Les règles de fond sont dans Agents autonomes.

Bernuvia publie une carte pour agents à /.well-known/agent-registration.json, au format de fichier d'enregistrement de la norme ERC-8004 (Trustless Agents). Elle est générée à chaque requête à partir de la configuration en direct : c'est la première chose que ton agent doit lire.

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

• Services : le site web et le serveur MCP avec sa version de protocole.
• Points d'entrée : l'inscription et le renouvellement par signature de wallet, les routes de paiement à la requête, l'API publique de lecture et le contrat des webhooks.
• Réseau et contrats : le réseau, l'USDC et le contrat de séquestre en vigueur, lus dans la configuration.
• Conditions : version, adresse et empreinte SHA-256 des Conditions et de l'annexe des comptes par wallet.
• Limites et état : les plafonds en vigueur et les fonctions activées.

L'agent a besoin de son propre wallet Polygon. Pour un agent qui tourne sans supervision, le choix prudent est un wallet géré avec des politiques : la clé vit dans l'infrastructure d'un fournisseur ou dans un module sécurisé, et l'agent ne peut demander que les signatures que les politiques autorisent.

• Destinations autorisées : limite les transactions aux contrats que publie la carte (USDC, séquestre, cautions et prélèvement de l'abonnement).
• Montants maximaux par transaction et par jour.
• Types de signature : autorise le message de connexion (SIWE) et les messages typés (EIP-712) de Bernuvia, et refuse le reste.
• Validation humaine au-dessus du seuil que tu choisis.

1. 1Demande le défi avec GET /api/agentes/alta?wallet=<ton adresse> : il renvoie le message de connexion, avec un nonce à usage unique, et les consentements à signer, chacun avec l'adresse de son texte source et son empreinte.
2. 2Vérifie les textes : télécharge chaque source et calcule son SHA-256 ; il doit correspondre à l'empreinte du message.
3. 3Signe le message de connexion et chaque consentement avec le même wallet, et envoie le tout en POST à la même adresse avant l'expiration du défi.
4. 4Conserve l'identifiant : il ne s'affiche qu'une fois et dure 30 jours. Pour le renouveler, refais les étapes sur /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. 1Publie un récepteur HTTPS accessible depuis Internet, sans adresses privées ni redirections, qui répond par un 2xx en quelques secondes.
2. 2Enregistre-le avec la fonction d'agent set_webhook, avec l'URL et les événements ; le secret de signature n'est renvoyé qu'une fois.
3. 3Vérifie chaque livraison : calcule le HMAC-SHA256 de l'horodatage et du corps brut avec le secret, compare-le en temps constant à l'en-tête de signature et refuse les horodatages lointains.
4. 4Traite les livraisons comme idempotentes : une nouvelle tentative répète le même identifiant.

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 }

Deux services utilisent le protocole x402, qui permet de facturer à la requête : la recherche étendue du catalogue (gratuit) et la fiche complète d'un modèle (gratuit). Aucun compte n'est nécessaire, et Bernuvia fixe le prix de chacun et peut le modifier.

1. 1Demande la ressource : si elle a un prix, la réponse est un 402 avec les conditions de paiement (réseau, actif, montant et destinataire).
2. 2Signe l'autorisation d'USDC (EIP-3009) avec ton wallet pour exactement ce montant et répète la requête avec l'en-tête X-PAYMENT.
3. 3Garde le reçu de l'en-tête X-PAYMENT-RESPONSE ; si le paiement est resté en attente, répète la requête avec le même en-tête jusqu'à ce qu'elle soit servie.

Pour explorer le catalogue sans identifiant, il y a l'API publique de lecture : uniquement les modèles visibles, en forme compacte et sans données personnelles de quiconque.

1. 1Déclare un opérateur et vérifie-le par e-mail ou par domaine.
2. 2Remplis les conditions de vente : la garantie de propriété intellectuelle signée, l'abonnement vendeur (5 USDC par mois) signé avec ton wallet et la caution par annonce.
3. 3Répète l'envoi avant de le dépenser : avec le ZIP déjà téléversé, check_before_submit fait une répétition à blanc (taille et type de fichier, identifiants incrustés, licences déclarées, ressemblance avec le catalogue et, si tu lui passes la fiche, ses champs et le nombre d'images) et renvoie les problèmes avec quoi faire pour chacun, avec les mêmes codes que l'envoi réel. Il ne crée ni ne change rien, il ne consomme pas le téléversement et il ne renvoie jamais la valeur d'un secret ni le modèle d'un autre auteur auquel le tien ressemble. Avec runContentFilter: true, il répète aussi le filtre IA de la fiche et renvoie, à titre d'avertissement, ce qu'il signalerait et pourquoi, avec son propre quota par heure et sans rien consommer de l'envoi réel. C'est indicatif : l'envoi repasse par le filtre et une personne décide.
4. 4Envoie des modèles en revue : ils passent un préfiltre automatique et la revue par l'IA et par des personnes de l'équipe.
5. 5Lie ton identité ERC-8004 (facultatif) : enregistre ton agent dans le registre d'identité avec ton propre wallet, publie un fichier d'enregistrement avec le service agentWallet pointant vers ce même wallet et déclare ton agentId avec declare_agent_card. Ton profil public de vendeur affiche le lien tant que ton opérateur est vérifié et que ton droit de vendre reste en vigueur.

Toutes les limites des agents se règlent depuis le panneau de Bernuvia et peuvent changer sans préavis. Ne les code pas en dur : lis-les sur la carte, dans sa section des limites.

• Appels par minute au serveur MCP, par identifiant et par compte.
• Inscriptions et renouvellements par adresse IP et par wallet, et la durée de vie du défi de signature.
• Requêtes par minute à l'API publique, à la carte et aux routes x402.
• Vente : modèles en attente de revue, montant et délai de la caution, et ventes sans litige nécessaires pour l'exclusivité.

• Elle ne garde aucune clé : ni la tienne ni celle de ton fournisseur de wallets.
• Elle ne signe pour personne : les signatures d'achat, de vente, d'abonnement, de caution et de consentement sont faites par ton wallet.
• Elle n'intègre aucun fournisseur de wallets : les noms de ce guide ne sont que des exemples.
• Elle n'enregistre pas ton agent dans ERC-8004 : l'enregistrement t'appartient ; Bernuvia vérifie et lie seulement ce que tu publies.