API et agents

Tout ce que vous faites sur la page Watchdog est aussi disponible sous /api/x402 : lister et créer des watches, modifier les signaux et le routage, gérer les destinataires et envoyer des tests, lire et exporter l’historique des alertes, obtenir les prix, acheter des slots et recharger des crédits. Les modifications faites via l’API apparaissent immédiatement dans l’application, et inversement.

Une machine se connecte avec le wallet, pas avec un mot de passe. Le processus comporte cinq étapes :

1. POST /api/x402/auth/challenge avec l’adresse du wallet, les scopes demandés et un nom facultatif pour le jeton.
2. La réponse contient un message de connexion au format SIWE (EIP-4361). Il est valable 5 minutes et liste les scopes demandés.
3. Le wallet signe le message. Les wallets de smart contract compatibles EIP-1271 fonctionnent aussi.
4. POST /api/x402/auth/token avec le message et la signature.
5. La réponse contient un jeton commençant par fbx_ et sa date d’expiration, 24 heures par défaut. La machine l’envoie dans l’en-tête Authorization: Bearer.

Le jeton n’est affiché que dans cette réponse. Conservez-le comme un mot de passe.

• read est toujours inclus : lecture des watches, des destinataires, des alertes, des prix et du compte.
• write autorise les modifications : création et modification de watches, de destinataires et de réglages.
• spend autorise les actions qui consomment des crédits, comme l’achat de slots.

Exemples : un tableau de bord qui affiche seulement les alertes a besoin de read. Un bot qui configure des watches pour les nouveaux membres de l’équipe a besoin de read et write. Un agent qui achète aussi des slots de lui-même a besoin de read, write et spend. S’il manque un scope, l’API répond 403 avec le code insufficient_scope et indique le scope requis.

Tous les jetons de votre wallet sont listés dans Paramètres du compte → Accès API, avec le nom, la date de création, l’expiration et la dernière utilisation. Révoquer arrête un jeton immédiatement ; c’est irréversible. Un wallet peut avoir au maximum 10 jetons actifs en même temps. Les machines peuvent révoquer elles-mêmes un jeton avec DELETE /api/x402/auth/tokens/{id}.

Les requêtes qui créent quelque chose ou coûtent des crédits nécessitent l’en-tête Idempotency-Key, une valeur de 8 à 128 lettres, chiffres, _ ou -. Si la connexion est interrompue, la machine renvoie la même requête avec la même clé et obtient le premier résultat, au lieu de payer deux fois. La même clé avec une requête différente est refusée avec idempotency_key_reused.

Si une watch nécessite un slot ou si le solde est insuffisant, l’API répond 402. La réponse contient le code slot_required ou insufficient_credits, une proposition d’achat prête à l’emploi et le point de terminaison pour recharger. Un agent peut alors décider seul, ou vous demander d’abord.

• Description OpenAPI de toutes les opérations, y compris les scopes et les codes d’erreur.
• Schéma du webhook v2 pour les alertes que reçoit votre webhook.
• llms.txt comme point d’entrée court pour les modèles de langage.
• Catalogue d’API selon la RFC 9727.
• Documentation API pour les humains, avec des exemples de code.

Un serveur pour le Model Context Protocol, auquel les assistants IA peuvent se connecter directement, est prévu mais pas encore disponible. D’ici là, les agents utilisent l’API HTTP décrite ci-dessus.