What the wallet tool is

A LangChain wallet tool is a single reusable tool that gives an agent the ability to pay. Under the hood it wraps the x402 client, so when the agent calls the tool with a target, the tool fetches it, settles any 402 in USDC on Base, and returns the result. The agent gets a wallet the way it gets any capability in LangChain: as a tool in its tools list.

There is no Blockchain0x LangChain package to install. The wallet tool is a pattern you build from @blockchain0x/node and @blockchain0x/x402, which keeps it honest and on the verified surface. This page is the focused artifact; for the broader integration overview see langchain-payment-integration, and for the task walkthrough see how-to-add-payments-to-langchain-agent. The payment API product page is the reference.

What it exposes to the agent

Keep the tool's surface small and clear, because the agent reasons about it from its description. The core operation is pay-by-calling: give the tool a URL (and optionally a method and body) and it returns the response, having settled any payment along the way. That single operation covers the common case, an agent paying for data, an API, or another agent's service.

You can extend the same tool with a read operation so the agent can see its own budget, the spend limit enforced on its wallet, which lets a planner avoid attempting a call it cannot afford. Beyond pay and read-limit, resist adding more; the wallet tool is most useful when it does one obvious thing. The wallet's spend limit, set in the dashboard, is what bounds whatever the tool does, so the tool itself does not need to enforce budgets. A common temptation is to add a "send payment to address X" operation; think hard before you do, because an open-ended send tool is a much larger attack surface than a pay-for-what-you-call tool, and the pay-by-calling shape is enough for almost every agent use case. Keep the tool to what the agent genuinely needs and let the wallet limit be the backstop.

Build the tool

The whole tool is a DynamicStructuredTool wrapping fetchWithPay.

import { DynamicStructuredTool } from "@langchain/core/tools";
import { createClient } from "@blockchain0x/node";
import { createX402Client } from "@blockchain0x/x402/client";
import { z } from "zod";

const sdk = createClient({ apiKey: process.env.B0X_API_KEY! });
const fetchWithPay = createX402Client({ sdk });

export const walletTool = new DynamicStructuredTool({
  name: "pay_and_fetch",
  description: "Fetch a URL, paying in USDC if it requires payment. Returns the response body.",
  schema: z.object({ url: z.string(), method: z.string().optional(), body: z.string().optional() }),
  func: async ({ url, method, body }) => {
    const res = await fetchWithPay(url, { method: method ?? "GET", body });
    return res.ok ? await res.text() : `Request failed with status ${res.status}.`;
  },
});

Add it to any agent with tools: [walletTool, /* ... */]. That is the wallet tool: one definition, reusable across agents, and the only payment code in your stack.

Add a balance-aware read

To let the agent reason about budget, add a second tool that reads the spend limit. It is a plain GET, so it stays simple:

export const limitTool = new DynamicStructuredTool({
  name: "check_spend_limit",
  description: "Return this agent's current spend limit (per-transaction cap and period allowance).",
  schema: z.object({}),
  func: async () => {
    const res = await fetch(
      `https://api.blockchain0x.com/v1/agents/${process.env.AGENT_ID}/spend-permissions`,
      { headers: { Authorization: `Bearer ${process.env.B0X_API_KEY!}` } },
    );
    return await res.text(); // per_tx_wei, allowance_wei, period_seconds
  },
});

Give the planner both tools and it can check the limit before a large purchase. The limit is still enforced by the wallet regardless, so this read is for smarter planning, not for safety, the safety is the server-side cap.

Compatibility

Because the wallet tool is an ordinary DynamicStructuredTool, it works wherever LangChain tools work.

When to use it

Reach for the wallet tool when an agent needs to pay for things it calls and you want that capability packaged as one reusable unit rather than threaded through each tool. It is the right shape when several agents share the same paying behavior, since you build the tool once and add it everywhere, and when you want payment to be a first-class capability the planner can invoke deliberately.

It is the wrong shape when only one specific tool should ever pay, in which case wrap that tool's own fetch directly rather than giving the agent a general pay capability, and when the agent is purely internal with one trusted endpoint and a shared key, where a wallet adds nothing. Match the tool to whether paying is a general capability the agent should have or a one-off behavior of a single tool.

One wallet tool, many agents

The reusability is the point, so use it. In a multi-agent system, you do not write payment code per agent; you build the wallet tool once and add it to whichever agents should be able to pay. Each agent still has its own wallet and its own spend limit, so giving them the same tool does not pool their money; the tool is shared code, the wallets are separate accounts.

Bind each agent's tool to that agent's key so the right wallet pays. The cleanest pattern is a small factory that takes a key and returns a wallet tool bound to it:

export function makeWalletTool(apiKey: string) {
  const sdk = createClient({ apiKey });
  const fetchWithPay = createX402Client({ sdk });
  return new DynamicStructuredTool({
    name: "pay_and_fetch",
    description: "Fetch a URL, paying in USDC if required.",
    schema: z.object({ url: z.string() }),
    func: async ({ url }) => {
      const res = await fetchWithPay(url);
      return res.ok ? await res.text() : `Failed: ${res.status}`;
    },
  });
}

Now makeWalletTool(researcherKey) and makeWalletTool(writerKey) give two agents the same capability on their own wallets, with per-agent attribution and limits intact. Build the pattern once, reuse it across the fleet.

Pricing

The tool is free; you build it from open packages. What you pay is the wallet platform fee per agent on the pricing page: Free is $0 per agent per month at a 5% transaction fee, Pro is $9 at 2%, and Business is $29 at 1%. Per-agent pricing means you pay for the agents that actually transact through the tool, not a flat seat. Start on Free, read your real volume, and move the busiest agents to Pro when the math favors it.

What to ship today

Build the pay_and_fetch wallet tool around createX402Client, add it to an agent's tools, and make one paid call on Base Sepolia. Add the check_spend_limit read if the planner should reason about budget. For the full integration overview see langchain-payment-integration. Pricing is on the pricing page.