Integrating x402 with LlamaIndex paid data, on demand.
LlamaIndex pipelines live or die on data quality. x402 lets an agent or query pipeline pull from premium, per-call-priced sources exactly when retrieval comes up short — paying cents, not committing to plans.
Most LlamaIndex applications retrieve from data you already have — your documents, your indexes, your vector store. The interesting gap appears at query time: the index doesn't cover the question, the data is stale, or the answer needs something external — a live lookup, a fresh document, an enrichment record. That's precisely where paid, per-call data sources earn their price.
x402 makes those sources usable from inside a pipeline. A priced endpoint answers with an HTTP 402, the client signs a USDC payment from the agent's wallet, the call retries and returns data. From LlamaIndex's side, it's just another tool that happened to cost $0.01.
Where paid sources fit in a pipeline
Think of x402 sources as the fallback tier of retrieval. Local indexes answer most queries at zero marginal cost; the paid source is what the agent reaches for when local confidence is low — fetching a document you never ingested, pulling current figures your snapshot lacks, or enriching an entity your corpus only mentions.
This ordering matters economically. A pipeline that pays for every query burns budget on questions the index already answers; a pipeline that can never pay gives wrong answers when the index runs out. Cheap first, paid on demand.
Wrap a paying call as a FunctionTool
The x402 Python SDK's httpx client handles the payment handshake inside an ordinary async function. Wrap it as a FunctionTool, hand it to an agent, and put the price in the description so the LLM treats it as the deliberate, costed choice it is.
import os
from eth_account import Account
from x402.clients.httpx import x402HttpxClient
from llama_index.core.tools import FunctionTool
from llama_index.core.agent.workflow import FunctionAgent
wallet = Account.from_key(os.environ["PIPELINE_WALLET_KEY"])
async def fetch_filing(ticker: str) -> str:
"""Fetch the latest filing summary for a ticker.
Paid source: $0.05 USDC per fetch via x402."""
async with x402HttpxClient(
account=wallet, base_url="https://api.example.com"
) as client:
resp = await client.get(f"/filings/{ticker}/latest")
return (await resp.aread()).decode()
agent = FunctionAgent(
tools=[FunctionTool.from_defaults(async_fn=fetch_filing)],
llm=llm,
)Pay once or pay every time? Cache deliberately
Retrieval pipelines naturally want to ingest what they fetch — embed the paid document, store it, answer future queries from the index for free. Whether you should depends on the data and its terms. Slow-changing reference material is a buy-once asset: pay, ingest, reuse. Live data — prices, availability, current filings — is worth paying for repeatedly precisely because the cached copy goes stale.
Check the source's terms before building paid responses into a permanent index, and version what you ingest with its fetch date and receipt. x402 settlements carry Ed25519-signed receipts, so your index can record exactly when each paid document was bought — which turns 'is this stale?' into a lookup.
Economics and where to find sources
Per-query pricing changes the math of data acquisition. Instead of licensing a feed you'll mostly not use, the pipeline pays for exactly the queries that needed external data — at minimum prices of $0.01 per call on Loomal, a thousand fallback fetches cost $10. Watch the ratio of paid calls to total queries; if it climbs, the fix is usually ingesting more into the free tier, not a bigger wallet.
For supply, query the Loomal Index: listings are priced, payable endpoints — search, scraping, documents, enrichment — many with live tool lists, so you can judge fit before the first paid call. And if your own pipeline produces retrieval-worthy data, the same rails sell it: price an endpoint, list it, and other pipelines become customers. Loomal's fee is 5% on settled transactions, currently waived.
FAQ
Should my pipeline pay for data on every query?
Usually not. Treat paid sources as the fallback tier: answer from local indexes first, and reach for the paid call when retrieval confidence is low or freshness matters. That keeps spend proportional to the queries that actually needed external data.
Can I embed and store documents I paid for?
Technically yes — once fetched, the response is yours to process like any other text. Whether you may reuse it indefinitely depends on the source's terms, so check them before making paid data a permanent part of an index, and record fetch dates so staleness is visible.
How does the wallet work in a server-side pipeline?
Same as any agent wallet: an EVM account holding USDC on Base, with the key in your secret manager. No ETH is needed — the facilitator submits the on-chain transaction. Keep the balance small and alert on it; it's your hard spending cap.
Does this work with query pipelines, or only agents?
Both. An agent chooses when to invoke the paid tool; in a static query pipeline you call the paying function yourself as a retrieval step — for instance, only when the top-k similarity score falls below a threshold.
Your data has a query price.
List an endpoint, set a per-call price, and sell to pipelines.