Tích hợp thanh toán LangChain.
Thêm thanh toán USDC vào bất kỳ đại lý LangChain nào. Gói Python thực cung cấp các công cụ ví - gửi, giải quyết và đọc - chỉ trong vài dòng.
Blockchain0x cung cấp một Python package thực, , mang lại cho agent LangChain các công cụ ví native: gửi USDC trên Base, thanh toán hóa đơn với bằng chứng on-chain, và đọc ví cùng giao dịch. Cài đặt nó, đặt , gọi , rồi chuyển các công cụ đó cho agent của bạn. Dùng TypeScript? Không có npm adapter - hãy bọc x402 client trong một tool của LangChain.js.
Một lớp mỏng trên API HTTP của Blockchain0x.
Mỗi công cụ trong blockchain0x-langchain là một bộ bọc mỏng trên SDK chính thức của blockchain0x. Không có logic REST hoặc x402 được triển khai lại, không có quyền sở hữu khóa: bộ điều hợp chuyển tiếp khóa API của bạn đến phía máy chủ và không giữ bí mật nào của riêng nó. create_blockchain0x_toolset(client) cung cấp cho LangChain năm công cụ - gửi một khoản thanh toán, thanh toán hóa đơn, đọc ví, liệt kê ví, đọc giao dịch - mỗi công cụ đã được gán kiểu và giới hạn.
Bạn vẫn có thể gọi raw API hoặc core SDK trực tiếp nếu muốn. Adapter là con đường ít trở ngại nhất; API mới là hợp đồng. Hãy ghim blockchain0x-langchain vào phạm vi langchain-core mà nó hỗ trợ thay vì chạy theo bản mới nhất của cả hai.
Một cài đặt. Một biến môi trường. Sẵn sàng.
Gói cần Python 3.9 hoặc mới hơn. Nó kéo vào SDK blockchain0x cốt lõi và langchain-core làm phụ thuộc; không cần thêm gì khác.
pip install blockchain0x-langchainexport BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
BLOCKCHAIN0X_API_KEY là một khóa sk_test_ testnet hoặc sk_live_ mainnet từ dashboard Blockchain0x của bạn. Đó là biến duy nhất mà adapter cần; nó chuyển tiếp khóa này tới backend và không giữ secret nào của riêng nó. Với webhook handler được hiển thị bên dưới, bạn cũng đặt BLOCKCHAIN0X_WEBHOOK_SECRET, giá trị này dashboard chỉ trả về một lần khi bạn tạo hoặc xoay vòng một webhook.
Một tác nhân LangChain hoạt động với hỗ trợ thanh toán.
Dưới đây là một đại lý LangChain hoàn chỉnh trong Python. create_blockchain0x_toolset trả về các công cụ ví, create_react_agent kết nối chúng vào một vòng lặp ReAct, và mô hình chọn công cụ phù hợp từ lời nhắc. Đặt BLOCKCHAIN0X_API_KEY, chạy nó, và đại lý có thể di chuyển và đọc USDC trên 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.
Điều gì xảy ra sau khi người dùng thanh toán.
Webhook URL của agent bạn (được đặt trong Blockchain0x dashboard) sẽ nhận một POST khi thanh toán được xác nhận. Hàm hỗ trợ verify webhook nằm trong Node SDK, nên handler này là TypeScript dù agent của bạn viết bằng Python. Bên dưới là một Express handler kiểm tra chữ ký và thực hiện phần việc trả phí. Hãy dùng cùng mẫu này trong bất kỳ HTTP framework nào.
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 thực hiện HMAC-SHA256 trong thời gian không đổi và trả về một liên minh phân biệt, vì vậy bạn phân nhánh trên result.ok mà không cần try/catch và đọc result.eventType. Đọc thân thô, không phải bản sao đã phân tích: phân tích rồi tái tuần tự hóa sẽ làm hỏng chữ ký. Các sự kiện được gửi là payment.received, payment.sent, wallet.deployed, và webhook.test; một khoản phí vào cho tác nhân của bạn là payment.received.
Không có bộ điều hợp npm LangChain. Đây là công thức trung thực.
Bộ chuyển đổi LangChain đã được gửi chỉ có trên Python. Không có bộ chuyển đổi LangChain trên npm. Đối với một tác nhân LangChain hoặc LangGraph TypeScript, bạn tự bọc khách hàng x402 thực tế trong một công cụ LangChain.js. Nó chỉ là vài dòng, và đó chính xác là những gì một bộ chuyển đổi chuyên dụng sẽ làm bên trong.
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() }), }, );
Mã nguồn và các ví dụ testnet nằm tại the Python SDK repo; ma trận hỗ trợ của SDK nằm tại the docs. Ví dụ smoke bằng Python gửi một giao dịch chuyển $0.01 USDC thật trên Base Sepolia thông qua cùng action send-payment mà tool của LangChain bọc lại.
Năm điều khiến bạn gặp khó khăn trong lần tích hợp đầu tiên.
Những điều này đến từ hộp thư hỗ trợ của chúng tôi. Không có điều nào trong số đó là điều kiện phá vỡ giao dịch, nhưng biết về chúng trước giúp tiết kiệm một giờ suy nghĩ mỗi điều.
Các số lượng là đơn vị cơ sở USDC, dưới dạng chuỗi
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.
Công cụ hóa đơn giải quyết, nó không tạo ra
blockchain0x_settle_invoice tất toán một payment request ĐÃ TỒN TẠI bằng bằng chứng on-chain. Không có tool nào để tạo một hóa đơn mới hoặc một hosted checkout link: payment request được tạo trong dashboard, và core SDK chỉ cung cấp chức năng tất toán. Nếu bạn kỳ vọng agent tự tạo một link thanh toán tức thời, thì không phải như vậy. Hãy tạo request bên ngoài trước, rồi để agent tất toán nó.
Xác minh các webhook với thân dữ liệu thô
Webhooks POST đến URL của bạn, và bất kỳ ai biết URL đó có thể POST rác. Chạy webhooks.verify từ @blockchain0x/node trên các byte yêu cầu RAW trước khi bạn tin tưởng một sự kiện. Phân tích JSON trước và HMAC sẽ không khớp, vì chữ ký bao phủ các byte chính xác đã đến. Nó là HMAC-SHA256 với một cửa sổ phát lại 300 giây. Bỏ qua nó là lỗi sản xuất phổ biến nhất.
send_payment có thể trả về 503 sớm
payments.create, mà blockchain0x_send_payment bọc lại, không tự động thử lại và có thể trả về 503 cho đến khi bộ chuyển đổi chuỗi được kết nối với mạng của bạn. Đừng để LLM đập công cụ trong một vòng lặp thử lại khi có lỗi: nó tiêu tốn token và làm mờ nhật ký ý định của bạn. Dựa vào khóa idempotency tích hợp, làm nổi bật sự thất bại, và tiếp tục.
Khớp phiên bản langchain-core
blockchain0x-langchain 0.1.x nhắm tới langchain-core >=0.2,<0.4. Nếu bạn đang dùng core mới hơn mức adapter hỗ trợ, hãy ghim cặp phiên bản khớp nhau thay vì chạy theo bản mới nhất của cả hai. Ma trận hỗ trợ nằm trong tài liệu.