LangChain支付集成。
将USDC支付添加到任何LangChain代理。真实的Python包为其提供钱包工具 - 发送、结算和读取 - 只需几行代码。
Blockchain0x 提供了一个真正的 Python 包，，它为 LangChain agent 提供原生钱包工具：在 Base 上发送 USDC、用链上证明结算发票，以及读取钱包和交易。安装它，设置 ，调用 ，然后把这些工具交给你的 agent。TypeScript 怎么办？没有 npm adapter - 把 x402 client 封装成一个 LangChain.js 工具即可。
在Blockchain0x HTTP API之上有一层薄薄的层。
blockchain0x-langchain 中的每个工具都是对官方 blockchain0x 核心 SDK 的薄包装。没有重新实现的 REST 或 x402 逻辑，没有密钥保管：适配器将您的 API 密钥转发到后端，并不持有自己的密钥。create_blockchain0x_toolset(client) 为 LangChain 提供五个工具 - 发送支付、结算发票、读取钱包、列出钱包、读取交易 - 每个工具都已类型化和范围限定。
如果您愿意，您仍然可以直接调用原始 API 或核心 SDK。适配器是最简单的路径；API 是合同。将 blockchain0x-langchain 固定到它支持的 langchain-core 范围，而不是追逐两者的最新版本。
一次安装。一个环境变量。准备好了。
该包需要 Python 3.9 或更高版本。它将核心 blockchain0x SDK 和 langchain-core 作为依赖项；无需添加其他内容。
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY 是你 Blockchain0x dashboard 中的 sk_test_ testnet 或 sk_live_ mainnet key。那是 adapter 唯一需要的变量；它只会把 key 转发到后端，本身不保存任何 secret。下面展示的 webhook handler 还需要设置 BLOCKCHAIN0X_WEBHOOK_SECRET，该值会在你创建或轮换 webhook 时由 dashboard 仅返回一次。
一个支持支付的工作LangChain代理。
以下是一个完整的Python中的LangChain代理。create_blockchain0x_toolset返回钱包工具，create_react_agent将它们连接到ReAct循环中，模型从提示中选择正确的工具。设置BLOCKCHAIN0X_API_KEY，运行它，代理可以在Base上移动和读取USDC。
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.
用户支付后发生什么。
您的代理的 webhook URL（在 Blockchain0x 仪表板中设置）在支付结算时接收 POST。webhook 验证助手在 Node SDK 中，因此该处理程序是 TypeScript，即使您的代理是 Python。下面是一个 Express 处理程序，它检查签名并运行已支付的工作。在任何 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 以恒定时间执行 HMAC-SHA256，并返回一个区分的联合，因此您可以在 result.ok 上分支，而无需 try/catch，并读取 result.eventType。读取原始主体，而不是解析的副本：解析然后重新序列化会破坏签名。发货的事件包括 payment.received、payment.sent、wallet.deployed 和 webhook.test；对您的代理的入站收费是 payment.received。
没有npm LangChain适配器。这是诚实的配方。
已发布的 LangChain 适配器仅限于 Python。npm 上没有 LangChain 适配器。对于 TypeScript LangChain 或 LangGraph 代理，您自己将真实的 x402 客户端包装在 LangChain.js 工具中。这只有几行代码，正是专用适配器在底层所做的。
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() }), }, );
源代码和 testnet 示例位于 the Python SDK repo；SDK support matrix 位于 the docs。Python smoke 示例会在 Base Sepolia 上通过 LangChain tool 封装的同一个 send-payment action 发送一笔真实的 $0.01 USDC transfer。
五个在首次集成时会造成困扰的事情。
这些来自我们的支持收件箱。它们都不是交易破坏者，但提前知道它们每个都能节省一个小时的困惑时间。
金额是USDC基本单位，以字符串形式表示
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.
发票工具结算，而不是创建
blockchain0x_settle_invoice 结算一个现有的支付请求，并提供链上证明。没有工具可以生成新的发票或托管结账链接：支付请求是在仪表板中创建的，核心 SDK 仅公开结算。如果您期望代理动态生成可支付链接，那不是这种形状。创建请求后，让代理结算。
根据原始主体验证 webhook
Webhook POST 到您的 URL，任何了解该 URL 的人都可以 POST 垃圾。信任事件之前，请在原始请求字节上运行 @blockchain0x/node 的 webhooks.verify。首先解析 JSON，HMAC 将不匹配，因为签名覆盖了到达的确切字节。它是 HMAC-SHA256，具有 300 秒的重放窗口。跳过它是最常见的生产失误。
send_payment 可能会提前返回 503
payments.create，blockchain0x_send_payment 封装的内容，默认不重试，并且在链适配器连接到您的网络之前可能返回 503。不要让 LLM 在错误上对工具进行重试循环：这会消耗令牌并混淆您的意图日志。依靠内置的幂等性密钥，表面化失败，继续前进。
匹配langchain-core版本
blockchain0x-langchain 0.1.x 面向 langchain-core >=0.2,<0.4。如果你使用的 core 比 adapter 支持的版本更高，不要盲目追最新，而是固定与之匹配的组合。support matrix 见 docs。