Integrazione dei pagamenti LangChain.
Aggiungi pagamenti USDC a qualsiasi agente LangChain. Il vero pacchetto Python fornisce strumenti per il portafoglio - invia, regola e leggi - in poche righe.
Blockchain0x distribuisce un vero package Python, , che offre a un agent LangChain strumenti wallet nativi: invia USDC su Base, salda una fattura con prova on-chain e legge wallet e transazioni. Installalo, imposta , invoca e passa gli strumenti al tuo agent. In TypeScript? Non esiste un adapter npm - incapsula il client x402 in uno strumento LangChain.js.
Uno strato sottile sopra l'API HTTP di Blockchain0x.
Ogni strumento in blockchain0x-langchain è un sottile wrapper sull'official blockchain0x core SDK. Nessuna logica REST o x402 re-implementata, nessuna custodia delle chiavi: l'adattatore inoltra la tua chiave API al backend e non detiene alcun segreto proprio. create_blockchain0x_toolset(client) fornisce a LangChain cinque strumenti - invia un pagamento, regola una fattura, leggi un portafoglio, elenca i portafogli, leggi una transazione - ognuno già tipizzato e scopo.
Puoi comunque chiamare l'API grezza o l'SDK core direttamente se preferisci. L'adattatore è il percorso di minor resistenza; l'API è il contratto. Fissa blockchain0x-langchain all'intervallo langchain-core che supporta piuttosto che inseguire l'ultima versione di entrambi.
Un'installazione. Una variabile d'ambiente. Pronto.
Il pacchetto richiede Python 3.9 o superiore. Include il core blockchain0x SDK e langchain-core come dipendenze; non c'è altro da aggiungere.
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY è una chiave sk_test_ per testnet o sk_live_ per mainnet dalla tua dashboard Blockchain0x. Questa è l'unica variabile di cui l'adapter ha bisogno; inoltra la chiave al backend e non conserva alcun secret proprio. Per il gestore webhook mostrato qui sotto devi impostare anche BLOCKCHAIN0X_WEBHOOK_SECRET, che la dashboard mostra una sola volta quando crei o ruoti un webhook.
Un agente LangChain funzionante con supporto ai pagamenti.
Di seguito è riportato un agente LangChain completo in Python. create_blockchain0x_toolset restituisce gli strumenti del portafoglio, create_react_agent li collega in un ciclo ReAct e il modello sceglie lo strumento giusto dal prompt. Imposta BLOCKCHAIN0X_API_KEY, eseguilo e l'agente può spostare e leggere USDC su 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.
Cosa succede dopo che l'utente paga.
L'URL del webhook del tuo agente (impostato nel dashboard di Blockchain0x) riceve un POST quando un pagamento si stabilizza. L'aiuto di verifica del webhook è nell'SDK Node, quindi questo gestore è TypeScript anche se il tuo agente è Python. Qui sotto c'è un gestore Express che controlla la firma e esegue il lavoro pagato. Usa lo stesso modello in qualsiasi 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 esegue HMAC-SHA256 in tempo costante e restituisce un'unione discriminata, quindi ramifichi su result.ok senza try/catch e leggi result.eventType. Leggi il corpo grezzo, non una copia analizzata: l'analisi e poi la re-serializzazione rompono la firma. Gli eventi inviati sono payment.received, payment.sent, wallet.deployed e webhook.test; un addebito in entrata al tuo agente è payment.received.
Nessun adattatore npm LangChain. Ecco la ricetta onesta.
L'adattatore LangChain fornito è solo Python. Non esiste un adattatore LangChain su npm. Per un agente LangChain o LangGraph in TypeScript, avvolgi tu stesso il vero client x402 in uno strumento LangChain.js. Sono poche righe, ed è esattamente ciò che farebbe un adattatore dedicato sotto il cofano.
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() }), }, );
Il sorgente e gli esempi per testnet sono nel the Python SDK repo; la matrice di supporto dell'SDK è in the docs. L'esempio smoke in Python invia un vero trasferimento di $0.01 USDC su Base Sepolia tramite la stessa azione send-payment che il tool LangChain incapsula.
Cinque cose che mordono alla prima integrazione.
Questi provengono dalla nostra casella di supporto. Nessuno di essi è un fattore decisivo, ma sapere in anticipo risparmia un'ora di confusione ciascuno.
Gli importi sono unità base USDC, come stringhe
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.
Lo strumento fattura si regola, non crea
blockchain0x_settle_invoice regola una richiesta di pagamento ESISTENTE con prova on-chain. Non esiste uno strumento che crea una fattura fresca o un link di checkout ospitato: le richieste di pagamento vengono create nel dashboard, e l'SDK core espone solo la regolazione. Se ti aspettavi che l'agente generasse un link pagabile al volo, quella non è la forma. Crea la richiesta al di fuori della banda, poi lascia che l'agente la regoli.
Verifica i webhook rispetto al corpo grezzo
I webhook POST al tuo URL, e chiunque apprenda quell'URL può POSTare spazzatura. Esegui webhooks.verify da @blockchain0x/node sui byte RAW della richiesta prima di fidarti di un evento. Analizza prima il JSON e l'HMAC non corrisponderà, perché la firma copre i byte esatti che sono arrivati. È HMAC-SHA256 con una finestra di replay di 300 secondi. Saltarlo è l'errore di produzione più comune.
send_payment può rispondere 503 all'inizio
payments.create, che avvolge blockchain0x_send_payment, non ripete per impostazione predefinita e può restituire 503 fino a quando l'adattatore della catena non è collegato alla tua rete. Non lasciare che il LLM martelli lo strumento in un ciclo di ripetizione su un errore: consuma token e confonde il tuo registro delle intenzioni. Fai affidamento sulla chiave di idempotenza integrata, evidenzia il fallimento e vai avanti.
Corrispondi alla versione di langchain-core
blockchain0x-langchain 0.1.x targetta langchain-core >=0.2,<0.4. Se usi una versione del core più recente di quella supportata dall'adapter, blocca la coppia corrispondente invece di inseguire l'ultima di entrambe. La matrice di supporto è nella documentazione.