LangChain-Zahlungsintegration.
Fügen Sie USDC-Zahlungen zu jedem LangChain-Agenten hinzu. Das echte Python-Paket bietet Wallet-Tools - senden, abwickeln und lesen - in wenigen Zeilen.
Blockchain0x liefert ein echtes Python-Paket, , das einem LangChain-Agenten native Wallet-Tools gibt: USDC auf Base senden, eine Rechnung mit On-Chain-Nachweis begleichen und Wallets sowie Transaktionen lesen. Installieren Sie es, setzen Sie , rufen Sie auf und geben Sie die Tools an Ihren Agenten weiter. Auf TypeScript? Es gibt keinen npm-Adapter - kapseln Sie den x402-Client in einem LangChain.js-Tool.
Eine dünne Schicht über der Blockchain0x HTTP API.
Jedes Tool in blockchain0x-langchain ist ein dünner Wrapper über das offizielle blockchain0x-Kern-SDK. Keine neu implementierte REST- oder x402-Logik, keine Schlüsselaufbewahrung: der Adapter leitet Ihren API-Schlüssel an das Backend weiter und hält kein eigenes Geheimnis. create_blockchain0x_toolset(client) übergibt LangChain fünf Tools - eine Zahlung senden, eine Rechnung begleichen, eine Wallet lesen, Wallets auflisten, eine Transaktion lesen - jedes bereits typisiert und eingestuft.
Sie können die rohe API oder das Kern-SDK direkt aufrufen, wenn Sie möchten. Der Adapter ist der Weg des geringsten Widerstands; die API ist der Vertrag. Fixieren Sie blockchain0x-langchain auf den unterstützten Bereich von langchain-core, anstatt den neuesten von beiden zu verfolgen.
Eine Installation. Eine Umgebungsvariable. Bereit.
Das Paket benötigt Python 3.9 oder neuer. Es zieht das Kern-blockchain0x SDK und langchain-core als Abhängigkeiten ein; nichts weiter hinzuzufügen.
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY ist ein sk_test_ Testnet- oder sk_live_ Mainnet-Schlüssel von Ihrem Blockchain0x-Dashboard. Das ist die einzige Variable, die der Adapter benötigt; er leitet den Schlüssel an das Backend weiter und hält kein eigenes Geheimnis. Für den unten gezeigten Webhook-Handler setzen Sie auch BLOCKCHAIN0X_WEBHOOK_SECRET, das das Dashboard einmal zurückgibt, wenn Sie einen Webhook erstellen oder rotieren.
Ein funktionierender LangChain-Agent mit Zahlungsunterstützung.
Unten ist ein vollständiger LangChain-Agent in Python. create_blockchain0x_toolset gibt die Wallet-Tools zurück, create_react_agent verbindet sie in eine ReAct-Schleife, und das Modell wählt das richtige Tool aus der Eingabeaufforderung aus. Setzen Sie BLOCKCHAIN0X_API_KEY, führen Sie es aus, und der Agent kann USDC auf Base bewegen und lesen.
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.
Was passiert, nachdem der Benutzer bezahlt hat.
Die Webhook-URL Ihres Agenten (im Blockchain0x-Dashboard festgelegt) erhält einen POST, wenn eine Zahlung abgeschlossen ist. Der Webhook-Überprüfungshelfer befindet sich im Node SDK, sodass dieser Handler TypeScript ist, auch wenn Ihr Agent Python ist. Unten finden Sie einen Express-Handler, der die Signatur überprüft und die bezahlte Arbeit ausführt. Verwenden Sie dasselbe Muster in jedem 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 führt HMAC-SHA256 in konstanter Zeit aus und gibt eine diskriminierte Vereinigung zurück, sodass Sie auf result.ok ohne try/catch verzweigen und result.eventType lesen. Lesen Sie den rohen Body, nicht eine geparste Kopie: das Parsen und anschließende Re-Serialisieren bricht die Signatur. Die gelieferten Ereignisse sind payment.received, payment.sent, wallet.deployed und webhook.test; eine eingehende Belastung Ihres Agenten ist payment.received.
Kein npm LangChain-Adapter. Hier ist das ehrliche Rezept.
Der gelieferte LangChain-Adapter ist nur für Python. Es gibt keinen LangChain-Adapter auf npm. Für einen TypeScript LangChain- oder LangGraph-Agenten wickeln Sie den echten x402-Client selbst in ein LangChain.js-Tool ein. Es sind nur ein paar Zeilen, und genau das würde ein dedizierter Adapter im Hintergrund tun.
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() }), }, );
Der Quell- und Testnet-Beispiele finden Sie in dem Python SDK-Repo; die SDK-Supportmatrix befindet sich in den Dokumenten. Das Python-Rauchbeispiel sendet eine echte $0,01 USDC-Überweisung auf Base Sepolia durch dieselbe send-payment-Aktion, die das LangChain-Tool umschließt.
Fünf Dinge, die bei der ersten Integration Probleme verursachen.
Diese stammen aus unserem Support-Posteingang. Keines davon ist ein Dealbreaker, aber im Voraus darüber Bescheid zu wissen, spart jeweils eine Stunde Kopfzerbrechen.
Beträge sind USDC-Basiseinheiten, 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.
Das Rechnungswerkzeug begleicht, es erstellt nicht
blockchain0x_settle_invoice begleicht eine EXISTIERENDE Zahlungsanforderung mit on-chain Nachweis. Es gibt kein Tool, das eine frische Rechnung oder einen gehosteten Checkout-Link erstellt: Zahlungsanforderungen werden im Dashboard erstellt, und das Kern-SDK bietet nur die Abwicklung an. Wenn Sie erwartet haben, dass der Agent einen zahlbaren Link in Echtzeit generiert, entspricht das nicht der Form. Erstellen Sie die Anfrage außerhalb der Bandbreite und lassen Sie den Agenten sie begleichen.
Überprüfen Sie Webhooks gegen den Rohkörper
Webhooks POST an Ihre URL, und jeder, der diese URL erfährt, kann Junk posten. Führen Sie webhooks.verify von @blockchain0x/node über die ROH-Anforderungsbytes aus, bevor Sie einem Ereignis vertrauen. Analysieren Sie zuerst das JSON, und das HMAC wird nicht übereinstimmen, da die Signatur die genauen Bytes abdeckt, die angekommen sind. Es ist HMAC-SHA256 mit einem 300-Sekunden-Wiederholfenster. Das Überspringen ist der häufigste Produktionsfehler.
send_payment kann frühzeitig 503 zurückgeben
payments.create, das blockchain0x_send_payment umschließt, versucht standardmäßig nicht erneut und kann 503 zurückgeben, bis der Chain-Adapter für Ihr Netzwerk konfiguriert ist. Lassen Sie nicht zu, dass das LLM das Tool in einer Wiederholschleife bei einem Fehler bearbeitet: es verbrennt Tokens und verwischt Ihr Absicht-Protokoll. Verlassen Sie sich auf den integrierten Idempotency-Key, zeigen Sie den Fehler an und machen Sie weiter.
Passen Sie die langchain-core-Version an
blockchain0x-langchain 0.1.x zielt auf langchain-core >=0.2,<0.4 ab. Wenn Sie auf einem neueren Kern sind, als der Adapter unterstützt, fixieren Sie das Paar, das übereinstimmt, anstatt den neuesten von beiden zu verfolgen. Die Supportmatrix befindet sich in den Dokumenten.