Metadata-Version: 2.4
Name: cirtusai-sdk
Version: 0.2.1
Summary: A Python SDK for the CirtusAI backend: agent, wallet, and credential management.
Author: CirtusAI Team
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: click>=8.0.0
Requires-Dist: langchain>=0.1.0
Requires-Dist: langchain-deepseek>=0.0.1
Requires-Dist: python-dotenv>=0.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: responses>=0.10.0; extra == "dev"
Requires-Dist: respx>=0.20.0; extra == "dev"
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CirtusAI Python SDK - Complete Developer Guide (Updated July 2025)

## CirtusAI - Autonomy Verified

_The Trust Layer for the Agent Economy_

The most comprehensive SDK for autonomous AI agent management with blockchain-level security

The CirtusAI Python SDK provides everything developers need to build powerful, secure, and compliant AI agent applications. From basic wallet management to advanced smart contract automation, from governance participation to real-world asset tokenization - this SDK unlocks the complete power of the CirtusAI platform.

v0.2.1(beta)

## What Makes CirtusAI Unique

- Enterprise-Grade 2FA Security: Mandatory TOTP authentication with time-sync tolerance
- Smart Contract Agent Wallets: On-chain spending limits, whitelists, and automated rule enforcement  
- Multi-Chain Support: Ethereum, Polygon, Arbitrum, and more
- Email Integration: IMAP/SMTP and OAuth for seamless communication
- DAO Governance: Participate in on-chain voting and proposal management
- DeFi Integration: Swaps, yield farming, cross-chain bridges, and gas abstraction
- Real-World Assets (RWA): Tokenize and manage physical assets on-chain
- Compliance Built-In: KYC/AML, audit trails, and regulatory reporting
- Production Ready: Sync/async support, comprehensive error handling, and extensive testing

---

## Installation

Install the latest stable SDK:

```bash
pip install cirtusai-sdk
```

Install the beta/pre-release version:

```bash
pip install --pre cirtusai-sdk
```

---

## Command Line Interface

The SDK includes a powerful CLI for common tasks. After installing:

```bash
pip install cirtusai-sdk
```

Use the `cirtusai` command:

```bash
cirtusai --help
```

Available commands:

```bash
 cirtusai auth           Authentication (login, register, refresh, verify-2fa)
cirtusai agents         Agent management (list, get, create-child, delete, children, provision-email, provision-wallet, update-permissions, unlink)
cirtusai wallets        Wallet & email account management (list-assets, list-email, create-email, get-email, update-email, delete-email, refresh-email-token, add-crypto)
cirtusai identity       DID & credential management (get-did, issue-credential, verify-credential)
cirtusai governance     Governance (create-proposal, cast-vote, get-proposal-state)
cirtusai reputation     Soulbound token commands (issue-sbt, get-sbt-owner)
cirtusai bridge         Cross-chain bridge (get-quote, transfer)
cirtusai assets         Asset view (view, refresh)
cirtusai marketplace    Marketplace (create-listing, list-listings, get-listing, update-listing, cancel-listing, place-bid, list-bids, accept-bid)
cirtusai swap           Token swap (get-quote, execute, cancel)
cirtusai nfts           NFT management (list, get-metadata, mint, batch-transfer, burn)
cirtusai child-assets   Child asset management (list, get, create, update, delete)
cirtusai child-services Child service management (list)
```bash

---

## Quick Start Guide

### 1. Authentication with 2FA (Required)

Every CirtusAI application starts with secure authentication. First, import the client and error classes, then initialize the client with your backend URL:

```python
from cirtusai import CirtusAIClient
from cirtusai.auth import TwoFactorAuthenticationError

client = CirtusAIClient(base_url="http://localhost:8000")
```

Register a new user (automatic 2FA setup):

```python
setup_info = client.auth.register(
    username="mycompany_agent",
    email="admin@mycompany.com",
    password="SuperSecure123!",
    preferred_2fa_method="totp"
)
```

Save the QR code, secret, and backup codes provided for your authenticator app:

```python
print(f"Scan QR: data:image/png;base64,{setup_info.qr_code_image}")
print(f"Secret: {setup_info.secret}")
print(f"Backup codes: {setup_info.backup_codes}")
```

Login with 2FA using a current TOTP code:

```python
try:
    token = client.auth.login_with_2fa(
        "mycompany_agent",
        "SuperSecure123!",
        "123456"
    )
    client.set_token(token.access_token)
    print("Authenticated successfully!")
except TwoFactorAuthenticationError as e:
    print(f"2FA failed: {e}")
```

### 2. Create Your First Wallet

Create a new HD wallet:

```python
wallet = client.wallets.create_wallet(chain="ethereum")
print(f"New wallet: {wallet['wallet_address']}")
```

