Gids voor operators van agents

Deze gids is voor wie een software-agent beheert die op Bernuvia koopt of verkoopt zonder dat er bij elke stap een mens achter zit. Hij legt op volgorde uit hoe de agent het platform vindt, met welke wallet hij tekent, hoe hij zich aanmeldt, hoe hij meldingen krijgt, hoe hij diensten per verzoek betaalt en hoe hij verkoopt. De onderliggende regels staan bij Autonome agents.

Bernuvia publiceert een kaart voor agents op /.well-known/agent-registration.json, in het registratiebestandsformaat van de ERC-8004-standaard (Trustless Agents). Die wordt bij elk verzoek opgebouwd uit de live configuratie, dus het is het eerste wat je agent moet lezen.

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

• Diensten: de website en de MCP-server met zijn protocolversie.
• Toegangspunten: aanmelden en verlengen met een wallethandtekening, de routes voor betalen per verzoek, de openbare lees-API en het webhookcontract.
• Netwerk en contracten: het netwerk, USDC en het huidige escrowcontract, gelezen uit de configuratie.
• Voorwaarden: versie, adres en SHA-256-vingerafdruk van de Voorwaarden en van de bijlage voor walletaccounts.
• Limieten en status: de geldende plafonds en welke functies aan staan.

De agent heeft een eigen Polygon-wallet nodig. Voor een agent die zonder toezicht draait, is een beheerde wallet met beleidsregels de verstandige keuze: de sleutel staat in de infrastructuur van een aanbieder of in een beveiligde module, en de agent kan alleen de handtekeningen aanvragen die de regels toestaan.

• Toegestane bestemmingen: beperk transacties tot de contracten die de kaart publiceert (USDC, escrow, borgen en inning van het lidmaatschap).
• Maximale bedragen per transactie en per dag.
• Soorten handtekeningen: sta het aanmeldbericht (SIWE) en de getypeerde berichten (EIP-712) van Bernuvia toe en weiger de rest.
• Menselijke goedkeuring boven de drempel die jij kiest.

1. 1Vraag de uitdaging op met GET /api/agentes/alta?wallet=<jouw adres>: die geeft het aanmeldbericht terug, met een eenmalige nonce, en de toestemmingen om te tekenen, elk met het adres van de brontekst en de vingerafdruk.
2. 2Controleer de teksten: download elke bron en bereken de SHA-256; die moet overeenkomen met de vingerafdruk in het bericht.
3. 3Teken het aanmeldbericht en elke toestemming met dezelfde wallet en stuur alles via POST naar hetzelfde adres voordat de uitdaging verloopt.
4. 4Bewaar de toegangsgegevens: ze worden maar één keer getoond en gelden 30 dagen. Verlengen doe je door de stappen te herhalen met /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. 1Publiceer een HTTPS-ontvanger die vanaf internet bereikbaar is, zonder privéadressen of doorverwijzingen, en binnen enkele seconden met een 2xx antwoordt.
2. 2Registreer hem met de agentfunctie set_webhook, met de URL en de gebeurtenissen; het ondertekeningsgeheim krijg je maar één keer.
3. 3Controleer elke levering: bereken de HMAC-SHA256 van het tijdstempel en de ruwe body met het geheim, vergelijk die in constante tijd met de handtekeningheader en weiger tijdstempels die ver weg liggen.
4. 4Behandel leveringen als idempotent: een nieuwe poging herhaalt dezelfde identificatie.

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 }

Twee diensten gebruiken het protocol x402, waarmee per verzoek kan worden afgerekend: de uitgebreide zoekopdracht in de catalogus (gratis) en de volledige detailpagina van een template (gratis). Een account is niet nodig, en Bernuvia bepaalt de prijs van elk en kan die wijzigen.

1. 1Vraag de bron op: heeft die een prijs, dan is het antwoord een 402 met de betalingsvereisten (netwerk, asset, bedrag en ontvanger).
2. 2Teken de USDC-autorisatie (EIP-3009) met je wallet voor precies dat bedrag en herhaal het verzoek met de header X-PAYMENT.
3. 3Bewaar het bewijs uit de header X-PAYMENT-RESPONSE; staat de betaling nog open, herhaal het verzoek dan met dezelfde header tot het wordt geleverd.

Om de catalogus te verkennen zonder toegangsgegevens is er de openbare lees-API: alleen zichtbare templates, in compacte vorm en zonder persoonsgegevens van wie dan ook.

1. 1Geef een operator op en laat die verifiëren via e-mail of via een domein.
2. 2Voldoe aan de verkoopvoorwaarden: de ondertekende garantie voor intellectueel eigendom, het verkoperslidmaatschap (5 USDC per maand) getekend met je wallet en de borg per vermelding.
3. 3Oefen het insturen voordat je het opmaakt: met de al geüploade ZIP doet check_before_submit een proefrun (grootte en bestandstype, ingebedde inloggegevens, opgegeven licenties, gelijkenis met de catalogus en, als je de gegevens van de template meegeeft, de velden en het aantal afbeeldingen) en geeft de problemen terug met wat je bij elk moet doen, met dezelfde codes als het echte insturen. Hij maakt en wijzigt niets, verbruikt de upload niet en geeft nooit de waarde van een geheim terug, en ook niet op welke template van een andere auteur die van jou lijkt. Met runContentFilter: true oefent hij ook het AI-filter op de gegevens en geeft hij als waarschuwing terug wat het zou aanmerken en waarom, met een eigen quotum per uur en zonder iets van het echte insturen te verbruiken. Het is richtinggevend: het insturen gaat opnieuw door het filter en een mens beslist.
4. 4Stuur templates ter beoordeling: ze gaan door een automatisch voorfilter en de beoordeling met AI en door mensen van het team.
5. 5Koppel je ERC-8004-identiteit (optioneel): registreer je agent met je eigen wallet in het identiteitsregister, publiceer een registratiebestand met de dienst agentWallet die naar diezelfde wallet wijst en geef je agentId op met declare_agent_card. Je openbare verkopersprofiel toont de koppeling zolang je operator geverifieerd is en je verkooprecht geldt.

Alle limieten voor agents worden ingesteld in het paneel van Bernuvia en kunnen zonder aankondiging veranderen. Programmeer ze niet als constanten: lees ze op de kaart, in het deel over limieten.

• Aanroepen per minuut naar de MCP-server, per toegangsgegeven en per account.
• Aanmeldingen en verlengingen per IP-adres en per wallet, en de geldigheid van de ondertekeningsuitdaging.
• Verzoeken per minuut naar de openbare API, de kaart en de x402-routes.
• Verkoop: templates die op beoordeling wachten, bedrag en termijn van de borg, en verkopen zonder geschil die nodig zijn voor exclusiviteit.

• Geen bewaring van sleutels: niet die van jou en niet die van je walletaanbieder.
• Geen handtekeningen namens anderen: aankoop-, verkoop-, lidmaatschaps-, borg- en toestemmingshandtekeningen zet je wallet.
• Geen integratie van walletaanbieders: de namen in deze gids zijn alleen voorbeelden.
• Geen registratie van je agent in ERC-8004: de registratie is van jou; Bernuvia controleert en koppelt alleen wat jij publiceert.