Portefeuilles d'agent

Un portefeuille d’agent (agent wallet) permet à un agent IA ou à un service automatisé d’envoyer des versements sans votre clé marchand. Vous l’approvisionnez avec une partie de votre solde, et vous donnez à l’agent une clé de portefeuille (ak_test_… ou ak_live_…) qui peut uniquement :

• lire son propre portefeuille et son solde, et
• créer des versements dans le cadre d’une politique fixe : un seul prestataire, un montant maximal par versement, un maximum journalier facultatif (max_daily_amount, compté par jour calendaire à l’heure de Dakar) et une liste autorisée de numéros de bénéficiaires (1 à 20).

Le solde approvisionné du portefeuille est la limite totale de dépenses de l’agent. Il ne peut jamais toucher au reste de votre solde.

Vous (clé marchand)	L’agent (clé de portefeuille)
POST /v1/agent-wallets — créer avec une politique (Idempotency-Key obligatoire)	GET /v1/agent/wallet — sa politique
POST /v1/agent-wallets/{id}/fund · …/reclaim — approvisionner / reprendre l’argent non réservé	GET /v1/agent/balance
POST /v1/agent-wallets/{id}/keys — émettre une clé (affichée une seule fois)	POST /v1/agent/payouts — verser dans le cadre de la politique
POST /v1/agent-wallets/{id}/disable — bloquer les nouvelles écritures de l’agent	GET /v1/agent/payouts · …/{id}
GET /v1/agent-wallets/{id}/payouts · …/transfers · …/keys

Nouvelles tentatives sûres : action_id

Chaque versement d’agent porte un action_id fourni par votre application (par exemple l’identifiant de la tâche approuvée), et non inventé par le modèle. Xaalis associe un seul versement à chaque action_id du portefeuille : un appel d’outil relancé renvoie donc le versement d’origine au lieu de payer deux fois. Réutiliser un action_id avec un montant ou un bénéficiaire différent renvoie 409.

Validation par le propriétaire au-delà des limites (mode test)

Des limites serrées sont plus sûres, mais l’agent est alors bloqué au premier versement inhabituel. Avec la validation par le propriétaire, un versement au-delà des plafonds souples du portefeuille attend une personne au lieu d’échouer :

• Règle (clé marchand ou tableau de bord) : approval_above_limit: true et approval_max_amount — un plafond ferme, au moins égal à max_payout_amount. Désactivé par défaut ; portefeuilles de test uniquement pour l’instant.
• Un versement d’agent par ailleurs valide, au-delà du plafond par versement ou du total du jour, répond 202 avec un agent_payout_approval (apr_…, status: "pending", 30 minutes). Rien n’est réservé pendant l’attente. Un destinataire hors liste, un autre prestataire ou un montant au-delà de approval_max_amount échoue toujours ; un portefeuille garde au plus 20 demandes en attente (422 limit_exceeded).
• L’agent interroge GET /v1/agent/approvals/{id} : pending → approved (avec payout_id), declined ou expired. Il ne voit jamais de lien PIN ni le numéro complet.
• Le propriétaire décide dans le tableau de bord ou sur WhatsApp, et confirme une validation avec son code PIN sur une page Xaalis — jamais dans une discussion ni un outil. La page montre le numéro complet, le montant et les frais. Valider admet le versement, ce n’est pas un succès : lisez le status du versement lui-même.

Nouvelles tentatives : gardez le même action_id et le même Idempotency-Key. Une nouvelle tentative renvoie la même demande tant qu’elle est en attente, refusée ou expirée — élargir les plafonds n’y change rien — puis l’unique versement une fois validé. Cette tentative répond 201 avec le versement même si sa réservation a échoué ensuite (status: "failed", failure_reason) : vérifiez-le et ne relancez pas une nouvelle action automatiquement. Un nouvel action_id est une nouvelle demande au propriétaire.

SDK : agent.payouts.request(…) / requestForAction(…) renvoient un Payout ou un AgentPayoutApproval ; interrogez agent.approvals.retrieve(id). Les anciennes create / createForAction renvoient toujours un Payout et lèvent XaalisApprovalRequiredError (avec .approval) quand une validation est nécessaire. Une réponse illisible à une écriture lève XaalisProtocolError avec outcomeUnknown: true : réessayez avec la même action, ou interrogez la demande connue.

Portefeuilles de production : créés par une personne

En production, seul un propriétaire connecté du compte marchand peut créer un portefeuille, modifier sa politique, l’approvisionner ou reprendre son solde, et émettre sa clé ak_live_ — depuis le tableau de bord marchand, jamais avec une clé d’API. Un agent qui détient votre clé sk_live_ (ou toute autre clé d’API) ne peut donc pas se créer ni s’approvisionner un portefeuille. Vos clés d’API de production peuvent toujours lire les portefeuilles et désactiver un portefeuille ou révoquer sa clé : arrêter un agent tient toujours en un appel.

Le propriétaire peut à tout moment relever ou abaisser les plafonds par versement et par jour, ou remplacer la liste des bénéficiaires ; le versement suivant est vérifié avec la nouvelle politique.

Limites de cette version

• Les versements d’agent en production ne prennent en charge que les portefeuilles Wave pour l’instant (les versements Orange Money ne sont pas encore disponibles).
• Une clé d’agent de production n’est acceptée qu’en HTTPS.
• Désactiver un portefeuille bloque les nouvelles écritures de l’agent ; les versements déjà acceptés vont tout de même jusqu’au bout.

Le SDK TypeScript inclut des fonctions pour les portefeuilles d’agent (xaalis.agentWallets pour vous, un client d’agent avec payouts.createForAction pour l’agent), avec un exemple de gestionnaire d’outil.