What the wallet tool is

A LangGraph wallet is a reusable tool that gives a graph the ability to pay. You place it in the graph's tool node, and when the model picks it, the graph routes there, runs it, and the tool settles any 402 in USDC on Base and returns the result. Because LangGraph builds on LangChain tools, the wallet tool is an ordinary LangChain tool; LangGraph just decides when the graph runs it.

There is no Blockchain0x LangGraph package. The wallet tool is a pattern you build from @blockchain0x/node and @blockchain0x/x402. This page is the focused artifact; for the broad integration overview, including modelling payment as a graph node, see langgraph-payments; the underlying LangChain tool is covered in langchain-wallet-tool. The payment API product page is the reference.

Build the tool for the ToolNode

The wallet tool wraps the x402 client (LangGraph.js) or the proxy (Python). Here is the LangGraph.js form, which calls the client directly.

import { DynamicStructuredTool } from "@langchain/core/tools";
import { ToolNode } from "@langchain/langgraph/prebuilt";
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 body.",
  schema: z.object({ url: z.string() }),
  func: async ({ url }) => {
    const res = await fetchWithPay(url);
    return res.ok ? await res.text() : `Failed: ${res.status}`;
  },
});

export const toolNode = new ToolNode([walletTool]);

Wire toolNode into your graph and the graph can pay. To the graph the wallet tool is just one of the tools in the node; the payment happens inside it, bounded by the wallet's spend limit. On Python, the tool body posts to a local proxy instead, and the rest is identical.

Load the limit into state

LangGraph's state is what makes a wallet feel native, so use it: load the agent's spend limit into state so nodes can plan around budget. Add a read tool (or a plain node) that does a GET to the spend-permissions endpoint and writes the result into state.

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
  },
});

With the limit in state, a check node can read it on a conditional edge and route away from a paid call the agent cannot afford, which is the graph-native budget pattern from langgraph-payments made concrete. The limit is enforced on chain regardless, so this read is for smarter routing, not safety; the spend limit is the safety.

Per-agent wallets in a multi-agent graph

A LangGraph app often runs several agents, sometimes as subgraphs, and each should keep its own wallet. Build the wallet tool with a factory so each agent's tool is bound to that agent's key, and give each its own tool node.

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}`;
    },
  });
}

Give the research subgraph makeWalletTool(researchKey) and the writer subgraph makeWalletTool(writerKey), each in its own ToolNode. The dashboard attributes spend per agent, and a compromised agent can only spend its own balance. Shared code, separate accounts, which is what a multi-agent graph wants. On Python, run one proxy per agent and point each tool at its port.

Reuse across graphs

The point of building the tool once is reuse, so reuse it. The same walletTool (or the factory) goes into any graph that needs to pay, dropped into that graph's tool node without rewriting payment logic. A library of graphs across your app can all import one wallet-tool module, so a change to how payment works happens in one place.

This matters as the number of graphs grows. Rather than each new graph reinventing a paid fetch, it imports the wallet tool and adds it to its node, and the behavior, error handling, and identifiers stay consistent everywhere. Treat the wallet tool as a shared building block, the same way you treat any common tool, and the cost of giving a new graph the ability to pay drops to one import and one entry in its tool node.

Compatibility

Because the wallet tool is an ordinary LangChain tool, it works across LangGraph's surfaces.

When to use it

Reach for the wallet tool when a graph needs to pay for what it calls and you want that capability as one reusable unit dropped into a tool node rather than per-graph glue. It fits when several graphs or several agents share the same paying behavior, since you build the tool once and reuse it, and when payment should be a deliberate tool the graph routes to.

It is the wrong shape when only one specific tool should ever pay (wrap that tool's own call instead) or when the graph is purely internal with no paid calls. Match it to whether paying is a general capability the graph needs or a one-off behavior of a single tool.

The strongest case is a long-running graph that makes many paid calls and must stay within a budget. There the wallet tool gives it the ability to pay, the check_spend_limit read gives it awareness of the cap, and the graph's own nodes give it the control to stop before overspending. That combination, capability plus awareness plus control, is exactly what LangGraph's explicit structure is good at, and it is why a wallet tool plus a budget node beats a flat agent for anything cost-sensitive.

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 each agent that transacts through the tool is billed on its own wallet, so a graph where only some agents pay only incurs fees for those agents.

What to ship today

Build pay_and_fetch (around createX402Client on LangGraph.js, around a proxy on Python), put it in a ToolNode, and make one paid call on Base Sepolia. Add check_spend_limit and load the limit into state if nodes should plan around budget. For multiple agents, use the factory. For the broad integration overview see langgraph-payments. Pricing is on the pricing page.