Skip to main content
En bref
Les agents IA peuvent payer des API et des données à la requête, en stablecoins, grâce à des protocoles ouverts de paiement par agents. Avec Blockradar, un agent paie depuis un portefeuille dont la clé privée ne quitte jamais Blockradar, en utilisant le point de terminaison de signature de données typées dont vous disposez déjà.

Protocoles pris en charge

Vous vendez plutôt aux agents ? Consultez Accepter des Paiements par Agents.

Prérequis

1

Clé API

Obtenez votre clé API depuis le Tableau de bord Blockradar. Naviguez vers Developers pour en générer une.
2

Portefeuille Principal EVM

Créez un portefeuille principal dans le tableau de bord sur la chaîne sur laquelle l’API facture, comme Base (voir Créer un Portefeuille Principal). Les paiements par agents via Blockradar sont réservés aux chaînes EVM.
3

USDC Activé

Activez USDC sur le portefeuille afin que les soldes et les dépôts soient suivis. Voir Gestion des Actifs.

Un budget dédié pour chaque agent

La signature n’a pas de plafond de dépense par paiement
Toute personne détenant une clé API ayant accès à un portefeuille peut signer un paiement de n’importe quel montant depuis ce portefeuille ou ses adresses. Blockradar ne plafonne pas ce qu’un agent signe. Limitez les dégâts que peuvent causer un agent défaillant ou une clé divulguée en attribuant à l’agent une adresse dédiée qui ne détient que ce qu’il est autorisé à dépenser.
Une adresse enfant avec l’auto-sweep désactivé constitue un bon budget pour un agent. Approvisionnez-la du montant que l’agent peut dépenser, et l’agent ne pourra jamais payer plus que ce solde.
Conservez disableAutoSweep: true sur l’adresse d’un agent. Avec l’auto-sweep activé, l’USDC que vous envoyez pour approvisionner l’agent est consolidé (sweep) vers le portefeuille principal, et les paiements de l’agent échouent faute de fonds.
Payer depuis le portefeuille principal fonctionne également. Utilisez les points de terminaison du portefeuille principal dans les exemples ci-dessous et omettez addressId. La totalité du solde du portefeuille principal est alors à la portée de l’agent : ne le faites donc qu’avec un portefeuille principal dédié à l’agent. Avec le Plan Checkout, les opérations sur les adresses enfants ne sont pas disponibles : utilisez un portefeuille principal dédié à l’agent.

Fonctionnement de x402

x402 est un protocole ouvert qui permet à une API de facturer à la requête : elle répond avec un HTTP 402 Payment Required, et l’appelant réessaie avec un paiement USDC signé. x402 implique trois parties : l’acheteur (votre agent), le vendeur (l’API payée) et un facilitateur qui vérifie le paiement et le soumet on-chain.
1

L'API demande un paiement

L’agent appelle un point de terminaison payant. L’API répond avec 402 Payment Required et un en-tête PAYMENT-REQUIRED listant ce qu’elle accepte : réseau, token, montant et adresse payTo.
2

Blockradar signe le paiement

L’agent transforme l’une de ces options en un TransferWithAuthorization EIP-3009 et le signe avec le point de terminaison de données typées de Blockradar. Rien n’est encore envoyé on-chain.
3

L'agent réessaie avec la signature

L’agent renvoie la requête avec le paiement signé dans l’en-tête PAYMENT-SIGNATURE.
4

Le facilitateur règle le paiement

Le facilitateur du vendeur vérifie la signature et soumet le transfert on-chain, en payant lui-même le gas. L’API renvoie la réponse, avec le résultat du règlement dans un en-tête PAYMENT-RESPONSE.
Le portefeuille de l’agent a besoin d’USDC mais pas de gas. La signature autorise un seul transfert d’un montant exact vers une adresse exacte, et le facilitateur ne peut modifier ni l’un ni l’autre.

Payer avec x402

Approvisionnez d’abord l’adresse de l’agent, comme décrit dans Un budget dédié pour chaque agent.

Option 1 : Utiliser le SDK client x402

Le client officiel @x402/fetch gère l’échange 402 pour vous. Il n’a besoin que d’un signataire doté d’une address et d’une méthode signTypedData. L’adaptateur ci-dessous implémente ce signataire sur le point de terminaison de données typées de Blockradar, de sorte que la clé reste dans Blockradar.
JavaScript
Enregistrez un schéma par réseau sur lequel l’agent paie (eip155:84532 pour Base Sepolia pendant les tests), avec un portefeuille sur cette chaîne derrière chacun.

Option 2 : Construire le paiement vous-même

Sans le SDK, ou dans un autre langage, un paiement nécessite trois appels HTTP : la première requête, l’appel de signature à Blockradar et la nouvelle tentative payée. Les étapes ci-dessous paient 0,01 USDC sur Base.

Étape 1 : Lire les exigences de paiement

