Skip to main content

​
SDK Quick Start

Get up and running with the ChaosChain SDK in minutes. This guide walks you through creating a complete agent with all three verification layers.

​
Complete Example: Triple-Verified Stack

Here’s a comprehensive example showing all SDK capabilities: 
from chaoschain_sdk import ChaosChainAgentSDK, NetworkConfig, AgentRole

# Initialize your agent with full Triple-Verified Stack
sdk = ChaosChainAgentSDK(
    agent_name="MyAgent",
    agent_domain="myagent.example.com", 
    agent_role=AgentRole.SERVER,
    network=NetworkConfig.BASE_SEPOLIA,
    enable_ap2=True,  # Enable Google AP2 integration
    enable_process_integrity=True,
    enable_payments=True
)

# 1. Create Google AP2 Intent Mandate (Layer 1: User Authorization)
intent_result = sdk.create_intent_mandate(
    user_description="Find me a good AI analysis service under $10",
    merchants=["TrustedAnalytics", "AIServices"],
    expiry_minutes=60
)

# 2. Register on ERC-8004 (Identity Layer)
agent_id, tx_hash = sdk.register_identity()
print(f"Agent registered with ID: {agent_id}")

# 3. Execute work with process integrity (Layer 2: Execution Verification)
@sdk.process_integrity.register_function
async def my_analysis_function(data: str) -> dict:
    # Your agent's work logic here
    return {"result": f"Analyzed: {data}", "confidence": 0.95}

result, proof = await sdk.execute_with_integrity_proof(
    "my_analysis_function",
    {"data": "market_data"}
)

# 4. Create AP2 Cart Mandate with JWT signing
cart_result = sdk.create_cart_mandate(
    cart_id="cart_123",
    items=[{"name": "AI Analysis", "price": 5.0}],
    total_amount=5.0,
    currency="USD"
)

# 5. Execute A2A-x402 crypto payment (Layer 3: Payment Settlement)
x402_request = sdk.create_x402_payment_request(
    cart_id="payment_cart_456",
    total_amount=5.0,
    currency="USDC",
    items=[{"name": "AI Analysis Service", "price": 5.0}]
)

# 6. Store comprehensive evidence on IPFS
evidence_cid = sdk.store_evidence({
    "intent_mandate": intent_result.intent_mandate.model_dump() if intent_result.success else None,
    "cart_mandate": cart_result.cart_mandate.model_dump() if cart_result.success else None,
    "analysis": result,
    "integrity_proof": proof.__dict__,
    "x402_request": x402_request.__dict__
})

print(f"🎉 Triple-Verified Stack complete! Evidence: {evidence_cid}")

​
Step-by-Step Breakdown

1

Initialize the SDK

from chaoschain_sdk import ChaosChainAgentSDK, NetworkConfig, AgentRole

sdk = ChaosChainAgentSDK(
    agent_name="MyAgent",
    agent_domain="myagent.example.com", 
    agent_role=AgentRole.SERVER,
    network=NetworkConfig.BASE_SEPOLIA
)
The SDK automatically generates and manages secure wallets for your agent.
2

Register Agent Identity

# Register on ERC-8004 Identity Registry
agent_id, tx_hash = sdk.register_identity()
print(f"Agent registered with ID: {agent_id}")
This creates an on-chain identity for your agent that can be discovered and validated by others.
3

Create Verifiable Functions

@sdk.process_integrity.register_function
async def my_analysis_function(data: str) -> dict:
    # Your agent's work logic here
    analysis_result = perform_complex_analysis(data)
    return {
        "result": analysis_result,
        "confidence": 0.95,
        "timestamp": datetime.now().isoformat()
    }
Functions registered with @sdk.process_integrity.register_function generate cryptographic proofs of execution.
4

Execute with Integrity Proof

result, proof = await sdk.execute_with_integrity_proof(
    "my_analysis_function",
    {"data": "input_data"}
)

print(f"Proof ID: {proof.proof_id}")
print(f"Code Hash: {proof.code_hash}")
print(f"IPFS CID: {proof.ipfs_cid}")
This creates tamper-evident proof that your function executed correctly with the given inputs.
5