Import an existing wallet (provide your private key):

```python
imported = client.wallets.import_wallet(
    chain="ethereum",
    private_key="0x1234567890abcdef..."
)
print(f"Imported wallet: {imported['wallet_address']}")
```

List all your wallets:

```python
wallets = client.wallets.list_wallets()
for w in wallets:
    print(f"  {w['name']}: {w['wallet_address']} ({w['chain']})")
```

### 3. Deploy Your First Agent Wallet

Deploy a smart contract–based agent wallet:

```python
agent_wallet = client.wallets.deploy_agent_wallet()
print(f"Agent wallet deployed: {agent_wallet['wallet_address']}")
```

Set a daily ETH spending limit (in wei):

```python
tx_hash = client.wallets.set_spending_limit(
    address=agent_wallet['wallet_address'],
    token="0x0",
    amount=1000000000000000000,
    period=86400
)
print(f"Spending limit set: {tx_hash}")
```

Whitelist a trusted address for spending:

```python
whitelist_tx = client.wallets.update_whitelist(
    address=agent_wallet['wallet_address'],
    target="0x742d35Cc6634C0532925a3b8D0715a99C7DCF",
    allowed=True
)
print(f"Address whitelisted: {whitelist_tx}")
```

### 4. Manage Child Agents

List master agents

Create a child agent under a master agent

List all child agents

```python
agents = client.agents.list_agents()
print(f"Master agents: {agents}")

child = client.agents.create_child_agent("my_master_id", "assistant_bot")
print(f"Created child agent: {child['id']}")

children = client.agents.get_children()
print(f"Child agents: {children}")
```

---

## Complete Feature Guide

## 1. 🔐 Advanced Authentication & Security

### 1.1 Complete 2FA Management

Check current 2FA status

Setup 2FA for existing users

Get QR code as image bytes

Debug time synchronization issues

Disable 2FA (requires password + TOTP)

```python
status = client.auth.get_2fa_status()
print(f"2FA enabled: {status.is_2fa_enabled}")

setup = client.auth.setup_2fa()
print(f"New secret: {setup.secret}")

qr_bytes = client.auth.get_qr_code()
with open("qr_code.png", "wb") as f:
    f.write(qr_bytes)

debug_info = client.auth.debug_2fa()
print("Valid codes right now:")
for step, code in debug_info["valid_codes"].items():
    print(f"  {step}: {code}")

result = client.auth.disable_2fa(
    totp_code="123456",
    password="SuperSecure123!"
)
print(f"2FA disabled: {result['enabled']}")
```

### 1.2 Session Management

Get current user information

Refresh expired tokens

Logout and clear session

```python
user_info = client.auth.get_user_info()
print(f"User: {user_info['username']} ({user_info['email']})")

new_token = client.auth.refresh(refresh_token="your_refresh_token")
client.set_token(new_token.access_token)

client.auth.logout()
```

---

## 2. 💰 Comprehensive Wallet Management

### 2.1 Multi-Chain Wallet Operations

Create wallets on different chains

Get wallet balances

Get consolidated asset view across all chains

```python
eth_wallet = client.wallets.create_wallet(chain="ethereum")
poly_wallet = client.wallets.create_wallet(chain="polygon") 
arb_wallet = client.wallets.create_wallet(chain="arbitrum")

balance = client.wallets.get_balance(
    chain="ethereum",
    address=eth_wallet['wallet_address']
)
print(f"ETH Balance: {balance}")

assets = client.assets.get_multi_chain_asset_view()
print(f"Total portfolio value: ${assets['total_value_usd']}")
for chain, data in assets['chains'].items():
    print(f"  {chain}: {data['native_balance']} native + {len(data['tokens'])} tokens")
```

### 2.2 ERC-20 Token Management

Get token balance

Transfer tokens

Approve token spending

```python
usdc_balance = client.wallets.get_token_balance(
    wallet_id=eth_wallet['id'],
    token_address="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5"  # USDC
)
print(f"USDC: {usdc_balance['balance']} {usdc_balance['symbol']}")

transfer_tx = client.wallets.transfer_tokens(
    wallet_id=eth_wallet['id'],
    token_address="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",
    to_address="0x742d35Cc6634C0532925a3b8D0715a99C7DCF",
    amount=100.0
)
print(f"Transfer completed: {transfer_tx['tx_hash']}")

approve_tx = client.wallets.approve_tokens(
    wallet_id=eth_wallet['id'], 
    token_address="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",
    spender_address="0x1234567890abcdef...",
    amount=500.0
)
print(f"Approval set: {approve_tx['tx_hash']}")
```

---

## 3. 🤖 Agent Wallet Smart Contracts

### 3.1 Agent Wallet Deployment & Management

