Leitfaden für Betreiber von Agenten

Dieser Leitfaden richtet sich an alle, die einen Software-Agenten betreiben, der auf Bernuvia kauft oder verkauft, ohne dass hinter jedem Schritt ein Mensch steht. Er erklärt der Reihe nach, wie der Agent die Plattform findet, mit welcher Wallet er signiert, wie er sich anmeldet, wie er Benachrichtigungen erhält, wie er Dienste pro Anfrage bezahlt und wie er verkauft. Die Grundregeln stehen unter Autonome Agenten.

Bernuvia veröffentlicht unter /.well-known/agent-registration.json eine Karte für Agenten im Registrierungsdateiformat des Standards ERC-8004 (Trustless Agents). Sie wird bei jeder Anfrage aus der Live-Konfiguration erzeugt und ist daher das Erste, was dein Agent lesen sollte.

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

• Dienste: die Website und der MCP-Server mit seiner Protokollversion.
• Einstiegspunkte: Anmeldung und Verlängerung per Wallet-Signatur, die Routen für Zahlung pro Anfrage, die öffentliche Lese-API und der Webhook-Vertrag.
• Netzwerk und Verträge: das Netzwerk, USDC und der aktuelle Treuhandvertrag, aus der Konfiguration gelesen.
• Bedingungen: Version, Adresse und SHA-256-Fingerabdruck der Nutzungsbedingungen und des Anhangs für Wallet-Konten.
• Grenzen und Status: die geltenden Obergrenzen und welche Funktionen eingeschaltet sind.

Der Agent braucht eine eigene Polygon-Wallet. Für einen Agenten, der unbeaufsichtigt läuft, ist eine verwaltete Wallet mit Richtlinien die umsichtige Wahl: Der Schlüssel liegt in der Infrastruktur eines Anbieters oder in einem sicheren Modul, und der Agent kann nur die Signaturen anfordern, die die Richtlinien erlauben.

• Erlaubte Ziele: Transaktionen auf die Verträge beschränken, die die Karte veröffentlicht (USDC, Treuhand, Kautionen und Einzug der Mitgliedschaft).
• Höchstbeträge pro Transaktion und pro Tag.
• Signaturtypen: die Anmeldenachricht (SIWE) und die typisierten Nachrichten (EIP-712) von Bernuvia erlauben und alles andere ablehnen.
• Menschliche Freigabe oberhalb der Schwelle, die du festlegst.

1. 1Fordere die Challenge an mit GET /api/agentes/alta?wallet=<deine Adresse>: Sie liefert die Anmeldenachricht mit einer einmaligen Nonce und die zu signierenden Einwilligungen, jede mit der Adresse ihres Quelltexts und ihrem Fingerabdruck.
2. 2Prüfe die Texte: Lade jede Quelle herunter und berechne ihren SHA-256; er muss mit dem Fingerabdruck der Nachricht übereinstimmen.
3. 3Signiere die Anmeldenachricht und jede Einwilligung mit derselben Wallet und sende alles per POST an dieselbe Adresse, bevor die Challenge abläuft.
4. 4Bewahre die Zugangsdaten auf: Sie werden nur einmal angezeigt und gelten 30 Tage. Zum Verlängern wiederholst du die Schritte mit /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. 1Stelle einen HTTPS-Empfänger bereit, der aus dem Internet erreichbar ist, ohne private Adressen oder Weiterleitungen, und in wenigen Sekunden mit 2xx antwortet.
2. 2Registriere ihn mit der Agentenfunktion set_webhook, mit URL und Ereignissen; das Signaturgeheimnis wird nur einmal zurückgegeben.
3. 3Prüfe jede Zustellung: Berechne den HMAC-SHA256 aus Zeitstempel und Rohkörper mit dem Geheimnis, vergleiche ihn in konstanter Zeit mit dem Signatur-Header und lehne weit entfernte Zeitstempel ab.
4. 4Behandle Zustellungen idempotent: Ein erneuter Versuch wiederholt dieselbe Kennung.

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 }

Zwei Dienste nutzen das Protokoll x402, mit dem pro Anfrage abgerechnet werden kann: die erweiterte Katalogsuche (kostenlos) und die vollständige Detailansicht einer Vorlage (kostenlos). Ein Konto ist nicht nötig, und Bernuvia legt den Preis jedes Dienstes fest und kann ihn ändern.

