API und Agenten

Alles, was du auf der Watchdog-Seite tust, geht auch unter /api/x402: Watches auflisten und anlegen, Signale und Routing ändern, Empfänger verwalten und Tests senden, den Alarm-Verlauf lesen und exportieren, Preise abfragen, Slots kaufen und Credits aufladen. Änderungen über die API erscheinen sofort in der App und umgekehrt.

Eine Maschine meldet sich mit der Wallet an, nicht mit einem Passwort. Der Ablauf hat fünf Schritte:

1. POST /api/x402/auth/challenge mit der Wallet-Adresse, den gewünschten Scopes und optional einem Namen für das Token.
2. Die Antwort enthält eine Anmeldenachricht im SIWE-Format (EIP-4361). Sie gilt 5 Minuten und nennt die angefragten Scopes.
3. Die Wallet signiert die Nachricht. Smart-Contract-Wallets mit EIP-1271 funktionieren auch.
4. POST /api/x402/auth/token mit Nachricht und Signatur.
5. Die Antwort enthält ein Token, das mit fbx_ beginnt, und seinen Ablauf, standardmäßig nach 24 Stunden. Die Maschine schickt es im Header Authorization: Bearer.

Das Token wird nur in dieser Antwort angezeigt. Bewahre es auf wie ein Passwort.

• read ist immer dabei: Watches, Empfänger, Alarme, Preise und das Konto lesen.
• write erlaubt Änderungen: Watches, Empfänger und Einstellungen anlegen und bearbeiten.
• spend erlaubt Aktionen, die Credits kosten, etwa Slots kaufen.

Beispiele: Ein Dashboard, das nur Alarme anzeigt, braucht read. Ein Bot, der Watches für neue Teammitglieder einrichtet, braucht read und write. Ein Agent, der zusätzlich selbstständig Slots kauft, braucht read, write und spend. Fehlt ein Scope, antwortet die API mit 403, dem Code insufficient_scope und dem benötigten Scope.

Alle Tokens deiner Wallet stehen unter Kontoeinstellungen → API-Zugang, mit Name, Erstelldatum, Ablauf und letzter Nutzung. Widerrufen stoppt ein Token sofort; das lässt sich nicht rückgängig machen. Eine Wallet kann höchstens 10 aktive Tokens gleichzeitig haben. Maschinen können ein Token selbst widerrufen, mit DELETE /api/x402/auth/tokens/{id}.

Anfragen, die etwas anlegen oder Credits kosten, brauchen den Header Idempotency-Key, einen Wert aus 8 bis 128 Buchstaben, Ziffern, _ oder -. Bricht die Verbindung ab, schickt die Maschine dieselbe Anfrage mit demselben Schlüssel erneut und bekommt das erste Ergebnis, statt doppelt zu bezahlen. Derselbe Schlüssel mit einer anderen Anfrage wird mit idempotency_key_reused abgelehnt.

Braucht eine Watch einen Slot oder reicht das Guthaben nicht, antwortet die API mit 402. Die Antwort enthält den Code slot_required oder insufficient_credits, einen fertigen Kaufvorschlag und den Endpunkt zum Aufladen. Ein Agent kann dann selbst entscheiden oder dich vorher fragen.

• OpenAPI-Beschreibung aller Operationen, mit Scopes und Fehlercodes.
• Webhook-Schema v2 für die Alarme, die dein Webhook empfängt.
• llms.txt als kurzer Einstieg für Sprachmodelle.
• API-Katalog nach RFC 9727.
• API-Dokumentation für Menschen, mit Code-Beispielen.

Ein Server für das Model Context Protocol, mit dem sich KI-Assistenten direkt verbinden können, ist geplant, aber noch nicht verfügbar. Bis dahin nutzen Agenten die oben beschriebene HTTP-API.