crewai-x402 0.1.0__tar.gz

crewai_x402-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

crewai_x402-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentRails
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crewai_x402-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: crewai-x402
+Version: 0.1.0
+Summary: x402 payment protocol integration for CrewAI - enable AI agents to pay for APIs with USDC
+Project-URL: Homepage, https://agentrails.io
+Project-URL: Documentation, https://agentrails.io/docs
+Project-URL: Repository, https://github.com/kmatthewsio/crewai-x402
+Project-URL: Issues, https://github.com/kmatthewsio/crewai-x402/issues
+Author-email: AgentRails <dev@agentrails.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,api-monetization,crewai,crypto,payments,usdc,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: crewai>=0.10.0
+Requires-Dist: eth-account>=0.10.0
+Requires-Dist: eth-typing>=3.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.22.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crewai-x402
+
+[![PyPI version](https://badge.fury.io/py/crewai-x402.svg)](https://pypi.org/project/crewai-x402/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Enable CrewAI agents to pay for APIs with USDC using the x402 protocol.**
+
+crewai-x402 integrates the [x402 payment protocol](https://x402.org) 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
+
+```bash
+pip install crewai-x402
+```
+
+## Quick Start
+
+```python
+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 premium market data from https://api.example.com/premium",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[task])
+result = crew.kickoff()
+```
+
+## Features
+
+### Automatic Payment Handling
+The `X402Tool` automatically detects 402 responses and handles payment negotiation:
+
+```python
+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:
+
+```python
+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:
+
+```python
+# When calling the tool directly
+result = tool._run(
+    url="https://api.example.com/expensive",
+    max_price_usd=0.05  # Won't pay more than $0.05 for this request
+)
+```
+
+### Payment History
+Track all payments made by the wallet:
+
+```python
+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:
+
+```python
+# 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
+
+```python
+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
+
+```python
+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/](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](https://pypi.org/project/langchain-x402/) - x402 integration for LangChain
+
+## Resources
+
+- [x402 Protocol Spec](https://x402.org)
+- [AgentRails Documentation](https://agentrails.io/docs)
+- [EIP-3009 Specification](https://eips.ethereum.org/EIPS/eip-3009)
+- [CrewAI Documentation](https://docs.crewai.com)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines and submit PRs to the [GitHub repository](https://github.com/kmatthewsio/crewai-x402).

crewai_x402-0.1.0/README.md

@@ -0,0 +1,224 @@
+# crewai-x402
+
+[![PyPI version](https://badge.fury.io/py/crewai-x402.svg)](https://pypi.org/project/crewai-x402/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Enable CrewAI agents to pay for APIs with USDC using the x402 protocol.**
+
+crewai-x402 integrates the [x402 payment protocol](https://x402.org) 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
+
+```bash
+pip install crewai-x402
+```
+
+## Quick Start
+
+```python
+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 premium market data from https://api.example.com/premium",
+    agent=researcher,
+)
+
+crew = Crew(agents=[researcher], tasks=[task])
+result = crew.kickoff()
+```
+
+## Features
+
+### Automatic Payment Handling
+The `X402Tool` automatically detects 402 responses and handles payment negotiation:
+
+```python
+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:
+
+```python
+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:
+
+```python
+# When calling the tool directly
+result = tool._run(
+    url="https://api.example.com/expensive",
+    max_price_usd=0.05  # Won't pay more than $0.05 for this request
+)
+```
+
+### Payment History
+Track all payments made by the wallet:
+
+```python
+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:
+
+```python
+# 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
+
+```python
+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
+
+```python
+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/](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](https://pypi.org/project/langchain-x402/) - x402 integration for LangChain
+
+## Resources
+
+- [x402 Protocol Spec](https://x402.org)
+- [AgentRails Documentation](https://agentrails.io/docs)
+- [EIP-3009 Specification](https://eips.ethereum.org/EIPS/eip-3009)
+- [CrewAI Documentation](https://docs.crewai.com)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines and submit PRs to the [GitHub repository](https://github.com/kmatthewsio/crewai-x402).

crewai_x402-0.1.0/crewai_x402/__init__.py

@@ -0,0 +1,19 @@
+"""CrewAI x402 integration - enable AI agents to pay for APIs with USDC."""
+
+from .wallet import PaymentRecord, X402Wallet
+
+__all__ = [
+    "X402Wallet",
+    "PaymentRecord",
+]
+
+# Import tool only if crewai is available
+try:
+    from .tool import X402Tool, X402ToolInput
+
+    __all__.extend(["X402Tool", "X402ToolInput"])
+except ImportError:
+    # crewai not installed - tool not available
+    pass
+
+__version__ = "0.1.0"

crewai_x402-0.1.0/crewai_x402/eip3009.py

@@ -0,0 +1,125 @@
+"""EIP-3009 signature utilities for x402 payments."""
+
+from typing import Any
+
+from eth_account import Account
+
+
+# Network configurations
+NETWORKS: dict[str, dict[str, Any]] = {
+    "base-mainnet": {
+        "chain_id": 8453,
+        "usdc_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "name": "USD Coin",
+        "version": "2",
+    },
+    "base-sepolia": {
+        "chain_id": 84532,
+        "usdc_address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        "name": "USD Coin",
+        "version": "2",
+    },
+    "ethereum-mainnet": {
+        "chain_id": 1,
+        "usdc_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+        "name": "USD Coin",
+        "version": "2",
+    },
+    "ethereum-sepolia": {
+        "chain_id": 11155111,
+        "usdc_address": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+        "name": "USD Coin",
+        "version": "2",
+    },
+    "arc-testnet": {
+        "chain_id": 5042002,
+        "usdc_address": "0x3600000000000000000000000000000000000000",
+        "name": "USD Coin",
+        "version": "2",
+    },
+}
+
+
+def build_transfer_authorization_typed_data(
+    network: str,
+    from_address: str,
+    to_address: str,
+    value: int,
+    valid_after: int,
+    valid_before: int,
+    nonce: bytes,
+) -> dict[str, Any]:
+    """Build EIP-712 typed data for TransferWithAuthorization."""
+    config = NETWORKS.get(network)
+    if not config:
+        raise ValueError(f"Unknown network: {network}")
+
+    return {
+        "types": {
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"},
+            ],
+            "TransferWithAuthorization": [
+                {"name": "from", "type": "address"},
+                {"name": "to", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "validAfter", "type": "uint256"},
+                {"name": "validBefore", "type": "uint256"},
+                {"name": "nonce", "type": "bytes32"},
+            ],
+        },
+        "primaryType": "TransferWithAuthorization",
+        "domain": {
+            "name": config["name"],
+            "version": config["version"],
+            "chainId": config["chain_id"],
+            "verifyingContract": config["usdc_address"],
+        },
+        "message": {
+            "from": from_address,
+            "to": to_address,
+            "value": value,
+            "validAfter": valid_after,
+            "validBefore": valid_before,
+            "nonce": nonce if isinstance(nonce, bytes) else bytes.fromhex(nonce.replace("0x", "")),
+        },
+    }
+
+
+def sign_transfer_authorization(
+    private_key: str,
+    network: str,
+    from_address: str,
+    to_address: str,
+    value: int,
+    valid_after: int,
+    valid_before: int,
+    nonce: bytes,
+) -> str:
+    """Sign a TransferWithAuthorization message and return the signature."""
+    typed_data = build_transfer_authorization_typed_data(
+        network=network,
+        from_address=from_address,
+        to_address=to_address,
+        value=value,
+        valid_after=valid_after,
+        valid_before=valid_before,
+        nonce=nonce,
+    )
+
+    # Sign the message - pass types without EIP712Domain (library adds it)
+    message_types = {
+        k: v for k, v in typed_data["types"].items() if k != "EIP712Domain"
+    }
+
+    account = Account.from_key(private_key)
+    signed = account.sign_typed_data(
+        typed_data["domain"],
+        message_types,
+        typed_data["message"],
+    )
+
+    return "0x" + signed.signature.hex()