LangChain betalingsintegratie.
Voeg USDC-betalingen toe aan elke LangChain-agent. Het echte Python-pakket geeft het portemonnee-tools - verzenden, afhandelen en lezen - in een paar regels.
Blockchain0x levert een echt Python-pakket, , dat een LangChain-agent native wallet tools geeft: USDC versturen op Base, een factuur afwikkelen met on-chain bewijs, en wallets en transacties lezen. Installeer het, stel in, roep aan, en geef de tools aan je agent. Op TypeScript? Er is geen npm-adapter - wrap de x402-client in een LangChain.js-tool.
Één dunne laag bovenop de Blockchain0x HTTP API.
Elke tool in blockchain0x-langchain is een dunne wrapper over de officiële blockchain0x core SDK. Geen opnieuw geïmplementeerde REST of x402 logica, geen sleutelbewaring: de adapter stuurt je API-sleutel door naar de backend en houdt geen geheim van zichzelf. create_blockchain0x_toolset(client) geeft LangChain vijf tools - stuur een betaling, vereffen een factuur, lees een wallet, lijst wallets, lees een transactie - elk al getypt en gescopeerd.
Je kunt de ruwe API of de kern SDK nog steeds rechtstreeks aanroepen als je dat wilt. De adapter is het pad van de minste weerstand; de API is het contract. Pin blockchain0x-langchain aan de langchain-core-reeks die het ondersteunt in plaats van de nieuwste van beide na te jagen.
Eén installatie. Eén omgevingsvariabele. Klaar.
Het pakket heeft Python 3.9 of nieuwer nodig. Het haalt de kern blockchain0x SDK en langchain-core als afhankelijkheden binnen; verder niets toe te voegen.
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY is een sk_test_ testnet- of sk_live_ mainnet-sleutel uit je Blockchain0x-dashboard. Dat is de enige variabele die de adapter nodig heeft; hij stuurt de sleutel door naar de backend en bewaart zelf geen geheim. Voor de webhook-handler die hieronder wordt getoond stel je ook BLOCKCHAIN0X_WEBHOOK_SECRET in, die het dashboard één keer teruggeeft wanneer je een webhook aanmaakt of roteert.
Een werkende LangChain-agent met betalingsondersteuning.
Hieronder is een complete LangChain-agent in Python. create_blockchain0x_toolset retourneert de portemonnee-tools, create_react_agent verbindt ze in een ReAct-lus, en het model kiest het juiste hulpmiddel uit de prompt. Stel BLOCKCHAIN0X_API_KEY in, voer het uit, en de agent kan USDC verplaatsen en lezen op 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.
Wat er gebeurt nadat de gebruiker betaalt.
De webhook-URL van je agent (ingevoerd in het Blockchain0x-dashboard) ontvangt een POST wanneer een betaling wordt afgehandeld. De webhook-verifiehelper bevindt zich in de Node SDK, dus deze handler is TypeScript, ook al is je agent Python. Hieronder staat een Express-handler die de handtekening controleert en het betaalde werk uitvoert. Gebruik hetzelfde patroon in elk HTTP-framework.
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 doet HMAC-SHA256 in constante tijd en retourneert een gediscrimineerde unie, zodat je takken op result.ok zonder try/catch en leest result.eventType. Lees het ruwe lichaam, niet een geparsed exemplaar: parseren en dan opnieuw serialiseren breekt de handtekening. De verzonden gebeurtenissen zijn payment.received, payment.sent, wallet.deployed, en webhook.test; een inkomende kosten voor je agent is payment.received.
Geen npm LangChain-adapter. Hier is het eerlijke recept.
De verzonden LangChain-adapter is alleen Python. Er is geen LangChain-adapter op npm. Voor een TypeScript LangChain of LangGraph-agent wikkel je de echte x402-client zelf in een LangChain.js-tool. Het zijn een paar regels, en het is precies wat een speciale adapter onder de motorkap zou doen.
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() }), }, );
De broncode en de testnet-voorbeelden staan in de Python SDK repo; de SDK support matrix staat in de docs. Het Python smoke example verstuurt een echte $0.01 USDC transfer op Base Sepolia via dezelfde send-payment action die de LangChain tool omhult.
Vijf dingen die pijn doen bij de eerste integratie.
Deze komen uit onze ondersteuningsinbox. Geen van hen zijn deal-breakers, maar er van tevoren over weten bespaart elk een uur van hoofdschudden.
Bedragen zijn USDC basis eenheden, als strings
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.
De factuurtool vereffent, het creëert niet
blockchain0x_settle_invoice vereffent een BESTAAND betalingsverzoek met on-chain bewijs. Er is geen tool die een verse factuur of een gehoste checkout-link mint: betalingsverzoeken worden in het dashboard gemaakt, en de kern SDK stelt alleen vereffening beschikbaar. Als je verwachtte dat de agent een betaalbare link on-the-fly genereert, is dat niet de vorm. Maak het verzoek buiten band, laat de agent het dan vereffenen.
Verifieer webhooks tegen de ruwe body
Webhooks POST naar je URL, en iedereen die die URL leert kan junk POSTen. Voer webhooks.verify uit van @blockchain0x/node over de RAW-aanroepbytes voordat je een gebeurtenis vertrouwt. Parse eerst de JSON en de HMAC zal niet overeenkomen, omdat de handtekening de exacte bytes dekt die zijn aangekomen. Het is HMAC-SHA256 met een replay-venster van 300 seconden. Het overslaan ervan is de meest voorkomende productiefout.
send_payment kan vroeg 503 beantwoorden
payments.create, dat blockchain0x_send_payment omhult, probeert standaard niet opnieuw en kan 503 retourneren totdat de chain adapter is aangesloten op jouw netwerk. Laat de LLM de tool niet in een herhaal lus op een fout hameren: het verbrandt tokens en verstoort je intentie log. Leun op de ingebouwde idempotency key, breng de fout aan het licht, ga verder.
Stem de langchain-core versie af
blockchain0x-langchain 0.1.x richt zich op langchain-core >=0.2,<0.4. Als je een nieuwere core gebruikt dan de adapter ondersteunt, pin dan het paar dat overeenkomt in plaats van achter de nieuwste van allebei aan te jagen. De supportmatrix staat in de docs.