What integration means

Integrating payments into Pydantic AI means two related things: letting an agent pay for what it calls (a paid API, a data source, another agent), and, when you want it, charging other callers for what your agent serves. The first is the common case; the second is the earn side, turning a Pydantic AI agent into a paid service.

This page is the integration reference: the pieces, how they fit, and where each path leads. For the step-by-step walkthrough of giving an agent a wallet, see how-to-add-payments-to-pydantic-ai-agent; for the same overview in a sibling framework, see crewai-payment-integration. The payment API product page is the broader reference. Here the focus is the shape of a Pydantic AI integration, including the one idiom that makes it feel native.

The Node proxy reality

Start with the fact that shapes everything: Pydantic AI 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 agent directly.

Instead, the payment work runs in a small Node process and the agent 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, both keep every payment identifier on the verified Node surface, and both are the honest pattern until a Python client ships. It is the same shape used across the Python-framework integrations, with one Pydantic-AI-specific refinement worth applying: inject the proxy through the agent's dependencies.

Inject the wallet through deps

Pydantic AI is built around typed dependencies, and the integration is cleanest when you use them. Rather than hardcode the proxy address in the tool, declare it in deps_type and read it from RunContext. This keeps each run explicitly configured, easy to test with a stub, and ready for per-agent wallets, since a different deps value points the same tool at a different wallet.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    proxy_url: str  # e.g. "http://127.0.0.1:8787", this agent's wallet proxy

agent = Agent("openai:gpt-4o", deps_type=Deps)

The proxy address now flows in per run, so the tool below stays generic and the wallet is a configuration concern, exactly where Pydantic AI wants it.

The pay side

With deps in place, the wallet tool is a @agent.tool that reads the proxy from RunContext and calls it.

import requests

@agent.tool
def pay_and_fetch(ctx: RunContext[Deps], url: str) -> str:
    """Fetch a URL, paying in USDC if it requires payment. Returns the body."""
    res = requests.post(ctx.deps.proxy_url, json={"url": url}, timeout=30)
    return res.text if res.status_code == 200 else f"Failed: {res.status_code}"

Start the proxy (the thirty-line service from the walkthrough) and run the agent with Deps(proxy_url=...). The agent calls pay_and_fetch; the proxy settles any 402 in USDC on Base and returns the result. The payment is invisible to the model, which sees a tool that returns data, and the wallet's spend limit is the backstop.

The earn side

To charge for what your Pydantic AI agent 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 agent.

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 /agent/run": { amountUsdc: "0.10", payToAddress: process.env.B0X_PAYTO_ADDRESS!, paymentRequestId: "pr_agent" } },
});
app.post("/agent/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 agent. The agent's Python code does not change; the gateway is the paywall. Keep a free discovery route so callers can see what the agent does before paying.

Validate what you paid for

Pydantic AI's whole premise is typed, validated outputs, and a paid call is exactly where that premise earns its keep. When the agent pays for data, you have spent real money on the response, so do not hand the model a raw blob and hope; parse the paid response into a Pydantic model and let validation catch a malformed or surprising payload before it reaches the agent's reasoning.

from pydantic import BaseModel

class Quote(BaseModel):
    symbol: str
    price: float

# inside the tool, after a paid fetch:
quote = Quote.model_validate_json(res.text)

If the paid source returns something that does not match Quote, you find out immediately and can decide what to do, rather than letting bad data flow downstream having already paid for it. This pairs the payment with a validation boundary, which is the Pydantic AI way and a genuine reason the framework fits paid retrieval well. The deeper treatment of returning a typed model lives in the how-to; the point here is that paying and validating belong together.

Compatibility

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

When this fits

The integration fits when a Pydantic AI agent needs to pay for what it calls, when you want to charge for what it serves, or both, and you are comfortable running one or two small Node processes alongside the Python. That covers most agent workloads that touch money: an agent paying for data, an agent selling a structured result, or both at once.

It fits less well when the agent never touches paid resources (no wallet needed) or when a single large human-approved payment is the only money movement. For per-call machine payments at agent scale, the proxy-and-gateway integration, wired through Pydantic AI's dependencies, is the path that matches the framework's typed, testable shape.

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

For the pay side, declare the proxy in deps_type, write the pay_and_fetch tool that reads it from RunContext, start a proxy with a sk_test_ key, and make one paid call on Base Sepolia; the walkthrough is how-to-add-payments-to-pydantic-ai-agent. For the earn side, front an endpoint with the Node gateway and confirm an unpaid call gets a 402. For the sibling-framework overview see crewai-payment-integration. Pricing is on the pricing page.