What the wallet tool is

A LlamaIndex wallet tool is a reusable FunctionTool that lets an agent pay for what it retrieves. The agent calls it with a target, the tool settles any 402 in USDC on Base, and the fetched data comes back as a tool result the agent reasons over. The agent gets a wallet the way it gets any capability in LlamaIndex: as a tool in its tools list, called when a task needs a paid source.

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

Build the tool

The wallet tool is a FunctionTool whose body pays. On Python LlamaIndex it calls the local Node proxy; on LlamaIndex.TS it calls createX402Client directly. Here is the Python form, since that is the common runtime for FunctionAgent.

import requests
from llama_index.core.tools import FunctionTool

def pay_and_fetch(url: str) -> str:
    """Fetch a URL, paying in USDC if it requires payment. Returns the body."""
    res = requests.post("http://127.0.0.1:8787", json={"url": url}, timeout=30)
    return res.text if res.status_code == 200 else f"Failed: {res.status_code}"

wallet_tool = FunctionTool.from_defaults(
    fn=pay_and_fetch,
    name="pay_and_fetch",
    description="Fetch a URL, paying in USDC if it requires payment. Returns the response body.",
)

Start the proxy (the thirty-line service from the walkthrough), add wallet_tool to a FunctionAgent, and the agent can pay. That is the wallet tool: one FunctionTool, reusable across agents.

The metadata is the interface

A LlamaIndex agent decides whether to call a tool from its metadata, the name and description you pass to FunctionTool, so that text is the real interface, not the function signature. Write it for the planner: say plainly that the tool fetches a URL and pays if the URL requires payment, and that it returns the body. That is usually enough for the agent to reach for it when a task needs a paid source and to leave it alone otherwise.

Decide deliberately whether to mention cost. If you want the agent to weigh price, note that calls may cost a small amount in USDC; if you would rather it not hesitate over routine sub-cent calls, leave cost out and let the wallet's spend limit be the control. Either is valid, but be intentional, because a vague description leaves the agent guessing about when the tool applies, while a precise one tells it exactly. The function body is small; the description is where you shape the agent's behavior, and in LlamaIndex that description is literally the metadata the planner reads.

A paid retriever

Here is the LlamaIndex-specific payoff. Because the wallet tool returns data, you can treat a paid source as just another thing the agent retrieves over. Point the tool at a paid API, and the data it fetches flows into the agent's context exactly like a retrieval from a local index, so the agent reasons over free and paid sources together without caring which is which.

This makes paid data a first-class part of a retrieval-augmented setup rather than a bolt-on. A FunctionAgent with both a local query engine and the wallet tool can answer from its index when the index suffices and pay for a fresh external source when it does not, deciding per query. The wallet tool is what turns "pay for data" into "retrieve from a paid source," which is the shape that fits LlamaIndex's retrieval-first design. Pair it with app-side caching so the same paid source is not fetched twice in one run, and the cost tracks genuinely new retrievals rather than repeated ones.

One tool per agent wallet

In a multi-agent setup, each agent should keep its own wallet. Bind each agent's tool to that agent's wallet with a small factory; on Python that means one proxy per agent on its own port, and the factory points the tool at the right port.

def make_wallet_tool(port: int) -> FunctionTool:
    def pay_and_fetch(url: str) -> str:
        res = requests.post(f"http://127.0.0.1:{port}", json={"url": url}, timeout=30)
        return res.text if res.status_code == 200 else f"Failed: {res.status_code}"
    return FunctionTool.from_defaults(fn=pay_and_fetch, name="pay_and_fetch",
        description="Fetch a URL, paying in USDC if required.")

researcher_tool = make_wallet_tool(8787)  # researcher's proxy/wallet
writer_tool = make_wallet_tool(8788)      # writer's proxy/wallet

Two agents, two proxies, two wallets, the same factory. The dashboard attributes spend per agent, and a compromised agent can only spend its own balance. Shared code, separate accounts.

Compatibility

Because the wallet tool is an ordinary FunctionTool, it works across LlamaIndex's surfaces.

When to use it

Reach for the wallet tool when a LlamaIndex agent needs to pay for sources it retrieves and you want that as one reusable unit rather than per-source glue. It fits when several agents share the same paying behavior, since you build the tool once and bind it per agent, and when paid data should sit alongside your free sources as something the agent draws on per query.

It is the wrong shape when only one specific source should ever cost money (wrap that source's own fetch through the proxy or client instead) or when every source is free and internal. Match the tool to whether paying for retrieval is a general capability the agent needs or a one-off behavior of a single source.

A concrete case makes the fit obvious. Imagine a research agent over a local document index that occasionally needs a current market figure no document holds. Give it the wallet tool, and it answers from the index when it can and pays a data API for the live figure when it must, choosing per query. Without the tool you would hardcode that one paid call; with it, paying for any external source is a capability the agent already has, and adding a second or third paid source later is just another URL it can reach.

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 its tool is billed on its own wallet, so a setup where only one agent pays for data only incurs fees for that one.

What to ship today

Build the pay_and_fetch FunctionTool (around the proxy on Python, around createX402Client on TS), add it to a FunctionAgent, and make one paid retrieval on Base Sepolia. Try pointing it at a paid API so the result feeds the agent's reasoning like any retrieval. For the broad integration overview see llamaindex-payment-integration. Pricing is on the pricing page.