Agent Economy — x402 Payment Layer for AI Agents
What It Does
Agent Economy adds a paywall to any AI agent skill using the x402 protocol. When Agent A calls Agent B's paid skill, it gets an HTTP 402 "Payment Required" response with payment details. Agent A sends USDC on-chain, Agent B verifies the payment, then serves the result.
One wrapper. Any skill. Real money.
How x402 Works
1. Agent A calls skill endpoint
2. Server responds: HTTP 402 + payment details (wallet, amount, token)
3. Agent A sends USDC to wallet on Base/Ethereum
4. Agent A retries with tx_hash in header
5. Server verifies payment on-chain
6. Server serves the response
No API keys to manage. No billing platforms. Just on-chain payments.
Quick Start
1. Install
from agent_economy import Paywall, Ledger
# Create a paywall with your wallet
paywall = Paywall(
wallet_address="0xYourWalletAddress",
network="base", # or "ethereum", "polygon"
price_per_call=0.01, # $0.01 USDC per call
)
2. Wrap Any Skill
# Your existing skill function
def analyze_server(metrics):
return {"health": "ok", "score": 95}
# Wrap it with payment
paid_analyze = paywall.require_payment(analyze_server)
# Now it returns 402 until paid, then serves the result
result = paid_analyze(request)
3. FastAPI Integration
from fastapi import FastAPI, Request, Response
from agent_economy import Paywall
app = FastAPI()
paywall = Paywall(wallet_address="0x...", network="base", price_per_call=0.05)
@app.post("/api/analyze")
async def analyze(request: Request):
# Check payment first
payment_result = paywall.check_payment(request)
if payment_result.status == "payment_required":
return payment_result.to_response() # Returns HTTP 402
# Payment verified — serve the skill
data = await request.json()
return {"result": "your analysis here"}
4. Calling a Paid Skill (Client Side)
from agent_economy import PaymentClient
client = PaymentClient(
wallet_private_key="0xYourPrivateKey", # or wallet connect
network="base"
)
# Call a paid skill — handles payment automatically
result = client.call(
url="https://api.example.com/api/analyze",
method="POST",
json={"metrics": {...}},
max_price=0.10 # Won't pay more than $0.10
)
Pricing Models
Per-Call
paywall = Paywall(price_per_call=0.01) # $0.01 every call
Per-Token (Usage-Based)
paywall = Paywall(
price_per_call=0.00, # Base price
price_per_1k_tokens=0.002 # $0.002 per 1K tokens
)
Tiered
paywall = Paywall(pricing_tiers={
"basic": 0.01, # Basic analysis
"premium": 0.05, # Deep analysis
"enterprise": 0.25 # Full audit
})
Subscription (Time-Based)
paywall = Paywall(
subscription_price=9.99, # $9.99/month
subscription_duration_days=30
)
# Subscribers get unlimited calls for the period
Ledger
Track all payments, usage, and revenue.
from agent_economy import Ledger
ledger = Ledger(db_path="payments.db")
# Record a payment
ledger.record(
payer="0xABC...",
skill="analyze-server",
amount=0.01,
tx_hash="0x123...",
network="base"
)
# Query revenue
revenue = ledger.get_revenue(period="30d")
# {"total_usd": 142.50, "calls": 14250, "unique_payers": 23}
# Query per-skill breakdown
skills = ledger.get_skill_breakdown()
# {"analyze-server": {"calls": 8000, "revenue": 80.00}, ...}
# Check if address has active subscription
active = ledger.is_subscribed("0xABC...", skill="analyze-server")
On-Chain Payment Verification
Agent Economy verifies USDC transfers on-chain. No trust required.
from agent_economy import PaymentVerifier
verifier = PaymentVerifier(network="base")
# Verify a transaction
valid = verifier.verify(
tx_hash="0x123...",
expected_sender="0xABC...",
expected_recipient="0xYourWallet",
expected_amount=0.01, # USDC
tolerance=0.001 # Allow small variance for gas
)
if valid:
print("Payment confirmed on-chain")
Supported Networks
| Network | Chain ID | USDC Contract |
|---|
| Base | 8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Ethereum | 1 | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |
| Polygon | 137 | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 |
| Arbitrum | 42161 | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 |
HTTP 402 Response Format
When payment is required, the server responds:
HTTP 402 Payment Required
Content-Type: application/json
{
"error": "payment_required",
"payment": {
"recipient": "0xYourWalletAddress",
"amount": "0.01",
"token": "USDC",
"network": "base",
"chain_id": 8453,
"description": "Per-call fee for analyze-server skill"
},
"retry": {
"header": "X-Payment-Tx-Hash",
"instructions": "Send USDC to recipient, then retry with tx hash in header"
}
}
Security Considerations
- Never expose private keys in code — use environment variables or vault
- Validate amounts — always check
expected_amount with tolerance
- Prevent replay — track used tx hashes in the ledger to prevent double-spend
- Rate limit — prevent spam calls that waste verification gas
- Refund policy — define upfront, no on-chain refunds by default
Architecture
┌──────────┐ HTTP ┌──────────────┐ Verify ┌──────────┐
│ Agent A │ ────────────→ │ Your Skill │ ──────────→ │ Blockchain │
│ (Caller) │ ←── 402 ──── │ (Server) │ ←─ Confirmed │ (Base/ETH) │
│ │ ── + tx ────→│ │ │ │
│ │ ←─ 200 ─────│ │ │ │
└──────────┘ └──────────────┘ └──────────┘
│
┌─────┴──────┐
│ Ledger │
│ (SQLite) │
└────────────┘
Requirements
- Python 3.8+
requests (for blockchain API calls)web3 (optional, for direct on-chain verification)- SQLite (built-in, for ledger)
Install Dependencies
pip install agent-economy
# or
pip install requests web3 # manual
Support
