Intégration de paiement LangChain.
Ajoutez des paiements USDC à n'importe quel agent LangChain. Le véritable package Python lui donne des outils de portefeuille - envoyer, régler et lire - en quelques lignes.
Blockchain0x fournit un vrai package Python, , qui donne à un agent LangChain des outils natifs de portefeuille : envoyer des USDC sur Base, régler une facture avec une preuve on-chain, et lire les portefeuilles et les transactions. Installez-le, définissez , appelez , et transmettez les outils à votre agent. En TypeScript ? Il n'existe pas d'adaptateur npm - enveloppez le client x402 dans un outil LangChain.js.
Une fine couche au-dessus de l'API HTTP de Blockchain0x.
Chaque outil dans blockchain0x-langchain est une fine enveloppe autour du SDK principal officiel de blockchain0x. Pas de logique REST ou x402 réimplémentée, pas de garde de clé : l'adaptateur transmet votre clé API au backend et ne détient aucun secret propre. create_blockchain0x_toolset(client) fournit à LangChain cinq outils - envoyer un paiement, régler une facture, lire un portefeuille, lister des portefeuilles, lire une transaction - chacun déjà typé et limité.
Vous pouvez toujours appeler l'API brute ou le SDK principal directement si vous le souhaitez. L'adaptateur est le chemin de moindre résistance ; l'API est le contrat. Fixez blockchain0x-langchain à la plage langchain-core qu'il prend en charge plutôt que de poursuivre les dernières versions des deux.
Une installation. Une variable d'environnement. Prêt.
Le paquet nécessite Python 3.9 ou une version plus récente. Il intègre le SDK blockchain0x de base et langchain-core comme dépendances ; rien d'autre à ajouter.
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY est une clé sk_test_ testnet ou sk_live_ mainnet de votre tableau de bord Blockchain0x. C'est la seule variable dont l'adaptateur a besoin ; il transmet la clé au backend et ne conserve aucun secret. Pour le gestionnaire de webhook montré ci-dessous, vous devez également définir BLOCKCHAIN0X_WEBHOOK_SECRET, que le tableau de bord renvoie une fois lorsque vous créez ou faites tourner un webhook.
Un agent LangChain fonctionnel avec support de paiement.
Voici un agent LangChain complet en Python. create_blockchain0x_toolset retourne les outils de portefeuille, create_react_agent les intègre dans une boucle ReAct, et le modèle choisit le bon outil à partir de l'invite. Définissez BLOCKCHAIN0X_API_KEY, exécutez-le, et l'agent peut déplacer et lire USDC sur Base.
from blockchain0x import Client from blockchain0x_langchain import create_blockchain0x_toolset from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent client = Client() # reads BLOCKCHAIN0X_API_KEY from the environment tools = create_blockchain0x_toolset(client) llm = ChatOpenAI(model="gpt-4o") agent = create_react_agent(llm, tools) result = agent.invoke({ "messages": [{ "role": "user", "content": "Pay 0.01 USDC from my agent to 0xRecipient for the dataset.", }], })
Run it with the prompt above and the model picks the send-payment tool, the SDK submits the transfer on Base, and you get a transaction hash back. amount_wei is USDC base units (6 decimals), so 0.01 USDC is the string "10000". A sk_test_ key keeps you on Base Sepolia until you switch to sk_live_. Heads up: payments.create can answer 503 until the chain adapter is wired for your network.
Que se passe-t-il après que l'utilisateur a payé.
L'URL du webhook de votre agent (définie dans le tableau de bord Blockchain0x) reçoit un POST lorsque le paiement est réglé. L'assistant de vérification du webhook se trouve dans le SDK Node, donc ce gestionnaire est en TypeScript même si votre agent est en Python. Ci-dessous se trouve un gestionnaire Express qui vérifie la signature et exécute le travail payé. Utilisez le même modèle dans n'importe quel framework HTTP.
import express from "express"; import { webhooks } from "@blockchain0x/node"; const app = express(); // Capture the RAW body. The HMAC is over the exact bytes on the wire. app.use(express.raw({ type: "application/json" })); app.post("/webhooks/payment", (req, res) => { const result = webhooks.verify({ headers: req.headers, rawBody: req.body, // Buffer, raw bytes secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!, }); if (!result.ok) return res.status(400).json({ code: result.code }); if (result.eventType === "payment.received") { // USDC landed in your agent wallet - do the paid work } res.status(200).send("ok"); });
webhooks.verify effectue HMAC-SHA256 en temps constant et renvoie une union discriminée, donc vous branchez sur result.ok sans try/catch et lisez result.eventType. Lisez le corps brut, pas une copie analysée : l'analyse puis la re-sérialisation casse la signature. Les événements expédiés sont payment.received, payment.sent, wallet.deployed, et webhook.test ; une charge entrante pour votre agent est payment.received.
Aucun adaptateur npm LangChain. Voici la recette honnête.
L'adaptateur LangChain expédié est uniquement en Python. Il n'y a pas d'adaptateur LangChain sur npm. Pour un agent LangChain ou LangGraph en TypeScript, vous enveloppez le véritable client x402 dans un outil LangChain.js vous-même. C'est quelques lignes, et c'est exactement ce qu'un adaptateur dédié ferait en coulisses.
import { createClient } from "@blockchain0x/node"; import { createX402Client } from "@blockchain0x/x402/client"; import { tool } from "@langchain/core/tools"; import { z } from "zod"; const sdk = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! }); const fetchWithPay = createX402Client({ sdk }); // There is no npm LangChain adapter. Wrap the x402 client in a LangChain.js tool. export const payAndFetch = tool( async ({ url }) => (await fetchWithPay(url)).text(), { name: "pay_and_fetch", description: "Fetch a URL, answering any x402 payment challenge automatically", schema: z.object({ url: z.string().url() }), }, );
La source et les exemples de testnet se trouvent dans le dépôt SDK Python; la matrice de support SDK se trouve dans la documentation. L'exemple de test Python envoie un transfert réel de $0.01 USDC sur Base Sepolia via la même action d'envoi de paiement que l'outil LangChain encapsule.
Cinq choses qui piquent lors de la première intégration.
Celles-ci proviennent de notre boîte de réception de support. Aucune d'entre elles n'est un obstacle, mais les connaître à l'avance permet d'économiser une heure de réflexion à chaque fois.
Les montants sont des unités de base USDC, sous forme de chaînes
The payment tools take amount_wei: a string of USDC base units, not a float and not a dollar figure. USDC has 6 decimals, so 0.01 USDC is "10000" and 5 USDC is "5000000". Always pass a string; large integers lose precision as JSON numbers. Send "5.00" and you will either get a validation error or move a millionth of what you meant.
L'outil de facture règle, il ne crée pas
blockchain0x_settle_invoice règle une demande de paiement EXISTANTE avec une preuve on-chain. Il n'y a pas d'outil qui génère une nouvelle facture ou un lien de paiement hébergé : les demandes de paiement sont créées dans le tableau de bord, et le SDK principal expose uniquement le règlement. Si vous vous attendiez à ce que l'agent génère un lien payable à la volée, ce n'est pas la forme. Créez la demande hors bande, puis laissez l'agent la régler.
Vérifiez les webhooks par rapport au corps brut
Les webhooks envoient des POST à votre URL, et quiconque apprend cette URL peut envoyer des déchets. Exécutez webhooks.verify depuis @blockchain0x/node sur les octets de la demande RAW avant de faire confiance à un événement. Analysez d'abord le JSON et le HMAC ne correspondra pas, car la signature couvre les octets exacts qui sont arrivés. C'est HMAC-SHA256 avec une fenêtre de répétition de 300 secondes. Le sauter est l'erreur de production la plus courante.
send_payment peut répondre 503 tôt
payments.create, que blockchain0x_send_payment enveloppe, ne réessaie pas par défaut et peut renvoyer 503 jusqu'à ce que l'adaptateur de chaîne soit câblé pour votre réseau. Ne laissez pas le LLM marteler l'outil dans une boucle de réessai en cas d'erreur : cela consomme des jetons et brouille votre journal d'intentions. Appuyez-vous sur la clé d'idempotence intégrée, exposez l'échec, passez à autre chose.
Faites correspondre la version langchain-core
blockchain0x-langchain 0.1.x cible langchain-core >=0.2,<0.4. Si vous êtes sur un noyau plus récent que celui que l'adaptateur prend en charge, fixez la paire qui correspond au lieu de poursuivre le dernier des deux. La matrice de support se trouve dans la documentation.