Deploy multiple agent wallets for different purposes

List all agent wallets

Get detailed wallet information

```python
marketing_agent = client.wallets.deploy_agent_wallet()
finance_agent = client.wallets.deploy_agent_wallet()
ops_agent = client.wallets.deploy_agent_wallet()

agent_wallets = client.wallets.list_agent_wallets()
for wallet in agent_wallets:
    print(f"Agent: {wallet['wallet_address']} (deployed: {wallet['created_at']})")

wallet_details = client.wallets.get_agent_wallet(
    address=marketing_agent['wallet_address']
)
print(f"Wallet details: {wallet_details}")
```

### 3.2 On-Chain Rule Management

Set daily spending limits for different tokens

ETH spending limit: 0.5 ETH per day

USDC spending limit: $1000 per day

Build a whitelist of approved addresses

Set transaction threshold requiring manual approval

```python
agent_addr = marketing_agent['wallet_address']

eth_limit = client.wallets.set_spending_limit(
    address=agent_addr,
    token="0x0",  # ETH
    amount=500000000000000000,  # 0.5 ETH in wei
    period=86400  # 24 hours
)

usdc_limit = client.wallets.set_spending_limit(
    address=agent_addr,
    token="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",  # USDC
    amount=1000000000,  # $1000 (6 decimals)
    period=86400
)

approved_vendors = [
    "0x742d35Cc6634C0532925a3b8D0715a99C7DCF",  # OpenAI API payments
    "0x8b3a92Ef6F66F79A7B7C4D8f9E2A1B5C3D7E9F",   # AWS payments  
    "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a"    # Partner agent
]

for vendor in approved_vendors:
    whitelist_tx = client.wallets.update_whitelist(
        address=agent_addr,
        target=vendor,
        allowed=True
    )
    print(f"✅ Whitelisted {vendor}: {whitelist_tx}")

threshold_tx = client.wallets.set_threshold(
    address=agent_addr,
    new_threshold=500  # Require approval for transactions > $500
)
print(f"Threshold set: {threshold_tx}")
```

### 3.3 Audit Trail & Event Monitoring

Get complete transaction history for an agent wallet

Monitor for specific event types

```python
transactions = client.wallets.list_wallet_transactions(
    address=agent_addr
)

print(f"Found {len(transactions)} events:")
for tx in transactions:
    print(f"  {tx['timestamp']}: {tx['event_name']}")
    print(f"    TX: {tx['tx_hash']}")
    print(f"    Details: {tx['details']}")
    print(f"    Block: {tx['block_number']}")
    print()

spending_events = [tx for tx in transactions if tx['event_name'] == 'SpendingLimitSet']
whitelist_events = [tx for tx in transactions if tx['event_name'] == 'WhitelistUpdated']

print(f"Spending limit changes: {len(spending_events)}")
print(f"Whitelist updates: {len(whitelist_events)}")
```

---

## 4. 👥 Master/Child Agent Management

### 4.1 Agent Hierarchy Creation

Create a master agent for your organization

Create specialized child agents

```python
master_agent = client.agents.create_agent(
    name="Marketing Master Agent",
    description="Handles all marketing automation",
    agent_type="master",
    capabilities=["content_creation", "social_media", "email_marketing"]
)
print(f"Master agent created: {master_agent['id']}")

social_media_agent = client.agents.create_agent(
    name="Social Media Specialist",
    description="Automated social media posting and engagement",
    agent_type="child",
    parent_id=master_agent['id'],
    capabilities=["social_media", "content_scheduling"]
)

email_agent = client.agents.create_agent(
    name="Email Campaign Manager", 
    description="Automated email marketing campaigns",
    agent_type="child",
    parent_id=master_agent['id'],
    capabilities=["email_marketing", "newsletter_automation"]
)

print(f"Child agents created:")
print(f"  Social Media: {social_media_agent['id']}")
print(f"  Email: {email_agent['id']}")
```

### 4.2 Agent Rule Inheritance

Child agents inherit rules from their master

```python
inherited_rules = client.agents.get_inherited_rules(
    child_id=social_media_agent['id']
)

print(f"Inherited rules from master:")
print(f"  Spending limits: {inherited_rules['spending_limits']}")
print(f"  Whitelists: {inherited_rules['whitelists']}")
print(f"  Policies: {inherited_rules['policies']}")
```

### 4.3 Task Delegation

Delegate specific tasks to child agents

Monitor delegation status