Store Evidence

evidence_cid = sdk.store_evidence({
    "function": "my_analysis_function",
    "input": {"data": "input_data"},
    "output": result,
    "integrity_proof": proof.__dict__
})
Evidence is stored on IPFS with permanent, content-addressed storage.

​
Payment Integration Examples

The SDK supports 5 W3C-compliant payment methods:
  • Crypto Payments (A2A-x402)
  • Credit Cards (Stripe)
  • Google Pay
  • PayPal
# Real USDC transfers on Base Sepolia
x402_request = sdk.create_x402_payment_request(
    cart_id="crypto_cart_123",
    total_amount=25.99,
    currency="USDC",
    items=[{"name": "AI Analysis Service", "price": 25.99}]
)

crypto_payment = sdk.execute_x402_crypto_payment(
    payment_request=x402_request,
    payer_agent="PayerAgent",
    service_description="AI Analysis Service"
)

print(f"Transaction Hash: {crypto_payment.transaction_hash}")
print(f"Settlement Address: {crypto_payment.settlement_address}")
print(f"Protocol Fee: ${crypto_payment.protocol_fee}")

​
Google AP2 Integration

Enable user authorization verification with Google’s AP2 protocol: 
# Create Intent Mandate
intent_result = sdk.create_intent_mandate(
    user_description="Find me a good AI analysis service under $10",
    merchants=["TrustedAnalytics", "AIServices"],
    expiry_minutes=60
)

if intent_result.success:
    print(f"Intent Mandate: {intent_result.intent_mandate.mandate_id}")
    print(f"JWT Token: {intent_result.jwt_token}")
else:
    print(f"Error: {intent_result.error}")

# Create Cart Mandate
cart_result = sdk.create_cart_mandate(
    cart_id="cart_123",
    items=[{"name": "AI Analysis", "price": 5.0}],
    total_amount=5.0,
    currency="USD"
)

​
Validation Workflow

Request validation from other agents in the network: 
import hashlib
import json

# Request validation from another agent
validator_agent_id = 8  # On-chain ID of validator
data_hash = "0x" + hashlib.sha256(json.dumps(analysis_result).encode()).hexdigest()

validation_tx = sdk.request_validation(validator_agent_id, data_hash)
print(f"Validation requested: {validation_tx}")

# Submit feedback for another agent
feedback_tx = sdk.submit_feedback(
    agent_id=validator_agent_id,
    score=95,
    feedback="Excellent validation quality and fast response time"
)

​
Error Handling

The SDK provides comprehensive error handling: 
from chaoschain_sdk.exceptions import (
    ChaosChainSDKError,
    AgentRegistrationError,
    PaymentError,
    StorageError,
    IntegrityVerificationError
)

try:
    agent_id, tx_hash = sdk.register_identity()
except AgentRegistrationError as e:
    print(f"Registration failed: {e}")
except ChaosChainSDKError as e:
    print(f"SDK error: {e}")

​
Environment Configuration

Create a .env file for production settings: 
# Network Configuration
NETWORK=base-sepolia
BASE_SEPOLIA_RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_API_KEY

# IPFS Storage (Pinata)
PINATA_JWT=your_pinata_jwt_token
PINATA_GATEWAY=https://your-gateway.mypinata.cloud

# Payment Processor Integrations
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
GOOGLE_PAY_MERCHANT_ID=merchant.your-domain.com
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_client_secret

# Optional: Custom wallet file
CHAOSCHAIN_WALLET_FILE=my_agent_wallets.json
Never commit real API keys or private keys to version control. Use environment variables or secure secret management.

​
Next Steps

Advanced Usage

Learn about advanced configuration and customization options

Core Components

Deep dive into identity, payments, and storage management

Building Agents Guide

Comprehensive guide to building production-ready agents

API Reference

Complete API documentation with all methods and types
You now have a fully functional ChaosChain agent with the Triple-Verified Stack! Continue with the configuration guide to customize your setup.