Appelez l’API. Une réponse 402 contient un en-tête PAYMENT-REQUIRED encodé en base64. Une fois décodé, il ressemble à ceci :
Choisissez dans accepts une entrée que votre portefeuille peut payer :
  • scheme vaut exact.
  • network correspond à la chaîne du portefeuille. eip155:8453 est Base mainnet.
  • extra.assetTransferMethod est absent ou vaut eip3009. La méthode permit2 nécessite d’abord une approbation de token on-chain, qui coûte du gas ; ce guide ne la couvre donc pas.
amount est exprimé dans la plus petite unité du token. USDC a 6 décimales, donc 10000 correspond à 0,01 USDC.

Étape 2 : Signer l’autorisation

Construisez le TransferWithAuthorization à partir des exigences et signez-le depuis l’adresse de l’agent :
Pour signer depuis le portefeuille principal, utilisez plutôt POST /v1/wallets/{walletId}/signing/typed-data et définissez from sur l’adresse du portefeuille principal. La réponse est la réponse des données typées standard ; la signature se trouve dans data.signedTransaction.signature.

Étape 3 : Réessayer avec le paiement

Enveloppez la signature et l’autorisation dans un payload de paiement, encodez-le en base64 et envoyez-le dans l’en-tête PAYMENT-SIGNATURE sur la même requête :
JavaScript

Étape 4 : Vérifier le règlement

Une réponse réussie inclut un en-tête PAYMENT-RESPONSE encodé en base64 :
transaction est le hash on-chain du transfert USDC. Si le paiement échoue, l’API répond à nouveau 402, et PAYMENT-RESPONSE contient un errorReason tel que insufficient_funds.
Les serveurs en version 1 de x402 diffèrent du flux ci-dessus sur quatre points :
  • Les exigences de paiement se trouvent dans le corps de la réponse 402, et non dans un en-tête.
  • Les réseaux sont nommés (base, base-sepolia) plutôt que eip155:<chainId>. Base correspond au chain ID 8453 ; Base Sepolia à 84532.
  • Le champ du montant est maxAmountRequired, et non amount.
  • Le paiement est envoyé dans l’en-tête X-PAYMENT sous forme de JSON encodé en base64 avec x402Version: 1, scheme, network et le même objet payload, et le règlement revient dans X-PAYMENT-RESPONSE.
L’étape de signature avec Blockradar est identique.

Règles de signature qui piègent les intégrations

Chaque signature est enregistrée comme une transaction SIGNED et déclenche un webhook signed.success, ce qui vous fournit une piste d’audit de chaque paiement autorisé par votre agent. Une signature n’est pas un paiement : l’USDC ne bouge que lorsque le facilitateur du vendeur règle le paiement. Lorsque le vendeur est en dehors de Blockradar, le règlement apparaît comme un transfert sortant depuis l’adresse de l’agent. Pour rapprocher les paiements, comparez les webhooks signed.success à la transaction on-chain de l’en-tête PAYMENT-RESPONSE.

Limites de x402

  • EVM uniquement. Les paiements sont signés avec des données typées EIP-712, que Blockradar prend en charge uniquement sur les chaînes EVM. Solana et les autres réseaux x402 non EVM ne sont pas pris en charge.
  • Paiements EIP-3009 exact uniquement. Les tokens dotés de transferWithAuthorization, comme USDC, fonctionnent. La méthode de transfert permit2 et les autres schémas ne sont pas couverts.
  • Pas de nanopaiements Circle Gateway. L’option de paiements groupés inférieurs au centime de Circle n’a pas été testée avec les portefeuilles Blockradar.

Bonnes Pratiques

  • Appliquez des limites dans votre agent. Blockradar signe toute requête bien formée provenant d’une clé API valide. Placez des limites par paiement et par jour dans le code de votre agent, et plafonnez l’exposition totale avec le solde de l’adresse de l’agent.
  • Une adresse par agent. Des budgets séparés permettent de voir clairement quel agent a dépensé quoi, et de couper un agent en vidant son adresse.
  • Vérifiez le prix avant de signer. Comparez amount au maximum que votre agent devrait payer pour cette ressource, et refusez tout montant supérieur.
  • Vérifiez le destinataire. Si votre agent ne paie que des API connues, tenez une liste autorisée d’adresses payTo.
  • Utilisez metadata et les webhooks. Taguez les adresses des agents avec metadata, et rapprochez les webhooks signed.success de la transaction on-chain de chaque PAYMENT-RESPONSE.
  • Verrouillez l’accès à l’API. N’acceptez les requêtes API que depuis vos propres serveurs grâce à la Liste Blanche IP, afin qu’une clé divulguée ne puisse pas être utilisée ailleurs.
  • Testez d’abord sur Base Sepolia. Utilisez un portefeuille testnet, eip155:84532, et de l’USDC testnet provenant des faucets avant de dépenser des fonds réels.

Référence API