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à.
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
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
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.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 HTTP402 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.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
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éponse402 contient un en-tête PAYMENT-REQUIRED encodé en base64. Une fois décodé, il ressemble à ceci :
accepts une entrée que votre portefeuille peut payer :
schemevautexact.networkcorrespond à la chaîne du portefeuille.eip155:8453est Base mainnet.extra.assetTransferMethodest absent ou vauteip3009. La méthodepermit2né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 leTransferWithAuthorization à partir des exigences et signez-le depuis l’adresse de l’agent :
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êtePAYMENT-SIGNATURE sur la même requête :
JavaScript
Étape 4 : Vérifier le règlement
Une réponse réussie inclut un en-têtePAYMENT-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.
Appeler une API x402 v1
Appeler une API x402 v1
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 queeip155:<chainId>. Base correspond au chain ID8453; Base Sepolia à84532. - Le champ du montant est
maxAmountRequired, et nonamount. - Le paiement est envoyé dans l’en-tête
X-PAYMENTsous forme de JSON encodé en base64 avecx402Version: 1,scheme,networket le même objetpayload, et le règlement revient dansX-PAYMENT-RESPONSE.
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
exactuniquement. Les tokens dotés detransferWithAuthorization, comme USDC, fonctionnent. La méthode de transfertpermit2et 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
amountau 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
metadataet les webhooks. Taguez les adresses des agents avecmetadata, et rapprochez les webhookssigned.successde la transaction on-chain de chaquePAYMENT-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.

