What integration means

Integrating payments into Haystack means two related things: letting a pipeline pay for what it fetches (a paid API, a data source, another agent), and, when you want it, charging other callers for what your pipeline serves. The first is the common case, since Haystack is built around retrieval and some sources cost money; the second is the earn side, turning a pipeline into a paid service.

This page is the integration reference: the pieces, how they fit, and the Haystack idiom that makes payment feel native. For the closely related RAG framework see llamaindex-payment-integration; for a sibling framework see crewai-payment-integration. The payment API product page is the broader reference. Here the focus is the shape of a Haystack integration, expressed as a component in a pipeline.

The Node proxy reality

Start with the fact that shapes everything: Haystack is Python, and the payment packages, @blockchain0x/x402 and @blockchain0x/node, ship for Node. There is no Python payment package, so you do not call Blockchain0x from inside the pipeline directly.

Instead, the payment work runs in a small Node process and the pipeline talks to it over localhost. On the pay side this is a proxy that holds the wallet; on the earn side it is a gateway that gates an endpoint. Both are small, about thirty lines, and both keep every payment identifier on the verified Node surface. It is the same pattern used across the Python-framework integrations, and for Haystack the clean move is to wrap the call to that proxy in a custom component.

Payment as a pipeline component

A Haystack pipeline is built from connected components, so the idiomatic integration is a payment component. It has typed inputs and outputs, slots between the components before and after it, and is reusable across pipelines.

import requests
from haystack import component

@component
class PaidFetcher:
    @component.output_types(body=str)
    def run(self, url: str):
        res = requests.post("http://127.0.0.1:8787", json={"url": url}, timeout=30)
        body = res.text if res.status_code == 200 else f"Failed: {res.status_code}"
        return {"body": body}

Add it to a pipeline with pipeline.add_component("paid_fetcher", PaidFetcher()) and connect it like any component. Start the proxy, and when the pipeline runs the component, the proxy settles any 402 in USDC on Base and the fetched data flows to the next step. The payment is invisible to the rest of the pipeline, which just sees a component that produces a body, and the wallet's spend limit is the backstop. For a Haystack Agent, wrap the same proxy call as a tool instead; the mechanism underneath is identical.

A paid source in a RAG pipeline

Here is the payoff for Haystack specifically. Because payment is a component, a paid data source becomes just another node in a retrieval-augmented pipeline, sitting alongside your retrievers and feeding the prompt builder like any other source. The pipeline draws on free local documents and a paid external source in the same flow, and downstream components do not need to know which produced what.

That makes paid data a first-class part of RAG rather than a bolt-on. A pipeline can retrieve from its document store when that suffices and fetch from a paid source when it needs fresher or proprietary data, with the PaidFetcher component as the boundary where money is spent. Pair it with caching, keying the fetched result so the same paid source is not called twice in one run, and the cost tracks genuinely new fetches rather than repeated ones. This is the same retrieval-first fit that suits LlamaIndex, expressed through Haystack's component-and-pipeline model.

The earn side

To charge for what your Haystack pipeline serves, expose it over HTTP and front it with a small Node gateway running createX402Plugin. The gateway returns the 402, verifies payment, and proxies paid requests to your pipeline.

import Fastify from "fastify";
import { createClient } from "@blockchain0x/node";
import { createX402Plugin } from "@blockchain0x/x402/server/fastify";

const sdk = createClient({ apiKey: process.env.B0X_API_KEY! });
const app = Fastify();
await app.register(createX402Plugin, {
  sdk,
  defaultNetwork: "testnet",
  pricing: { "POST /pipeline/run": { amountUsdc: "0.05", payToAddress: process.env.B0X_PAYTO_ADDRESS!, paymentRequestId: "pr_pipeline" } },
});
app.post("/pipeline/run", async (req) => {
  const r = await fetch("http://127.0.0.1:8000/run", { method: "POST", body: JSON.stringify(req.body) });
  return await r.json();
});
await app.listen({ port: 8080 });

An unpaid call gets a 402; a paid one runs your pipeline. The pipeline's Python code does not change; the gateway is the paywall. Keep a free discovery route so callers can see what the pipeline does before paying.

Test the component in isolation

A quiet benefit of modelling payment as a component is that you can test it on its own, outside any pipeline. Because PaidFetcher has typed inputs and outputs and no hidden state, you can run it directly with a test URL against a proxy holding a sk_test_ key and assert on what it returns, before ever wiring it into a larger flow. That isolates payment from the rest of the pipeline when something goes wrong.

So verify in two steps: first run the component alone and confirm a paid fetch settles on Base Sepolia and returns the body; then connect it into the pipeline and confirm the data reaches the next component. If a paid run misbehaves once it is wired up, you already know the component itself works, so the issue is the connection or the data shape, not the payment. That separation is exactly what Haystack's component model is meant to give you, and it applies as cleanly to a paying component as to any other.

Compatibility

The integration works across Haystack's surfaces because it lives in a component (pay) or a gateway (earn), not in the framework internals.

When this fits

The integration fits when a Haystack pipeline retrieves from sources that cost money, when you want to charge for what the pipeline serves, or both. It fits Haystack naturally, since retrieval is its core and a paid source slots into a pipeline like any component, and a pipeline that pays per fetch and one that earns per run are both first-class uses.

It fits less well when every source is free and internal or when a single human-approved payment is the only money movement. For per-call machine payments around retrieval, the payment component plus proxy, with an optional earn gateway, is the integration that matches how Haystack pipelines are actually built.

Pricing

Integration 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%, Business is $29 at 1%. Per-agent pricing means each agent that transacts, paying or earning, is billed on its own wallet, so you pay for the agents that actually move money.

What to ship today

Write a PaidFetcher component, add it to a pipeline and connect it, start a proxy with a sk_test_ key, and make one paid fetch on Base Sepolia. Try connecting it alongside a retriever so a paid source feeds the same flow. To earn, front your pipeline with the Node gateway. For the RAG-framework sibling see llamaindex-payment-integration. Pricing is on the pricing page.