LangChain 결제 통합.
모든 LangChain 에이전트에 USDC 결제를 추가하십시오. 실제 Python 패키지는 지갑 도구를 제공합니다 - 전송, 정산 및 읽기 - 몇 줄로 가능합니다.
Blockchain0x는 실제 Python 패키지인 을 제공합니다. 이 패키지는 LangChain agent에 네이티브 지갑 도구를 제공해 Base에서 USDC를 보내고, 온체인 증명으로 인보이스를 정산하며, 지갑과 거래를 읽을 수 있게 합니다. 설치한 뒤 를 설정하고 를 호출해 agent에 도구를 넘기세요. TypeScript를 사용하나요? npm adapter는 없습니다 - x402 클라이언트를 LangChain.js tool로 감싸면 됩니다.
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 이상이 필요합니다. 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로 전달할 뿐 자체적으로는 어떤 비밀도 보관하지 않습니다. 아래에 표시된 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.
사용자가 결제한 후 발생하는 일.
귀하의 에이전트의 웹훅 URL(Blockchain0x 대시보드에서 설정)은 결제가 완료되면 POST를 수신합니다. 웹훅 검증 헬퍼는 Node SDK에 포함되어 있으므로, 이 핸들러는 귀하의 에이전트가 Python임에도 불구하고 TypeScript입니다. 아래는 서명을 확인하고 유료 작업을 실행하는 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() }), }, );
source와 testnet 예시는 the Python SDK repo에 있으며, SDK 지원 매트릭스는 the docs에 있습니다. Python smoke 예시는 LangChain tool이 감싸는 동일한 send-payment action을 통해 Base Sepolia에서 실제 $0.01 USDC 전송을 보냅니다.
첫 통합에서 문제를 일으키는 다섯 가지 사항.
이것들은 우리의 지원 인박스에서 나옵니다. 이들 중 어떤 것도 거래를 깨뜨리는 것은 아니지만, 미리 알면 각각 한 시간의 머리 긁는 시간을 절약합니다.
금액은 문자열로 된 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는 정산만 노출합니다. 에이전트가 즉시 결제 가능한 링크를 생성할 것으로 예상했다면, 그것은 그런 형태가 아닙니다. 요청을 별도로 생성한 다음 에이전트가 이를 정산하도록 하세요.
원시 본문에 대해 웹훅을 검증하십시오.
웹훅은 귀하의 URL에 POST하며, 그 URL을 아는 누구나 쓰레기를 POST할 수 있습니다. 이벤트를 신뢰하기 전에 @blockchain0x/node에서 RAW 요청 바이트에 대해 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를 사용 중이라면, 둘 다 최신으로 따라가지 말고 맞는 조합을 고정하세요. 지원 매트릭스는 docs에 있습니다.