crewai-x402 0.2.0

x402 payment protocol integration for CrewAI - enable AI agents to pay for APIs with USDC

crewai-x402

Enable CrewAI agents to pay for APIs with USDC using the x402 protocol.

crewai-x402 integrates the x402 payment protocol with CrewAI, allowing your AI agent crews to autonomously access paid APIs without managing API keys or subscriptions.

What is x402?

x402 is the HTTP-native payment protocol that finally implements the 402 Payment Required status code. Instead of API keys and monthly subscriptions, software pays software—per request, in USDC, with cryptographic proof.

How it works:

1. Agent requests a resource
2. Server returns 402 Payment Required with price info
3. Agent signs a USDC payment authorization (EIP-3009)
4. Agent retries with payment proof
5. Server settles on-chain, returns data

All in a single HTTP round-trip.

Installation

pip install crewai-x402

Quick Start

import os
from crewai import Agent, Crew, Task
from crewai_x402 import X402Wallet, X402Tool

# 1. Create a wallet with a USDC budget
wallet = X402Wallet(
    private_key=os.environ["WALLET_PRIVATE_KEY"],
    network="eip155:8453",  # Base mainnet (CAIP-2 format)
    budget_usd=10.00
)

# 2. Create the payment tool
payment_tool = X402Tool(wallet=wallet)

# 3. Add to your agent
researcher = Agent(
    role="Research Analyst",
    goal="Find accurate data using any available source",
    backstory="You have access to both free and paid APIs.",
    tools=[payment_tool],
)

# 4. Agent can now pay for premium data
task = Task(
    description="Get the premium analysis from https://sandbox.agentrails.io/api/x402/protected/analysis",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()

Try It with the Sandbox

The AgentRails Sandbox is a free test environment with x402-protected endpoints you can hit right away. No signup required to see the 402 flow in action.

1. Check available endpoints and pricing

curl https://sandbox.agentrails.io/api/x402/pricing

{
  "endpoints": [
    { "resource": "/api/x402/protected/analysis", "amountUsdc": 0.01 },
    { "resource": "/api/x402/protected/data", "amountUsdc": 0.001 }
  ],
  "supportedNetworks": [
    "eip155:5042002", "eip155:84532", "eip155:11155111",
    "eip155:8453", "eip155:1"
  ],
  "payTo": "0x6255d8dd3f84ec460fc8b07db58ab06384a2f487"
}

2. See a 402 response

curl -i https://sandbox.agentrails.io/api/x402/protected/analysis
# → 402 Payment Required
# → PAYMENT-REQUIRED: <base64-encoded payment requirements>

3. Point your crew at the sandbox

wallet = X402Wallet(
    private_key=os.environ["WALLET_PRIVATE_KEY"],
    network="eip155:84532",  # Base Sepolia testnet (CAIP-2 format)
    budget_usd=1.00
)

payment_tool = X402Tool(wallet=wallet)

researcher = Agent(
    role="Research Analyst",
    goal="Gather data from premium APIs",
    tools=[payment_tool],
)

task = Task(
    description="Get the analysis from https://sandbox.agentrails.io/api/x402/protected/analysis",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()

Sandbox Endpoints

Endpoint	Cost	Description
GET /api/x402/protected/analysis	$0.01 USDC	AI analysis (premium)
GET /api/x402/protected/data	$0.001 USDC	Data endpoint (micropayment)
GET /api/x402/pricing	Free	Pricing for all protected endpoints
GET /api/x402/stats	Free	Payment statistics

Full API reference: sandbox.agentrails.io/swagger

Features

Automatic Payment Handling

The X402Tool automatically detects 402 responses and handles payment negotiation:

tool = X402Tool(
    wallet=wallet,
    auto_pay=True,  # Automatically pay when within budget
    timeout=30.0,   # Request timeout in seconds
)

Budget Control

Set spending limits at the wallet level:

wallet = X402Wallet(
    private_key=key,
    network="eip155:8453",
    budget_usd=5.00  # Crew can't spend more than $5
)

# Check remaining budget
print(f"Remaining: ${wallet.remaining_usd}")

# Check if can afford a specific amount
if wallet.can_afford(0.01):
    print("Can afford $0.01 request")

Per-Request Price Limits

Limit how much an agent can pay for a single request:

# When calling the tool directly
result = tool._run(
    url="https://sandbox.agentrails.io/api/x402/protected/analysis",
    max_price_usd=0.05  # Won't pay more than $0.05 for this request
)

Payment History

Track all payments made by the wallet:

for payment in wallet.payments:
    print(f"{payment.resource_url}: ${payment.amount_usd}")

# Get summary
summary = wallet.get_payment_summary()
print(f"Total spent: ${summary['spent_usd']}")
print(f"Payments made: {summary['payment_count']}")

Multi-Network Support

Supports multiple EVM networks using CAIP-2 identifiers:

# Base (recommended - low fees)
wallet = X402Wallet(private_key=key, network="eip155:8453")

# Ethereum
wallet = X402Wallet(private_key=key, network="eip155:1")

# Testnets
wallet = X402Wallet(private_key=key, network="eip155:84532")   # Base Sepolia
wallet = X402Wallet(private_key=key, network="eip155:5042002") # Arc testnet

Legacy network names (base-mainnet, base-sepolia, etc.) are still accepted for backwards compatibility.

API Reference

X402Wallet

X402Wallet(
    private_key: str,      # Hex-encoded private key
    network: str,          # CAIP-2 network ID (e.g., "eip155:8453")
    budget_usd: float,     # Maximum USD to spend
)

Properties:

• address - Wallet address
• spent_usd - Total USD spent
• remaining_usd - Remaining budget
• payments - List of PaymentRecord objects

Methods:

• can_afford(amount_usd) - Check if budget allows payment
• sign_payment(to, amount, valid_before) - Sign EIP-3009 authorization
• get_payment_summary() - Get spending summary dict
• reset_budget(new_budget) - Reset budget and clear history

X402Tool

X402Tool(
    wallet: X402Wallet,    # Wallet for payments
    auto_pay: bool = True, # Auto-pay when within budget
    timeout: float = 30.0, # HTTP timeout
)

Tool Input Fields:

• url (required) - URL to request
• method - HTTP method (default: "GET")
• body - Request body
• headers - Additional headers
• max_price_usd - Per-request price limit

Networks

V2 uses CAIP-2 network identifiers:

Network ID (CAIP-2)	Chain ID	Environment	Legacy Alias
eip155:8453	8453	Production	base-mainnet
eip155:84532	84532	Testnet	base-sepolia
eip155:1	1	Production	ethereum-mainnet
eip155:11155111	11155111	Testnet	ethereum-sepolia
eip155:5042002	5042002	Testnet	arc-testnet

Security Considerations

1. Never commit private keys - Use environment variables or secret managers
2. Set appropriate budgets - Limit what crews can spend
3. Use testnets first - Test with eip155:84532 (Base Sepolia) before mainnet
4. Monitor spending - Check wallet.get_payment_summary() regularly

Examples

See the examples/ directory:

• research_crew.py - Research crew with payment capability

How It Differs From API Keys

API Keys	x402
1 key per service	1 wallet for all services
Monthly subscriptions	Pay per request
Human signup required	Zero onboarding
Credential rotation	No credentials to leak
Service-level limits	Agent-level budgets

Related Packages

• langchain-x402 - x402 integration for LangChain

Resources

• x402 Protocol Spec
• AgentRails Documentation
• AgentRails Swagger (Sandbox)
• EIP-3009 Specification
• CrewAI Documentation

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please read our contributing guidelines and submit PRs to the GitHub repository.