LANGCHAIN INTEGRATION

LangChain payment integration.

Add USDC payments to any LangChain agent in 5 minutes. One tool, one environment variable, one line in your agent's tools list.

SHORT ANSWER

Blockchain0x provides a drop-in BlockchainOxPaymentTool for LangChain agents. It lets your agent request, verify, and confirm USDC payments on Base. Install @blockchain0x/langchain, set your API key, and add the tool to your agent's tool list. The agent can now request payment for any work it does. Payments land in your wallet. Webhooks confirm.

WHY THE WRAPPER EXISTS

One thin layer over the Blockchain0x HTTP API.

The Blockchain0x API is plain JSON over HTTPS - any LangChain agent could call it through the StructuredTool interface by hand. The wrapper exists because writing that integration by hand takes 30-60 minutes per agent, and we want it to take 60 seconds. BlockchainOxPaymentTool handles the boilerplate: idempotency key generation, request/response typing, retry behavior, error mapping into LangChain's exception system, and webhook signature verification utilities.

You can still use the raw API if you prefer. The wrapper is the path of least resistance; the API is the contract. The wrapper version updates every time the API ships a new endpoint or field; pin to a wrapper version that matches your LangChain version if you want predictable behavior.

INSTALLATION

Two commands. Two environment variables. Ready.

The package targets Node 18+ (LangChain's minimum) and ships with TypeScript types. No additional peer dependencies beyond what LangChain itself requires.

INSTALL

npm install @blockchain0x/langchain

ENVIRONMENT VARIABLES

export BLOCKCHAIN0X_API_KEY=sk_live_...
export BLOCKCHAIN0X_AGENT_ID=agt_abc123
export BLOCKCHAIN0X_SIGNING_SECRET=whsec_...

BLOCKCHAIN0X_API_KEY and BLOCKCHAIN0X_AGENT_ID come from the agent's settings page in the Blockchain0x dashboard after you create the agent. BLOCKCHAIN0X_SIGNING_SECRET comes from the webhook configuration; you only need it if you are handling webhooks in the same process (the typical pattern).

FULL AGENT EXAMPLE

A working LangChain agent with payment support.

Below is a complete LangChain ReAct agent that includes payment request capability. Drop this into your codebase, set your environment variables, and the agent can request payments from users for any work it produces. The tool itself handles the API call; your job is to wire it into your agent and handle the webhook on the other side.

AGENT.TS

import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { BlockchainOxPaymentTool } from "@blockchain0x/langchain";

const llm = new ChatOpenAI({ model: "gpt-4o" });
const paymentTool = new BlockchainOxPaymentTool({
  agentId: process.env.BLOCKCHAIN0X_AGENT_ID!,
  apiKey: process.env.BLOCKCHAIN0X_API_KEY!,
});

const agent = createReactAgent({
  llm,
  tools: [paymentTool, /* your other tools */],
});

const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "Write me a market analysis. Charge me $5 USDC for it.",
  }],
});

When you run this agent with the prompt above, the LLM decides to call BlockchainOxPaymentTool, the tool POSTs to /v1/payment-requests, returns the hosted_url to the LLM, and the LLM hands that URL back to the user. The user clicks the link, pays the $5 USDC on Base, and your webhook receives payment.confirmed within seconds. From your agent's perspective: one tool call, asynchronous webhook in.

WEBHOOK HANDLING

What happens after the user pays.

Your agent's webhook URL (set in the Blockchain0x dashboard) receives a POST when the chain confirms the payment. Below is an Express handler that verifies the signature and unlocks the paid work. Use the same pattern in any HTTP framework.

WEBHOOK-HANDLER.TS

import express from "express";
import { verifyWebhook } from "@blockchain0x/langchain";

const app = express();

app.post(
  "/webhooks/payment",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.header("X-Blockchain0x-Signature");
    if (!signature || !verifyWebhook(req.body, signature, process.env.BLOCKCHAIN0X_SIGNING_SECRET!)) {
      return res.status(401).send("Invalid signature");
    }
    const event = JSON.parse(req.body.toString());
    // event.type is "payment.received" | "payment.confirmed" | ...
    if (event.type === "payment.confirmed") {
      // Unlock the work this payment was for
      await deliverPaidWork(event.data.payment_request_id);
    }
    res.status(200).send("ok");
  },
);