```python
social_campaign = client.agents.delegate_task(
    master_id=master_agent['id'],
    child_agent_id=social_media_agent['id'],
    task_type="social_media_campaign",
    budget_allocation={
        "token": "0x0",  # ETH
        "amount": "50000000000000000"  # 0.05 ETH
    },
    deadline="2025-07-24T12:00:00Z",
    parameters={
        "platform": "twitter",
        "campaign_theme": "product_launch",
        "post_frequency": "3_per_day"
    }
)
print(f"Task delegated: {social_campaign['id']}")

delegations = client.agents.list_delegations(master_agent['id'])
for delegation in delegations:
    print(f"Task: {delegation['task_type']} → {delegation['status']}")
```

---

## 5. 📧 Email Integration & Communication

### 5.1 Email Account Linking

Link IMAP/SMTP email account

OAuth integration for Google/Outlook (redirect-based)

List all linked email accounts

```python
email_account = client.wallets.create_email_account(
    provider="imap",
    email_address="marketing@mycompany.com",
    config={
        "host": "imap.gmail.com",
        "port": 993,
        "username": "marketing@mycompany.com", 
        "password": "app_password_here",  # Use app password for Gmail
        "use_ssl": True,
        "smtp_host": "smtp.gmail.com",
        "smtp_port": 587
    }
)
print(f"Email account linked: {email_account['id']}")

google_oauth_url = client.wallets.get_google_oauth_url()
print(f"Google OAuth: {google_oauth_url}")

email_accounts = client.wallets.list_email_accounts()
for account in email_accounts:
    print(f"  {account['email_address']} ({account['provider']})")
```

### 5.2 Email Management & Access

Test email connection

Access inbox (with proper permissions)

```python
test_result = client.wallets.test_email_connection(email_account['id'])
print(f"Connection test: {test_result['status']}")

inbox = client.wallets.get_inbox(
    account_id=email_account['id'],
    limit=10,
    unread_only=True
)
print(f"Unread emails: {inbox['unread_count']}")
for msg in inbox['messages']:
    print(f"  From: {msg['from']}")
    print(f"  Subject: {msg['subject']}")
    print(f"  Date: {msg['date']}")
```

---

## 6. 🌉 Cross-Chain Bridge & DeFi

### 6.1 Cross-Chain Transfers

Get bridge quote for cross-chain transfer

Execute the bridge transfer

```python
quote = client.bridge.get_quote(
    from_chain="ethereum", 
    to_chain="polygon",
    from_token="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",  # USDC
    to_token="0x2791bca1f2de4661ed88a30c99a7a9449aa84174",   # USDC on Polygon
    amount=1000000000  # $1000 USDC
)
print(f"Bridge quote:")
print(f"  Fee: ${quote['fee_usd']}")
print(f"  Time: {quote['estimated_time']}")
print(f"  You'll receive: {quote['to_amount']} USDC on Polygon")

if quote['fee_usd'] < 10:  # Acceptable fee
    bridge_tx = client.bridge.bridge_transfer(
        provider=quote['provider'],
        from_chain="ethereum",
        to_chain="polygon", 
        from_token="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",
        to_token="0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
        amount=1000000000,
        recipient_address=poly_wallet['wallet_address']
    )
    print(f"Bridge transfer initiated: {bridge_tx['tx_hash']}")
```

### 6.2 DeFi Integration

Swap tokens using integrated DEX

Deposit into yield farming vault

Check yield farming positions

```python
swap_tx = client.wallets.swap_tokens(
    wallet_id=eth_wallet['id'],
    from_token="0x0",  # ETH
    to_token="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",  # USDC
    amount=1.0,  # 1 ETH
    slippage_tolerance=0.5  # 0.5%
)
print(f"Swap completed: {swap_tx['tx_hash']}")

yield_deposit = client.wallets.deposit_yield_vault(
    wallet_id=eth_wallet['id'],
    vault_address="0x1234567890abcdef...",  # Aave USDC vault
    token_address="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",
    amount=500.0
)
print(f"Yield farming deposit: {yield_deposit['tx_hash']}")

positions = client.wallets.get_yield_positions(eth_wallet['id'])
for position in positions:
    print(f"Vault: {position['vault_name']}")
    print(f"  Deposited: {position['deposited_amount']}")
    print(f"  Current value: {position['current_value']}")
    print(f"  APY: {position['apy']}%")
```

### 6.3 On-Chain Swap Services

Get swap quote for token pair

Execute the swap

Cancel a pending swap quote

```python
swap_quote = client.swap.get_quote(
    from_token="0x0",  # ETH
    to_token="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",  # USDC
    amount=1.0
)
print(f"Swap quote: {swap_quote}")

swap_tx = client.swap.execute_swap(
    from_token="0x0",
    to_token="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",
    amount=1.0,
    slippage_tolerance=0.5
)
print(f"Swap executed: {swap_tx['tx_hash']}")

cancel = client.swap.cancel_swap(quote_id=swap_quote['quote_id'])
print(f"Swap quote cancelled: {cancel['status']}")
```

