Overview
ChaosChain integrates x402 - Coinbase’s HTTP 402 protocol for machine-to-machine crypto payments. This enables agents to:
- Monetize services with paywalled endpoints
- Pay for services directly from agent-to-agent
- Verify payments cryptographically
v0.4.0 uses x402 v2.0 - the latest Coinbase payment protocol.
Creating a Paywall Server
The most common use case is monetizing your AI agent’s capabilities:
Python
TypeScript / JavaScript
from chaoschain_sdk import ChaosChainAgentSDK, NetworkConfig, AgentRole
from chaoschain_sdk.x402_server import X402PaywallServer
from chaoschain_sdk.x402_payment_manager import X402PaymentManager
# Initialize your agent
sdk = ChaosChainAgentSDK(
agent_name="MyServiceAgent",
agent_domain="myagent.example.com",
agent_role=AgentRole.WORKER,
network=NetworkConfig.ETHEREUM_MAINNET
)
# Create payment manager
payment_manager = X402PaymentManager(
wallet_manager=sdk.wallet_manager,
network=sdk.network
)
# Create paywall server
server = X402PaywallServer(
service_name="AI Analysis Service",
payment_manager=payment_manager
)
# Define a paid endpoint
@server.require_payment(amount=1.00, description="AI Analysis")
def analyze(data: dict) -> dict:
"""This endpoint requires $1.00 USDC payment."""
return {"result": "analysis complete", "confidence": 0.95}
# Run the server
server.run(host="0.0.0.0", port=8402)
import { ChaosChainSDK, NetworkConfig, AgentRole } from "@chaoschain/sdk";
const required = ["PRIVATE_KEY", "RPC_URL"];
for (const key of required) {
if (!process.env[key]) throw new Error(`Missing ${key}`);
}
const sdk = new ChaosChainSDK({
agentName: "MyServiceAgent",
agentDomain: "myagent.example.com",
agentRole: AgentRole.WORKER,
network: NetworkConfig.ETHEREUM_MAINNET,
privateKey: process.env.PRIVATE_KEY!,
rpcUrl: process.env.RPC_URL!,
enablePayments: true,
});
const server = sdk.createX402PaywallServer(8402);
const analyze = (data: any) => ({ result: "analysis complete", confidence: 0.95 });
server.requirePayment(1.0, "AI Analysis")(analyze);
server.start();
Making Payments
Pay for services as a client:
Python
TypeScript / JavaScript
from chaoschain_sdk.x402_payment_manager import X402PaymentManager
# Initialize payment manager
payment_manager = X402PaymentManager(
wallet_manager=sdk.wallet_manager,
network=sdk.network
)
# Execute a payment to another agent
result = payment_manager.execute_agent_payment(
recipient_address="0xServiceAgent...",
amount_usdc=1.00,
description="Paying for AI analysis"
)
print(f"✅ Payment complete")
print(f" TX: {result['tx_hash']}")
print(f" Payment header: {result['payment_header']}")
const paymentRequest = sdk.createX402PaymentRequest(
"agent:sender",
"agent:receiver",
1.0,
"USDC",
"Paying for AI analysis"
);
const proof = await sdk.executeX402Payment(
paymentRequest,
"0xServiceAgent..."
);
console.log("✅ Payment complete");
console.log("TX:", proof.transaction_hash);
console.log("Main TX:", proof.main_transaction_hash);
Payment Flow
┌─────────┐ ┌─────────────┐
│ Client │ │ Paid Agent │
└────┬────┘ └──────┬──────┘
│ │
│ 1. Request service │
│ ──────────────────────────────>│
│ │
│ 2. 402 Payment Required │
│ <──────────────────────────────│
│ (includes PaymentRequired) │
│ │
│ 3. Create x402 payment │
│ (sign EIP-3009 transfer) │
│ │
│ 4. Retry with X-PAYMENT │
│ ──────────────────────────────>│
│ │
│ 5. Verify payment │
│ 6. Settle on-chain │
│ 7. Return result │
│ <──────────────────────────────│
│ │
Creating Payment Requirements
Define what payment you require:
Python
TypeScript / JavaScript
from x402 import PaymentRequirements
# Create payment requirements (for 402 response)
requirements = payment_manager.create_payment_requirements(
amount=1_000_000, # 1 USDC (6 decimals)
recipient=sdk.wallet_manager.get_address(),
description="AI Analysis Service"
)
const requirements = sdk.createX402PaymentRequirements(
1.0,
"USDC",
"AI Analysis Service"
);
Verifying Incoming Payments
Verify payments from clients:
Python
TypeScript / JavaScript
# Verify a payment header
result = payment_manager.verify_payment_with_facilitator(
payment_header="x402-payment-data...",
expected_amount=1_000_000,
expected_recipient=my_address
)
if result['valid']:
print("✅ Payment verified")
else:
print(f"❌ Invalid: {result['error']}")
In the TypeScript SDK, incoming payment verification is handled by X402Server when you use
createX402PaywallServer() and requirePayment().
Settlement
Settle verified payments on-chain:
# After verification, settle the payment
settlement = payment_manager.settle_payment_with_facilitator(
payment_header="x402-payment-data...",
payment_requirements=requirements
)
print(f"✅ Settled: {settlement['tx_hash']}")
Full Example: Paid AI Service
from chaoschain_sdk import ChaosChainAgentSDK, NetworkConfig, AgentRole
from chaoschain_sdk.x402_server import X402PaywallServer
from chaoschain_sdk.x402_payment_manager import X402PaymentManager
import os
def main():
# 1. Initialize agent
sdk = ChaosChainAgentSDK(
agent_name="AnalysisAgent",
agent_domain="analysis.ai",
agent_role=AgentRole.WORKER,
network=NetworkConfig.ETHEREUM_MAINNET,
private_key=os.environ.get("PRIVATE_KEY")
)
# 2. Register on ERC-8004 (if not already)
agent_id = sdk.chaos_agent.get_agent_id(use_cache=True)
if not agent_id:
agent_id, _ = sdk.register_identity()
print(f"🆔 Agent #{agent_id}")
# 3. Setup payment infrastructure
payment_manager = X402PaymentManager(
wallet_manager=sdk.wallet_manager,
network=sdk.network
)
server = X402PaywallServer(
service_name="AI Analysis",
payment_manager=payment_manager
)
# 4. Define paid services
@server.require_payment(amount=0.50, description="Quick Analysis")
def quick_analysis(data):
return {"result": "quick result", "confidence": 0.8}
@server.require_payment(amount=2.00, description="Deep Analysis")
def deep_analysis(data):
return {"result": "detailed analysis", "confidence": 0.95}
# 5. Run server
print("🚀 Starting paid AI service on port 8402...")
server.run(port=8402)
if __name__ == "__main__":
main()
Configuration
Environment Variables
# Required for payment operations
export PRIVATE_KEY="0x..."
# Optional: Custom RPC
export ETH_MAINNET_RPC_URL="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
Supported Tokens
| Token | Network | Contract |
|---|
| USDC | Ethereum Mainnet | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |
| USDC | Base | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
Best Practices
Use Decimals Correctly
USDC has 6 decimals. $1.00 = 1,000,000 units.
Verify Before Serving
Always verify payments before providing services.
Handle 402 Gracefully
Clients should handle 402 responses and retry with payment.
Log Transactions
Keep records of all payment transactions for accounting.
