Integración de pagos de LangChain.
Agrega pagos en USDC a cualquier agente de LangChain. El paquete real de Python le proporciona herramientas de billetera - enviar, liquidar y leer - en unas pocas líneas.
Blockchain0x incluye un paquete Python real, , que le da a un agente de LangChain herramientas nativas de wallet: enviar USDC en Base, liquidar una factura con prueba on-chain y leer wallets y transacciones. Instálalo, configura , llama a y entrega las herramientas a tu agente. ¿En TypeScript? No hay adapter de npm - envuelve el cliente x402 en una herramienta de LangChain.js.
Una capa delgada sobre la API HTTP de Blockchain0x.
Cada herramienta en blockchain0x-langchain es un delgado envoltorio sobre el SDK central oficial de blockchain0x. No hay lógica REST o x402 reimplementada, no hay custodia de claves: el adaptador reenvía tu clave API al backend y no retiene ningún secreto propio. create_blockchain0x_toolset(client) entrega a LangChain cinco herramientas: enviar un pago, liquidar una factura, leer una billetera, listar billeteras, leer una transacción - cada una ya tipada y delimitada.
Todavía puedes llamar a la API RAW o al SDK central directamente si lo prefieres. El adaptador es el camino de menor resistencia; la API es el contrato. Fija blockchain0x-langchain al rango langchain-core que soporta en lugar de perseguir lo último de ambos.
Una instalación. Una variable de entorno. Listo.
El paquete necesita Python 3.9 o superior. Incluye el SDK central de blockchain0x y langchain-core como dependencias; nada más que agregar.
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY es una clave sk_test_ testnet o sk_live_ mainnet de tu panel de control de Blockchain0x. Esa es la única variable que necesita el adaptador; reenvía la clave al backend y no guarda ningún secreto propio. Para el manejador de webhook que se muestra a continuación, también debes establecer BLOCKCHAIN0X_WEBHOOK_SECRET, que el panel de control devuelve una vez cuando creas o rotas un webhook.
Un agente de LangChain funcional con soporte de pago.
A continuación se presenta un agente completo de LangChain en Python. create_blockchain0x_toolset devuelve las herramientas de billetera, create_react_agent las conecta en un bucle ReAct, y el modelo elige la herramienta correcta del prompt. Establece BLOCKCHAIN0X_API_KEY, ejecútalo, y el agente puede mover y leer USDC en 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.
Qué sucede después de que el usuario paga.
La URL de webhook de tu agente (establecida en el panel de Blockchain0x) recibe un POST cuando un pago se liquida. El ayudante de verificación de webhook está en el SDK de Node, por lo que este manejador es TypeScript aunque tu agente sea Python. A continuación se muestra un manejador de Express que verifica la firma y ejecuta el trabajo pagado. Usa el mismo patrón en cualquier 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 realiza HMAC-SHA256 en tiempo constante y devuelve una unión discriminada, por lo que usted se ramifica en result.ok sin try/catch y lee result.eventType. Lea el cuerpo sin procesar, no una copia analizada: analizar y luego re-serializar rompe la firma. Los eventos enviados son payment.received, payment.sent, wallet.deployed y webhook.test; un cargo entrante a su agente es payment.received.
No hay adaptador de npm LangChain. Aquí está la receta honesta.
El adaptador LangChain enviado es solo para Python. No hay adaptador LangChain en npm. Para un agente LangChain o LangGraph en TypeScript, envuelves el cliente x402 real en una herramienta LangChain.js tú mismo. Son unas pocas líneas, y es exactamente lo que haría un adaptador dedicado bajo el capó.
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() }), }, );
El código y los ejemplos de testnet se encuentran en el repositorio del SDK de Python; la matriz de soporte del SDK está en la documentación. El ejemplo de Python envía una transferencia real de $0.01 USDC en Base Sepolia a través de la misma acción de enviar pago que envuelve la herramienta LangChain.
Cinco cosas que afectan en la primera integración.
Estos provienen de nuestra bandeja de entrada de soporte. Ninguno de ellos es un factor decisivo, pero conocerlos de antemano ahorra una hora de confusión cada uno.
Las cantidades son unidades base de USDC, como cadenas
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.
La herramienta de factura liquida, no crea
blockchain0x_settle_invoice liquida una solicitud de pago EXISTENTE con prueba en la cadena. No hay herramienta que genere una nueva factura o un enlace de pago alojado: las solicitudes de pago se crean en el panel, y el SDK principal expone solo la liquidación. Si esperaba que el agente generara un enlace pagadero sobre la marcha, esa no es la forma. Cree la solicitud fuera de banda, luego deje que el agente la liquide.
Verificar webhooks contra el cuerpo sin procesar
Los webhooks envían POST a tu URL, y cualquiera que aprenda esa URL puede enviar basura. Ejecuta webhooks.verify desde @blockchain0x/node sobre los bytes de la solicitud RAW antes de confiar en un evento. Analiza el JSON primero y el HMAC no coincidirá, porque la firma cubre los bytes exactos que llegaron. Es HMAC-SHA256 con una ventana de repetición de 300 segundos. Omitirlo es el error de producción más común.
send_payment puede responder 503 temprano
payments.create, que envuelve blockchain0x_send_payment, no reintenta por defecto y puede devolver 503 hasta que el adaptador de cadena esté conectado a su red. No deje que el LLM golpee la herramienta en un bucle de reintento en un error: quema tokens y ensucia su registro de intenciones. Confíe en la clave de idempotencia incorporada, exponga la falla y siga adelante.
Coincide con la versión de langchain-core
blockchain0x-langchain 0.1.x apunta a langchain-core >=0.2,<0.4. Si estás en un núcleo más nuevo que el que soporta el adaptador, fija el par que coincida en lugar de perseguir el último de ambos. La matriz de soporte está en la documentación.