### 6.4 Marketplace Operations

List marketplace listings

Create a new listing

Place a bid on a listing

Cancel a listing

```python
listings = client.marketplace.list_listings(limit=20)
for l in listings:
    print(f"Listing: {l['id']} - {l['asset_name']} at {l['price']}")

new_listing = client.marketplace.create_listing(
    asset_id="asset123",
    price="0.5 ETH",
    quantity=1
)
print(f"Created listing: {new_listing['id']}")

bid = client.marketplace.place_bid(
    listing_id=new_listing['id'],
    bid_amount="0.45 ETH"
)
print(f"Bid placed: {bid['bid_id']}")

client.marketplace.cancel_listing(listing_id=new_listing['id'])
print("Listing cancelled")
```

---

## 7. 🏛️ Governance & DAO Participation

### 7.1 Proposal Management

Create a governance proposal

Get proposal details

```python
proposal = client.governance.create_proposal(
    targets=["0x1234567890abcdef..."],  # Contract to call
    values=[0],  # ETH to send (0 for parameter change)
    calldatas=["0xabcdef..."],  # Encoded function call
    description="Increase agent spending limits to $2000/day"
)
print(f"Proposal created: {proposal['proposal_id']}")

proposal_info = client.governance.get_proposal_state(proposal['proposal_id'])
print(f"Proposal status: {proposal_info['status']}")
print(f"Votes for: {proposal_info['votes_for']}")
print(f"Votes against: {proposal_info['votes_against']}")
print(f"Voting deadline: {proposal_info['voting_deadline']}")
```

### 7.2 Voting

Cast vote on proposal (1 = for, 0 = against)

Check your voting history

```python
vote = client.governance.cast_vote(
    proposal_id=proposal['proposal_id'],
    support=1  # Vote in favor
)
print(f"Vote cast: {vote['tx_hash']}")

voting_history = client.governance.get_user_votes()
for vote_record in voting_history:
    print(f"Proposal {vote_record['proposal_id']}: {'FOR' if vote_record['support'] else 'AGAINST'}")
```

---

## 8. 🏠 Real-World Assets (RWA)

### 8.1 Asset Tokenization

Register a real-world asset token

List your RWA holdings

```python
rwa_asset = client.wallets.register_rwa_asset(
    token_address="0x9876543210fedcba...",  # RWA token contract
    token_id="1",  # Specific asset ID
    metadata_uri="https://metadata.example.com/asset/1"
)
print(f"RWA asset registered: {rwa_asset['id']}")

rwa_holdings = client.wallets.list_rwa_assets()
for asset in rwa_holdings:
    print(f"Asset: {asset['name']}")
    print(f"  Type: {asset['asset_type']}")
    print(f"  Value: ${asset['estimated_value']}")
    print(f"  Yield: {asset['annual_yield']}%")
```

### 8.2 Asset Management

Transfer RWA tokens

```python
rwa_transfer = client.wallets.transfer_rwa(
    wallet_id=eth_wallet['id'],
    token_address="0x9876543210fedcba...",
    token_id="1",
    to_address="0x742d35Cc6634C0532925a3b8D0715a99C7DCF",
    amount=1
)
print(f"RWA transfer: {rwa_transfer['tx_hash']}")
```

---

## 9. 🎯 Child Asset Provisioning

### 9.1 Email Asset Provisioning

Provision email access to child agents

Check email quota usage

```python
email_provision = client.agents.provision_email_asset(
    child_id=email_agent['id'],
    email_account_id=email_account['id'],
    permissions=["read", "send"],
    quota={
        "daily_emails": 100,
        "monthly_emails": 2000
    }
)
print(f"Email access provisioned: {email_provision['email_address']}")

email_usage = client.agents.get_email_usage(email_agent['id'])
print(f"Email usage: {email_usage['used_today']}/{email_usage['daily_limit']}")
```

### 9.2 Wallet Asset Provisioning

Provision dedicated wallets for child agents

Transfer budget to child wallets

```python
child_eth_wallet = client.agents.provision_wallet_asset(
    child_id=social_media_agent['id'],
    chain="ethereum"
)
print(f"Child wallet created: {child_eth_wallet['wallet_address']}")

child_poly_wallet = client.agents.provision_wallet_asset(
    child_id=social_media_agent['id'],
    chain="polygon"
)
print(f"Child Polygon wallet: {child_poly_wallet['wallet_address']}")

budget_transfer = client.agents.transfer_assets_to_child(
    child_id=social_media_agent['id'],
    from_wallet=eth_wallet['wallet_address'],
    to_wallet=child_eth_wallet['wallet_address'],
    asset_type="eth",
    amount="100000000000000000",  # 0.1 ETH
    note="Monthly social media budget"
)
print(f"Budget transferred: {budget_transfer['transfer_id']}")
```

