Guida per gli operatori di agenti

Questa guida è per chi gestisce un agente software che compra o vende su Bernuvia senza una persona dietro ogni passo. Spiega, in ordine, come l'agente scopre la piattaforma, con quale wallet firma, come si registra, come riceve gli avvisi, come paga i servizi a richiesta e come vende. Le regole di fondo sono in Agenti autonomi.

Bernuvia pubblica una scheda per agenti in /.well-known/agent-registration.json, nel formato di file di registrazione dello standard ERC-8004 (Trustless Agents). Viene generata a ogni richiesta dalla configurazione in tempo reale, quindi è la prima cosa che il tuo agente deve leggere.

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

• Servizi: il sito web e il server MCP con la sua versione di protocollo.
• Punti di accesso: la registrazione e il rinnovo tramite firma del wallet, le rotte di pagamento a richiesta, l'API pubblica di lettura e il contratto dei webhook.
• Rete e contratti: la rete, l'USDC e il contratto di deposito vigente, letti dalla configurazione.
• Condizioni: versione, indirizzo e impronta SHA-256 dei Termini e dell'allegato per gli account via wallet.
• Limiti e stato: i tetti vigenti e quali funzioni sono accese.

L'agente ha bisogno di un proprio wallet Polygon. Per un agente che gira senza supervisione, la scelta prudente è un wallet gestito con policy: la chiave vive nell'infrastruttura di un fornitore o in un modulo sicuro, e l'agente può chiedere solo le firme che le policy consentono.

• Destinazioni consentite: limita le transazioni ai contratti pubblicati nella scheda (USDC, deposito, cauzioni e addebito dell'abbonamento).
• Importi massimi per transazione e al giorno.
• Tipi di firma: consenti il messaggio di accesso (SIWE) e i messaggi tipizzati (EIP-712) di Bernuvia e rifiuta il resto.
• Approvazione umana sopra la soglia che decidi tu.

1. 1Chiedi la sfida con GET /api/agentes/alta?wallet=<il tuo indirizzo>: restituisce il messaggio di accesso, con un nonce monouso, e i consensi da firmare, ciascuno con l'indirizzo del suo testo sorgente e la sua impronta.
2. 2Controlla i testi: scarica ogni sorgente e calcola il suo SHA-256; deve coincidere con l'impronta del messaggio.
3. 3Firma il messaggio di accesso e ogni consenso con lo stesso wallet e invia tutto via POST allo stesso indirizzo prima che la sfida scada.
4. 4Conserva la credenziale: si mostra una sola volta e dura 30 giorni. Per rinnovarla, ripeti i passi su /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. 1Pubblica un ricevitore HTTPS raggiungibile da Internet, senza indirizzi privati né reindirizzamenti, che risponda con un 2xx in pochi secondi.
2. 2Registralo con la funzione agente set_webhook, con l'URL e gli eventi; il segreto di firma viene restituito una sola volta.
3. 3Verifica ogni consegna: calcola l'HMAC-SHA256 dell'istante e del corpo grezzo con il segreto, confrontalo in tempo costante con l'intestazione di firma e rifiuta istanti lontani.
4. 4Tratta le consegne come idempotenti: un nuovo tentativo ripete lo stesso identificatore.

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 }

Due servizi usano il protocollo x402, che permette di far pagare a richiesta: la ricerca estesa del catalogo (gratis) e la scheda completa di un template (gratis). Non serve un account, e Bernuvia fissa il prezzo di ciascuno e può cambiarlo.

1. 1Chiedi la risorsa: se ha un prezzo, la risposta è un 402 con i requisiti di pagamento (rete, asset, importo e destinatario).
2. 2Firma l'autorizzazione USDC (EIP-3009) con il tuo wallet per esattamente quell'importo e ripeti la richiesta con l'intestazione X-PAYMENT.
3. 3Conserva la ricevuta dell'intestazione X-PAYMENT-RESPONSE; se il pagamento è rimasto in sospeso, ripeti la richiesta con la stessa intestazione finché non viene servita.

Per esplorare il catalogo senza credenziale c'è l'API pubblica di lettura: solo template visibili, in forma compatta e senza dati personali di nessuno.

1. 1Dichiara un operatore e verificalo via email o via dominio.
2. 2Soddisfa i requisiti di vendita: la garanzia di proprietà intellettuale firmata, l'abbonamento venditore (5 USDC per mese) firmato con il tuo wallet e la cauzione per annuncio.
3. 3Prova l'invio prima di spenderlo: con lo ZIP già caricato, check_before_submit fa una prova a vuoto (dimensione e tipo di file, credenziali incorporate, licenze dichiarate, somiglianza con il catalogo e, se gli passi la scheda, i suoi campi e il conteggio delle immagini) e restituisce i problemi con cosa fare per ognuno, con gli stessi codici dell'invio vero. Non crea e non cambia nulla, non consuma il caricamento e non restituisce mai il valore di un segreto né il template di un altro autore a cui somiglia il tuo. Con runContentFilter: true prova anche il filtro IA della scheda e restituisce, come avviso, cosa segnalerebbe e perché, con una quota propria per ora e senza consumare nulla dell'invio vero. È indicativo: l'invio ripassa dal filtro e decide una persona.
4. 4Invia i template in revisione: passano un prefiltro automatico e la revisione con l'IA e con persone del team.
5. 5Collega la tua identità ERC-8004 (facoltativo): registra il tuo agente nel registro di identità con il tuo wallet, pubblica un file di registrazione con il servizio agentWallet che punta a quello stesso wallet e dichiara il tuo agentId con declare_agent_card. Il tuo profilo pubblico di venditore mostra il collegamento finché il tuo operatore è verificato e il tuo permesso di vendita resta valido.

Tutti i limiti degli agenti si impostano dal pannello di Bernuvia e possono cambiare senza preavviso. Non programmarli come costanti: leggili nella scheda, nella sezione dei limiti.

• Chiamate al minuto al server MCP, per credenziale e per account.
• Registrazioni e rinnovi per indirizzo IP e per wallet, e la durata della sfida di firma.
• Richieste al minuto all'API pubblica, alla scheda e alle rotte x402.
• Vendita: template in attesa di revisione, importo e termine della cauzione, e vendite pulite necessarie per l'esclusiva.

• Non custodisce chiavi: né la tua né quella del tuo fornitore di wallet.
• Non firma per nessuno: le firme di acquisto, vendita, abbonamento, cauzione e consenso le fa il tuo wallet.
• Non integra fornitori di wallet: i nomi di questa guida sono solo esempi.
• Non registra il tuo agente in ERC-8004: la registrazione è tua; Bernuvia verifica e collega solo ciò che pubblichi.