Integração de pagamento LangChain.
Adicione pagamentos USDC a qualquer agente LangChain. O pacote Python real oferece ferramentas de carteira - enviar, liquidar e ler - em algumas linhas.
A Blockchain0x disponibiliza um pacote Python real, , que dá a um agente LangChain ferramentas nativas de carteira: enviar USDC na Base, liquidar uma fatura com prova on-chain e ler carteiras e transações. Instale, defina , chame e entregue as ferramentas ao seu agente. Em TypeScript? Não há adaptador npm - envolva o cliente x402 em uma ferramenta do LangChain.js.
Uma camada fina sobre a API HTTP do Blockchain0x.
Cada ferramenta em blockchain0x-langchain é um wrapper fino sobre o SDK core oficial do blockchain0x. Sem lógica REST ou x402 reimplementada, sem custódia de chave: o adaptador encaminha sua chave de API para o backend e não mantém segredo algum. create_blockchain0x_toolset(client) fornece à LangChain cinco ferramentas - enviar um pagamento, liquidar uma fatura, ler uma carteira, listar carteiras, ler uma transação - cada uma já tipada e escopo.
Você ainda pode chamar a API bruta ou o SDK principal diretamente se preferir. O adaptador é o caminho de menor resistência; a API é o contrato. Fixe blockchain0x-langchain ao intervalo langchain-core que ele suporta em vez de perseguir o mais recente de ambos.
Uma instalação. Uma variável de ambiente. Pronto.
O pacote precisa do Python 3.9 ou mais recente. Ele puxa o SDK blockchain0x principal e langchain-core como dependências; nada mais a adicionar.
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY é uma chave sk_test_ de testnet ou sk_live_ de mainnet do seu painel Blockchain0x. Essa é a única variável que o adaptador precisa; ele encaminha a chave para o backend e não guarda nenhum segredo próprio. Para o handler de webhook mostrado abaixo, você também define BLOCKCHAIN0X_WEBHOOK_SECRET, que o painel retorna uma única vez quando você cria ou rota um webhook.
Um agente LangChain funcional com suporte a pagamentos.
Abaixo está um agente LangChain completo em Python. create_blockchain0x_toolset retorna as ferramentas de carteira, create_react_agent as conecta em um loop ReAct, e o modelo escolhe a ferramenta certa do prompt. Defina BLOCKCHAIN0X_API_KEY, execute-o, e o agente pode mover e ler USDC no 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.
O que acontece depois que o usuário paga.
A URL do webhook do seu agente (definida no painel do Blockchain0x) recebe um POST quando um pagamento é liquidado. O helper de verificação do webhook está no SDK do Node, então este manipulador é TypeScript, mesmo que seu agente seja Python. Abaixo está um manipulador Express que verifica a assinatura e executa o trabalho pago. Use o mesmo padrão em qualquer 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 faz HMAC-SHA256 em tempo constante e retorna uma união discriminada, então você ramifica em result.ok sem try/catch e lê result.eventType. Leia o corpo bruto, não uma cópia analisada: analisar e depois re-serializar quebra a assinatura. Os eventos enviados são payment.received, payment.sent, wallet.deployed e webhook.test; uma cobrança recebida para seu agente é payment.received.
Nenhum adaptador LangChain npm. Aqui está a receita honesta.
O adaptador LangChain enviado é apenas para Python. Não há adaptador LangChain no npm. Para um agente LangChain ou LangGraph em TypeScript, você envolve o cliente x402 real em uma ferramenta LangChain.js você mesmo. São algumas linhas, e é exatamente o que um adaptador dedicado faria nos bastidores.
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() }), }, );
O source e os exemplos de testnet estão no the Python SDK repo; a matriz de suporte do SDK está em the docs. O exemplo smoke em Python envia uma transferência real de $0.01 USDC na Base Sepolia pela mesma ação send-payment que a tool do LangChain encapsula.
Cinco coisas que prejudicam na primeira integração.
Estes vêm da nossa caixa de entrada de suporte. Nenhum deles é um fator decisivo, mas saber sobre eles com antecedência economiza uma hora de confusão cada.
Os valores são unidades base de USDC, como 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.
A ferramenta de fatura liquida, não cria
blockchain0x_settle_invoice liquida um pedido de pagamento EXISTENTE com prova on-chain. Não há ferramenta que crie uma nova fatura ou um link de checkout hospedado: os pedidos de pagamento são criados no painel, e o SDK principal expõe apenas a liquidação. Se você esperava que o agente gerasse um link pagável instantaneamente, essa não é a forma. Crie o pedido fora da banda, então deixe o agente liquidá-lo.
Verifique webhooks contra o corpo bruto
Webhooks POST para sua URL, e qualquer um que aprender essa URL pode POSTAR lixo. Execute webhooks.verify de @blockchain0x/node sobre os bytes da solicitação RAW antes de confiar em um evento. Analise o JSON primeiro e o HMAC não corresponderá, porque a assinatura cobre os bytes exatos que chegaram. É HMAC-SHA256 com uma janela de replay de 300 segundos. Ignorar isso é o erro mais comum em produção.
send_payment pode responder 503 logo no início
payments.create, que blockchain0x_send_payment envolve, não tenta novamente por padrão e pode retornar 503 até que o adaptador de cadeia esteja configurado para sua rede. Não deixe o LLM sobrecarregar a ferramenta em um loop de nova tentativa em caso de erro: isso consome tokens e confunde seu registro de intenções. Confie na chave de idempotência embutida, destaque a falha e siga em frente.
Combine a versão langchain-core
blockchain0x-langchain 0.1.x tem como alvo langchain-core >=0.2,<0.4. Se você estiver em um core mais novo do que o adapter suporta, fixe o par compatível em vez de tentar acompanhar a versão mais recente de ambos. A matriz de suporte está na documentação.