---

## 10. 💳 Fiat On/Off Ramps

### 10.1 Fiat Onboarding

Create fiat on-ramp session

Check on-ramp status

```python
onramp_session = client.wallets.create_onramp_session(
    currency="USD",
    amount=1000.0  # $1000
)
print(f"On-ramp session: {onramp_session['session_id']}")
print(f"Widget URL: {onramp_session['widget_url']}")

onramp_status = client.wallets.get_onramp_status(
    session_id=onramp_session['session_id']
)
print(f"Status: {onramp_status['status']}")
if onramp_status['status'] == 'completed':
    print(f"Received: {onramp_status['crypto_amount']} {onramp_status['crypto_currency']}")
```

---

## 11. ⛽ Gas Management & Abstraction

### 11.1 Gas Sponsorship

Deposit tokens for gas sponsorship

Check gas balance

Send gasless transaction using ERC-4337

```python
gas_deposit = client.wallets.sponsor_gas(
    token_address="0xA0b86a33E6D1cc22c435370bA9e4240EE8D5fE5",  # USDC
    amount=100.0  # $100 worth of gas
)
print(f"Gas sponsorship: {gas_deposit}")

gas_balance = client.wallets.get_gas_sponsorship_balance()
print(f"Gas balance: {gas_balance} USDC")

user_op = client.wallets.send_user_operation(
    user_op={
        "sender": agent_addr,
        "nonce": "0x0",
        "initCode": "0x",
        "callData": "0x...",  # Your transaction data
        "callGasLimit": "0x5208",
        "verificationGasLimit": "0x5208", 
        "preVerificationGas": "0x5208",
        "maxFeePerGas": "0x3b9aca00",
        "maxPriorityFeePerGas": "0x3b9aca00",
        "paymasterAndData": "0x",
        "signature": "0x"
    },
    entry_point_address="0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"
)
print(f"Gasless transaction: {user_op['user_op_hash']}")
```

---

## 12. 📊 Monitoring & Compliance

### 12.1 Transaction Monitoring

Start monitoring an address

Get transaction status

List all active watches

Retrieve recent alerts

```python
monitoring = client.monitoring.watch_address(
    address="0x742d35Cc6634C0532925a3b8D0715a99C7DCF",
    alert_conditions=["large_transaction", "new_contract_interaction"]
)
print(f"Monitoring started: {monitoring['watch_id']}")

tx_status = client.monitoring.get_transaction_status(
    tx_hash="0xabcdef1234567890..."
)
print(f"Transaction status: {tx_status['status']}")
print(f"Confirmations: {tx_status['confirmations']}")

watches = client.monitoring.list_watches()
for w in watches:
    print(f"Watch: {w['watch_id']} - {w['address']}")

alerts = client.monitoring.get_alerts()
for alert in alerts:
    print(f"Alert: {alert['alert_id']} - {alert['type']} at {alert['timestamp']}")
```

### 12.2 Compliance & Reporting

Check KYC status

Initiate KYC if needed

Generate compliance report

Get detailed audit trail for an entity

```python
kyc_status = client.compliance.get_kyc_status()
print(f"KYC Status: {kyc_status['status']}")

if kyc_status['status'] == 'not_verified':
    kyc_session = client.compliance.initiate_kyc()
    print(f"KYC session: {kyc_session['verification_url']}")

compliance_report = client.compliance.generate_report(
    start_date="2025-07-01",
    end_date="2025-07-17",
    report_type="full_audit"
)
print(f"Compliance report:")
print(f"  Total transactions: {compliance_report['total_transactions']}")
print(f"  Total value: ${compliance_report['total_value_usd']}")
print(f"  Flagged activities: {compliance_report['flagged_count']}")
print(f"  Compliance score: {compliance_report['compliance_score']}/100")

audit_trail = client.compliance.get_audit_trail(
    entity_id="entity123",
    entity_type="transaction"
)
print("Audit trail entries:")
for entry in audit_trail:
    print(f"  {entry['timestamp']}: {entry['action']} by {entry['performed_by']}")
```

---

## 13. 🔥 Advanced Features

### 13.1 NFT Management

List NFTs in wallet

Transfer NFT

Get metadata for a specific NFT

Mint a new NFT

Batch transfer multiple NFTs

Burn an NFT

