crewai-x402 0.1.1

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="base-mainnet",
    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": [
    "arc-testnet", "base-sepolia", "ethereum-sepolia",
    "base-mainnet", "ethereum-mainnet"
  ],
  "payTo": "0x6255d8dd3f84ec460fc8b07db58ab06384a2f487"
}

2. See a 402 response

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

3. Point your crew at the sandbox

wallet = X402Wallet(
    private_key=os.environ["WALLET_PRIVATE_KEY"],
    network="base-sepolia",  # Use testnet for sandbox
    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="base-mainnet",
    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:

# Base (recommended - low fees)
wallet = X402Wallet(private_key=key, network="base-mainnet")

# Ethereum
wallet = X402Wallet(private_key=key, network="ethereum-mainnet")

# Testnets
wallet = X402Wallet(private_key=key, network="base-sepolia")
wallet = X402Wallet(private_key=key, network="arc-testnet")

API Reference

X402Wallet

X402Wallet(
    private_key: str,      # Hex-encoded private key
    network: str,          # Network name (e.g., "base-mainnet")
    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

Network	Chain ID	Environment
base-mainnet	8453	Production
base-sepolia	84532	Testnet
ethereum-mainnet	1	Production
ethereum-sepolia	11155111	Testnet
arc-testnet	5042002	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 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.