What the integration covers

The CrewAI payment integration is a pattern, not a package. Each agent in a crew pays through a small local x402 proxy built on @blockchain0x/x402, which gives the crew four capabilities it lacks by default: per-agent paid-tool calls, per-agent identity with a public profile counterparties can verify, per-agent spend limits that survive prompt injection, and audit indexed by agent rather than by crew run.

The design principle is that every CrewAI agent is its own economic actor. A crew of five agents has five wallets, five limits, and five audit trails. That matches how CrewAI already thinks - each agent has its own role, goal, and tools - and extends the same isolation to money.

This is the integration-cluster reference. The task-oriented walkthrough is how-to-add-payments-to-crewai-agent, which includes the full proxy code; the canonical reference is the CrewAI integration page. Here the focus is what the integration is, what it touches, and the crew-specific patterns.

Compatibility matrix

Because each agent's tool calls a localhost proxy, anything in CrewAI that calls a tool works.

What is not in scope:

• Tools that bypass BaseTool and call HTTP directly. Point them at the proxy yourself, or wire the payment API directly.
• A single crew-wide pre-authorized budget across all agents at once. The model is per agent; share one key across proxies if you must, and accept the attribution trade-off.

Surface area in one screen

The Python side has no Blockchain0x code at all. A tool just calls the proxy:

from crewai.tools import BaseTool
import requests

class RealtimeQuoteTool(BaseTool):
    name: str = "get_quote_realtime"
    description: str = "Fetch a real-time quote for a stock ticker."

    def _run(self, ticker: str) -> str:
        upstream = f"https://quotes.example.com/v1/quote?ticker={ticker}"
        res = requests.post("http://127.0.0.1:8787", json={"url": upstream}, timeout=30)
        return res.text if res.status_code == 200 else f"Lookup failed: {res.status_code}"

The proxy is the Node piece, about thirty lines built on createClient plus createX402Client. The full proxy code is in the how-to-add-payments-to-crewai-agent walkthrough. Run one proxy per agent wallet, each on its own port with its own B0X_API_KEY.

The other half is the spend limit, which you set in the dashboard and read back over the API:

import os, requests

res = requests.get(
    f"https://api.blockchain0x.com/v1/agents/{os.environ['RESEARCHER_AGENT_ID']}/spend-permissions",
    headers={"Authorization": f"Bearer {os.environ['B0X_API_KEY']}"},
    timeout=30,
)
permissions = res.json()  # allowance_wei, per_tx_wei, period_seconds, ...

No new Agent class, no replacement Crew runtime, no patching of CrewAI internals. The integration is additive: a tool that calls a proxy, and a limit you set once.

Running one proxy per agent sounds heavy and is not. The proxy is stateless and tiny, so a five-agent crew runs five proxies on five ports under one process manager, or as five containers in the same pod. Pass each its own B0X_API_KEY and its own port through the environment, and have each agent's tool read the matching port from a config value. In practice teams template this: a short loop reads a map of agent name to key and port, starts a proxy for each, and the crew definition references the same map. It is the same shape as running one sidecar per service, which most teams already know how to operate.

Crew patterns and per-agent wallets

The integration earns its keep when you use it the way CrewAI already structures work: one wallet per agent. Four patterns follow.

Role-based budgets. A researcher hitting premium data needs a higher allowance than a summariser that only calls an LLM. Per-agent wallets let you set the limit per role. A shared wallet forces you to budget for the worst case and over-allocate everyone else.

Manager-with-delegates billing. In Process.hierarchical, the manager delegates to specialists. With per-agent wallets, the manager pays each delegate for its sub-task and the owner gets a per-delegate audit trail. This is the agent-to-agent pattern in miniature, documented at the agent-to-agent payment glossary entry.

Crews-of-crews. Flow-orchestrated multi-crew systems treat each Crew as a unit, and the per-agent wallets inside each Crew keep working. Audit at the Flow level shows which Crew spent; audit at the agent level shows which role within it spent.

Safety through isolation. A prompt-injected agent spends only its own allowance. The rest of the crew keeps running. Share one wallet and a single compromised agent can drain the balance for everyone on it.

For the parallel decisions on LangChain, see langchain-payment-integration.

What the integration does not touch

The pattern stays narrow. These parts of your CrewAI stack are untouched:

• The LLM. Each agent's llm passes through; payment is in the tool.
• Role, goal, backstory. Agent personality and reasoning are unchanged.
• The Process type. Sequential, hierarchical, custom, all see normal tools.
• Task delegation. allow_delegation=True keeps working; payment runs on the underlying tool calls.
• Memory and context. Short-term, long-term, and entity memory operate independently.
• Telemetry. OpenTelemetry and CrewAI's own observability see normal tool invocations.
• Other tools. Free tools coexist with paid ones on the same agent.

When this is the right integration

Two situations where this pattern beats the alternatives.

Your crew calls paid third-party services. Premium data, paid LLMs, paid MCP tools, all surface as 402-returning endpoints the proxy handles. The alternative, per-tool credentials and per-tool rate limiters, does not scale past a handful of tools and gives you no unified limit.

Your crew is itself a paid service. Flip the direction and gate your crew's HTTP surface with the x402 server adapter so external callers pay it. Same protocol, other side of the call graph. The receive side is covered in how-to-add-payments-to-mcp-server.

Where it is not the right pick: a single-agent crew calling one trusted provider with a shared key (no payment surface to add), a fully internal crew where nothing is paid (no economic actor needed), or a workload where humans drive every payment through checkout (use Stripe).

Pricing and tier choices

The pattern is free; you write code against open packages. What you pay is the wallet platform fee, set per agent by tier on the pricing page: Free is $0 per agent per month at a 5% transaction fee, Pro is $9 per agent per month at 2%, and Business is $29 per agent per month at 1%. Per-agent pricing means you pay for the agents that actually transact.

A typical crew shape: keep agents on Free until their volume justifies an upgrade, then move the busiest to Pro. The rough crossover is a few hundred dollars of monthly volume per agent, where Pro's monthly fee plus 2% beats Free's flat 5%. Because tiers are per agent, you mix freely.

One CrewAI-specific note: in Process.hierarchical, the manager usually has the highest volume because every delegation routes through it. Upgrade that agent first and leave the specialists on Free until their own volume earns the change.