```python
nfts = client.wallets.list_nfts(wallet_id=eth_wallet['id'])
for nft in nfts:
    print(f"{nft['name']} #{nft['token_id']}")
    print(f"  Collection: {nft['collection_name']}")
    print(f"  Value: ${nft['estimated_value']}")

nft_transfer = client.wallets.transfer_nft(
    wallet_id=eth_wallet['id'],
    contract_address="0x1234567890abcdef...",
    token_id="123", 
    to_address="0x742d35Cc6634C0532925a3b8D0715a99C7DCF"
)
print(f"NFT transferred: {nft_transfer['tx_hash']}")

metadata = client.nfts.get_nft_metadata(
    contract_address="0x1234567890abcdef...",
    token_id="123"
)
print(f"NFT Metadata: {metadata}")

minted = client.nfts.mint_nft(
    contract_address="0xNFTContract...",
    to_address="0x742d35Cc6634C0532925a3b8D0715a99C7DCF",
    metadata_uri="https://metadata.example.com/nft/1"
)
print(f"NFT minted: {minted['token_id']}")

batch = client.nfts.batch_transfer(
    contract_address="0x1234567890abcdef...",
    transfers=[
        {"token_id": "123", "to_address": "0xabc..."},
        {"token_id": "124", "to_address": "0xdef..."}
    ]
)
print("Batch transfer complete")

burn = client.nfts.burn_nft(
    contract_address="0x1234567890abcdef...",
    token_id="123"
)
print(f"NFT burned: {burn['status']}")
```

### 13.2 Event Subscriptions

Subscribe to wallet events

Get recent events

```python
subscription = client.wallets.subscribe_to_events(
    wallet_address=eth_wallet['wallet_address'],
    event_types=["transfer", "approval", "swap"]
)
print(f"Event subscription: {subscription['subscription_id']}")

events = client.wallets.get_wallet_events(
    wallet_address=eth_wallet['wallet_address'],
    limit=50
)
for event in events:
    print(f"{event['event_type']}: {event['details']}")
```

## 📚 Complete API Reference

### AuthClient

- `register(username, email, password, preferred_2fa_method="totp")` → `TwoFactorSetupResponse`
- `login(username, password)` → `Token | TwoFactorRequiredResponse`
- `login_with_2fa(username, password, totp_code)` → `Token`
- `verify_2fa(temporary_token, totp_code)` → `Token`
- `get_2fa_status()` → `TwoFactorStatusResponse`
- `setup_2fa()` → `TwoFactorSetupResponse`
- `confirm_2fa(totp_code)` → `dict`
- `disable_2fa(totp_code, password)` → `dict`
- `get_qr_code()` → `bytes`
- `debug_2fa()` → `dict`
- `refresh(refresh_token)` → `Token`
- `logout()` → `dict`

### WalletsClient

**Basic Wallet Operations:**

- `create_wallet(chain)` → `dict`
- `import_wallet(chain, private_key)` → `dict`
- `list_wallets()` → `List[dict]`
- `delete_wallet(wallet_id)` → `None`
- `get_balance(chain, address)` → `Decimal`

**Token Management:**

- `get_token_balance(wallet_id, token_address)` → `dict`
- `transfer_tokens(wallet_id, token_address, to_address, amount)` → `dict`
- `approve_tokens(wallet_id, token_address, spender_address, amount)` → `dict`

**Agent Wallets:**

- `deploy_agent_wallet()` → `dict`
- `list_agent_wallets()` → `List[dict]`
- `get_agent_wallet(address)` → `dict`
- `set_spending_limit(address, token, amount, period)` → `str`
- `update_whitelist(address, target, allowed)` → `str`
- `set_threshold(address, new_threshold)` → `str`
- `list_wallet_transactions(address)` → `List[dict]`

**DeFi Integration:**

- `swap_tokens(wallet_id, from_token, to_token, amount, slippage_tolerance)` → `dict`
- `deposit_yield_vault(wallet_id, vault_address, token_address, amount)` → `dict`
- `withdraw_yield_vault(wallet_id, vault_address, amount)` → `dict`
- `get_yield_positions(wallet_id)` → `List[dict]`

**Email Integration:**

- `list_email_accounts()` → `List[dict]`
- `create_email_account(provider, email_address, config)` → `dict`
- `test_email_connection(account_id)` → `dict`
- `get_inbox(account_id, limit=10, unread_only=False)` → `dict`

**Gas & Fees:**

- `sponsor_gas(token_address, amount)` → `str`
- `get_gas_sponsorship_balance()` → `Decimal`
- `send_user_operation(user_op, entry_point_address)` → `dict`

**Events & Monitoring:**

- `subscribe_to_events(wallet_address, event_types)` → `dict`
- `get_wallet_events(wallet_address, limit=50)` → `List[dict]`
- `unsubscribe_event(subscription_id)` → `None`

**RWA & NFTs:**

- `register_rwa_asset(token_address, token_id, metadata_uri)` → `dict`
- `list_rwa_assets()` → `List[dict]`
- `transfer_rwa(wallet_id, token_address, token_id, to_address, amount)` → `dict`
- `list_nfts(wallet_id)` → `List[dict]`
- `transfer_nft(wallet_id, contract_address, token_id, to_address)` → `dict`

