LangChain支払い統合。
任意のLangChainエージェントにUSDC支払いを追加します。実際のPythonパッケージは、数行で送信、決済、読み取りのウォレットツールを提供します。
Blockchain0x は実用的な Python パッケージ を提供しており、LangChain エージェントにネイティブのウォレットツールを付与します: Base 上で USDC を送信し、オンチェーン証明付きで請求書を決済し、ウォレットと取引を読み取れます。インストールして を設定し、 を呼び出して、そのツールをエージェントに渡してください。TypeScript ではどうするか? npm アダプターはありません - x402 クライアントを LangChain.js のツールでラップしてください。
Blockchain0x HTTP APIの上に1つの薄いレイヤー。
blockchain0x-langchainのすべてのツールは、公式のblockchain0xコアSDKの薄いラッパーです。再実装されたRESTやx402ロジックはなく、キーの保管もありません：アダプタはあなたのAPIキーをバックエンドに転送し、独自の秘密は保持しません。create_blockchain0x_toolset(client)はLangChainに5つのツールを提供します - 支払いを送信、請求書を精算、ウォレットを読み取り、ウォレットをリストし、トランザクションを読み取ります - それぞれがすでに型付けされ、スコープが設定されています。
好みであれば、RAW APIまたはコアSDKを直接呼び出すこともできます。アダプターは最も抵抗が少ないパスです。APIは契約です。両方の最新を追い求めるのではなく、blockchain0x-langchainをサポートするlangchain-core範囲に固定してください。
1つのインストール。1つの環境変数。準備完了。
このパッケージはPython 3.9以降が必要です。core 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 キーです。adapter が必要とするのはこの変数だけで、キーを backend に転送するだけであり、adapter 自身は秘密情報を保持しません。下に示す webhook handler では、webhook を作成またはローテーションしたときに dashboard が 1 回だけ返す BLOCKCHAIN0X_WEBHOOK_SECRET も設定します。
支払いサポート付きの動作する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を実行し、識別されたユニオンを返します。したがって、try/catchなしでresult.okに分岐し、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 の対応表は the docs にあります。Python の smoke example は、LangChain tool がラップしているのと同じ send-payment action を使って、Base Sepolia 上で実際の $0.01 USDC transfer を送信します。
初回の統合で問題を引き起こす5つのこと。
これらは私たちのサポート受信箱からのものです。どれも取引を破るものではありませんが、事前に知っていると、各々1時間の頭を悩ませることを節約します。
金額は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を確認します。
WebhooksはあなたのURLにPOSTし、そのURLを知っている誰でもジャンクをPOSTできます。イベントを信頼する前に、RAWリクエストバイトに対して@blockchain0x/nodeからwebhooks.verifyを実行します。最初にJSONを解析すると、HMACは一致しません。なぜなら、署名は到着した正確なバイトをカバーするからです。これは300秒のリプレイウィンドウを持つHMAC-SHA256です。これをスキップすることは、最も一般的なプロダクションミスです。
send_paymentは早期に503を返すことがあります
payments.createは、blockchain0x_send_paymentでラップされており、デフォルトでは再試行せず、チェーンアダプターがネットワークに接続されるまで503を返すことがあります。エラー時にLLMがツールを再試行ループで叩かせないでください：トークンを消費し、意図のログを混乱させます。組み込みの冪等性キーに依存し、失敗を明らかにし、次に進んでください。
langchain-coreのバージョンを一致させる
blockchain0x-langchain 0.1.x は langchain-core >=0.2,<0.4 を対象にしています。adapter が対応しているより新しい core を使っている場合は、両方の最新を追うのではなく、対応する組み合わせを固定してください。support matrix は docs にあります。