The verifyWebhook helper does HMAC-SHA256 in constant time. Read the raw body, not a parsed JSON copy - parsing then re-serializing breaks the signature. The webhook fires up to 5 different event types (payment.requested, payment.received, payment.confirmed, payment.failed, agent.verified); most LangChain agents only need payment.confirmed and payment.failed.

STARTER REPOSITORY

Working example you can clone and run.

A complete LangChain agent + webhook server lives at the GitHub repository below. Clone it, set your env vars, run npm start. Hit the agent with a sample prompt and walk through the full payment lifecycle on Base mainnet (or Base Sepolia for testing).

github.com/blockchain0x/agent-wallet-langchain

The repository includes: minimal agent code (the example above), webhook handler with signature verification, test fixtures for Base Sepolia, a Dockerfile for one-command deploy, and a README walking through deployment to Fly.io, Railway, or Vercel functions.

COMMON PITFALLS

Five things that bite on first integration.

These come from our support inbox. None of them are deal-breakers, but knowing about them in advance saves an hour of head-scratching each.

PITFALL 1

Floating-point amounts

Always pass amounts as decimal strings ("5.00") not floats (5.0). JavaScript's IEEE 754 representation of 0.1 + 0.2 is 0.30000000000000004; if your LangChain tool decides to compute a fee on the fly and passes a float, you get a 422 from the API with an amount-mismatch error. The SDK validates this and throws before the HTTP call, but it is still the most common pitfall on first integration.

PITFALL 2

LangChain's tool-result truncation

LangChain's default tool wrapping truncates tool results above 4096 characters. The hosted_url our tool returns is well under that, but if you set verbose: true the entire payment_request payload becomes part of the tool result, sometimes pushing the LLM's context near limits. Pass returnRawTool: false (the SDK default) unless you specifically need the raw response in the LLM's context.

PITFALL 3

Forgetting webhook signature verification

The hosted pay page lives on our domain, but the webhook POSTs to your URL. Anyone with the URL can POST arbitrary payloads. Always verify the X-Blockchain0x-Signature header using HMAC-SHA256 with your signing secret before trusting the event. The SDK exports verifyWebhook for this; do not skip it. We see this miss on roughly 1 in 5 first integrations.

PITFALL 4

Not handling payment.failed

Your webhook handler probably has nice logic for payment.confirmed. It needs equivalent logic for payment.failed (request expired without payment, or the broadcast transaction reverted). Without it, you get hanging promises in your LangChain run and your agent waits forever. Default policy: log the failure, mark the run as failed, surface to the user.

PITFALL 5

Tool call retry loops on 422

If your agent's LLM decides to retry a payment request after a 422 (policy exceeded, idempotency conflict, etc.), it can loop indefinitely. The SDK's withRetryPolicy({maxAttempts: 1}) option disables the LLM-initiated retry; the SDK's own retry handles transient network errors at the HTTP layer with proper idempotency keys. Configure this from the start; it is the difference between an agent that quietly fails and one that burns LangChain tokens forever.

FREQUENTLY ASKED

Three LangChain-specific questions.

How do I receive USDC instead of asking for it?

Your LangChain agent passively receives USDC at the wallet address shown on its public profile page. The BlockchainOxPaymentTool is for active payment REQUESTS that your agent initiates (creating hosted_urls to hand to buyers). For passive receiving, no tool is needed; you just share your agent's public page URL or wallet address, buyers pay, and your webhook fires payment.confirmed as soon as the chain settles. Many LangChain agents use both patterns: passive page for general tips, active tool for charging per specific request.

Does this work with LangGraph?

Yes. The BlockchainOxPaymentTool works in any LangChain or LangGraph agent because it conforms to the standard LangChain tool interface (StructuredTool). In LangGraph specifically, you can attach the tool to any node that processes user messages, and it composes cleanly with checkpointing, interruption, and human-in-the-loop patterns. See the LangGraph integration page for graph-specific patterns. For most ReAct-style LangChain agents, the createReactAgent example above is the right starting point.

What chains are supported?

Base only at MVP, with native USDC issued by Circle. Solana support is planned for V2, Ethereum mainnet and Polygon for V3 by demand. The architecture uses chain adapters from day one, so adding new chains will not change this integration's API - the BlockchainOxPaymentTool stays the same shape; you can specify chain in the tool config when more chains turn on. For now, every payment is Base USDC; the SDK does not let you accidentally specify a different chain.

All integrations Pricing

Plug payments into your LangChain agent.

Five minutes from npm install to your first paid request. Pro at $9/agent/month.