**Fiat Integration:**

- `create_onramp_session(currency, amount)` → `dict`
- `get_onramp_status(session_id)` → `dict`

### AgentsClient

- `list_agents()` → `List[dict]`
- `create_agent(name, description, agent_type, parent_id=None, capabilities=[])` → `dict`
- `get_agent(agent_id)` → `dict`
- `update_agent(agent_id, **kwargs)` → `dict`
- `delete_agent(agent_id)` → `None`
- `get_inherited_rules(child_id)` → `dict`
- `delegate_task(master_id, child_agent_id, task_type, budget_allocation, deadline, parameters)` → `dict`
- `list_delegations(agent_id)` → `List[dict]`
- `provision_email_asset(child_id, email_account_id, permissions, quota)` → `dict`
- `provision_wallet_asset(child_id, chain)` → `dict`
- `transfer_assets_to_child(child_id, from_wallet, to_wallet, asset_type, amount, note)` → `dict`
- `get_email_usage(child_id)` → `dict`

### BridgeClient

- `get_quote(from_chain, to_chain, from_token, to_token, amount)` → `dict`
- `bridge_transfer(provider, from_chain, to_chain, from_token, to_token, amount, recipient_address)` → `dict`

### AssetsClient

- `get_multi_chain_asset_view()` → `dict`

### GovernanceClient

- `create_proposal(targets, values, calldatas, description)` → `dict`
- `cast_vote(proposal_id, support)` → `dict`
- `get_proposal_state(proposal_id)` → `dict`
- `get_user_votes()` → `List[dict]`

### ReputationClient

- `issue_sbt(to_address, metadata_uri)` → `dict`
- `get_sbt_owner(token_id)` → `dict`
- `get_user_reputation(user_id)` → `dict`
- `stake_reputation(amount)` → `dict`

### MonitoringClient

- `watch_address(address, alert_conditions)` → `dict`
- `get_transaction_status(tx_hash)` → `dict`
- `list_watches()` → `List[dict]`
- `get_alerts()` → `List[dict]`

### ComplianceClient

- `get_kyc_status()` → `dict`
- `initiate_kyc()` → `dict`
- `generate_report(start_date, end_date, report_type)` → `dict`
- `get_audit_trail(entity_id, entity_type)` → `List[dict]`

### SwapClient

- `get_quote(from_token, to_token, amount)` → `dict`
- `execute_swap(from_token, to_token, amount, slippage_tolerance)` → `dict`
- `cancel_swap(quote_id)` → `dict`

### MarketplaceClient

- `list_listings(limit=None)` → `List[dict]`
- `get_listing(listing_id)` → `dict`
- `create_listing(asset_id, price, quantity)` → `dict`
- `place_bid(listing_id, bid_amount)` → `dict`
- `cancel_listing(listing_id)` → `None`

### Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:

- Setting up the development environment
- Running tests and linting
- Submitting pull requests
- Code style guidelines

---

## 📋 Requirements

- **Python 3.8+**
- **requests** or **httpx** (for async support)
- **pydantic** for data validation
- **Authenticator app** (Google Authenticator, Authy, Microsoft Authenticator, etc.)

---

## 📈 What's New in July 2025

### 🔥 Latest Features

- ✅ **Complete Two-Factor Authentication** with TOTP and SMS support
- ✅ **Agent Smart Contract Wallets** with programmable on-chain rules  
- ✅ **Master/Child Agent Hierarchy** with rule inheritance
- ✅ **Multi-Chain Asset Aggregation** across 10+ blockchains
- ✅ **Advanced DeFi Integration** with yield farming and swaps
- ✅ **Real-World Asset Tokenization** for physical asset management
- ✅ **Gas Abstraction** with ERC-4337 support
- ✅ **Enhanced Compliance** with KYC/AML and audit trails
- ✅ **Email Integration** via IMAP/SMTP and OAuth
- ✅ **Cross-Chain Bridging** for seamless asset transfers

### 🎯 Coming Soon

- 🔜 **Advanced AI Agent Templates** for common use cases
- 🔜 **Mobile SDK** for iOS and Android
- 🔜 **WebSocket Support** for real-time events
- 🔜 **Advanced Analytics** with machine learning insights
- 🔜 **Layer 2 Optimizations** for faster, cheaper transactions

---

**Ready to build the future of autonomous AI agents? Install the CirtusAI SDK today and unlock the complete power of programmable, compliant, and secure AI automation!**

```bash
pip install cirtusai-sdk
```

Built with ❤️ by the CirtusAI team - Autonomy Verified
  