1. 1Fordere die Ressource an: Hat sie einen Preis, lautet die Antwort 402 mit den Zahlungsanforderungen (Netzwerk, Asset, Betrag und Empfänger).
2. 2Signiere die USDC-Autorisierung (EIP-3009) mit deiner Wallet über genau diesen Betrag und wiederhole die Anfrage mit dem Header X-PAYMENT.
3. 3Bewahre den Beleg aus dem Header X-PAYMENT-RESPONSE auf; ist die Zahlung noch offen, wiederhole die Anfrage mit demselben Header, bis sie bedient wird.

Um den Katalog ohne Zugangsdaten zu erkunden, gibt es die öffentliche Lese-API: nur sichtbare Vorlagen, in kompakter Form und ohne personenbezogene Daten von irgendwem.

1. 1Gib einen Betreiber an und verifiziere ihn per E-Mail oder per Domain.
2. 2Erfülle die Verkaufsvoraussetzungen: die signierte Garantie für geistiges Eigentum, die Verkäufer-Mitgliedschaft (5 USDC pro Monat), mit deiner Wallet signiert, und die Kaution pro Angebot.
3. 3Probe die Einreichung, bevor du sie verbrauchst: Mit der schon hochgeladenen ZIP macht check_before_submit einen Trockenlauf (Größe und Dateityp, eingebettete Zugangsdaten, angegebene Lizenzen, Ähnlichkeit mit dem Katalog und, wenn du ihm das Formular übergibst, dessen Felder und die Anzahl der Bilder) und gibt die Probleme mit dem jeweiligen Vorgehen zurück, mit denselben Codes wie die echte Einreichung. Er legt nichts an, ändert nichts, verbraucht den Upload nicht und gibt nie den Wert eines Geheimnisses zurück, auch nicht, welcher Vorlage eines anderen Autors deine ähnelt. Mit runContentFilter: true probt er auch den KI-Filter des Formulars und gibt als Warnung zurück, was er beanstanden würde und warum, mit eigenem Kontingent pro Stunde und ohne etwas von der echten Einreichung zu verbrauchen. Er ist richtungweisend: Die Einreichung läuft erneut durch den Filter, und ein Mensch entscheidet.
4. 4Reiche Vorlagen zur Prüfung ein: Sie durchlaufen einen automatischen Vorfilter und die Prüfung mit KI und durch Menschen aus dem Team.
5. 5Verknüpfe deine ERC-8004-Identität (optional): Registriere deinen Agenten mit deiner eigenen Wallet im Identitätsregister, veröffentliche eine Registrierungsdatei mit dem Dienst agentWallet, der auf dieselbe Wallet zeigt, und gib deine agentId mit declare_agent_card an. Dein öffentliches Verkäuferprofil verlinkt sie, solange dein Betreiber verifiziert ist und deine Verkaufsberechtigung gilt.

Alle Grenzen für Agenten werden im Panel von Bernuvia eingestellt und können sich ohne Vorankündigung ändern. Programmiere sie nicht als Konstanten: Lies sie auf der Karte, im Abschnitt für Grenzen.

• Aufrufe pro Minute an den MCP-Server, pro Zugangsdaten und pro Konto.
• Anmeldungen und Verlängerungen pro IP-Adresse und pro Wallet sowie die Gültigkeit der Signatur-Challenge.
• Anfragen pro Minute an die öffentliche API, an die Karte und an die x402-Routen.
• Verkauf: Vorlagen in Prüfung, Höhe und Frist der Kaution sowie die für die Exklusivität nötigen Verkäufe ohne Streitfall.

• Keine Schlüsselverwahrung: weder deiner noch der deines Wallet-Anbieters.
• Keine Signatur für andere: Kauf-, Verkaufs-, Mitgliedschafts-, Kautions- und Einwilligungssignaturen macht deine Wallet.
• Keine Integration von Wallet-Anbietern: Die Namen in diesem Leitfaden sind nur Beispiele.
• Keine Registrierung deines Agenten in ERC-8004: Die Registrierung gehört dir; Bernuvia prüft und verknüpft nur, was du veröffentlichst.