Overview

Code examples for integrating ClawFirst MCP server with autonomous AI agents across multiple frameworks.

Quick Start

OpenClaw Python Integration

The fastest way to enable autonomous payments for your AI agent:

from openclaw import Agent
from clawfirst import X402Provider

# Configure agent with payment capabilities
agent = Agent(
    name="payment_assistant",
    providers=[
        X402Provider(
            network="mainnet-beta",
            wallet_path="~/.config/solana/agent.json",
            approval_policy={
                "auto_approve_threshold": "100 USDC",
                "daily_limit": "1000 USDC"
            }
        )
    ]
)

# Agent autonomously executes payments
result = agent.run("Pay the $250 invoice from Acme Corp using USDC")
print(f"Payment completed: {result.tx_signature}")

Standalone MCP Server

Run ClawFirst as a framework-agnostic MCP server:

# Launch MCP server
clawfirst serve \
  --network mainnet-beta \
  --wallet ~/.config/solana/agent.json \
  --port 3402

# Server exposes 6 MCP tools:
# ✓ x402.initialize_payment
# ✓ x402.authorize_transaction
# ✓ x402.verify_settlement
# ✓ x402.query_balance
# ✓ x402.estimate_fees
# ✓ x402.cancel_payment

Language-Specific Examples

Python (OpenClaw)

Complete OpenClaw integration examples including:

• Autonomous invoice settlement

• Treasury management agents

• Subscription payment handling

• Error handling and retry logic

JavaScript/TypeScript

LangChain and custom MCP client examples:

• Agent payment workflows

• React-based approval dashboards

• Real-time transaction monitoring

• Production deployment patterns

Rust

High-performance agent implementations:

• Async/await payment flows

• Concurrent transaction processing

• Low-latency MCP client

• Production monitoring

Common Integration Patterns

Pattern 1: Autonomous Invoice Processing

from openclaw import Agent
from clawfirst import X402Provider

agent = Agent(
    name="ap_agent",
    providers=[X402Provider(
        network="mainnet-beta",
        wallet_path="~/.config/solana/treasury.json",
        approval_policy={
            "auto_approve_threshold": "5000 USDC",
            "vendor_whitelist": ["[email protected]", "[email protected]"]
        }
    )]
)

def process_invoice(invoice):
    prompt = f"""
    Process this invoice:
    - Vendor: {invoice.vendor}
    - Amount: {invoice.amount}
    - Invoice ID: {invoice.id}

    Steps:
    1. Verify vendor is approved
    2. Check budget availability
    3. Execute payment using USDC
    4. Generate receipt
    """
    return agent.run(prompt)

Pattern 2: Treasury Management

agent = Agent(
    name="treasury_agent",
    providers=[X402Provider(
        network="mainnet-beta",
        wallet_path="~/.config/solana/treasury.json",
        approval_policy={
            "require_human_approval": True,
            "daily_limit": "50000 USDC"
        }
    )]
)

# Agent manages treasury operations
agent.run("""
Review current cash position and pay all outstanding invoices
under $1000 that are due within 7 days. For larger invoices,
request CFO approval before payment.
""")

Pattern 3: Subscription Management

from datetime import datetime, timedelta

agent = Agent(
    name="subscription_agent",
    providers=[X402Provider(
        network="mainnet-beta",
        wallet_path="~/.config/solana/subscriptions.json"
    )]
)

def renew_subscriptions():
    subscriptions = get_expiring_subscriptions(days=7)

    for sub in subscriptions:
        agent.run(f"""
        Renew subscription {sub.name} for ${sub.monthly_cost}.
        Verify renewal was successful and update our records.
        """)

Pattern 4: Multi-Agent Coordination

# Accounts Payable Agent
ap_agent = Agent(
    name="ap_agent",
    providers=[X402Provider(wallet_path="~/.config/solana/ap.json")]
)

# Accounts Receivable Agent
ar_agent = Agent(
    name="ar_agent",
    providers=[X402Provider(wallet_path="~/.config/solana/ar.json")]
)

# Treasury Agent coordinates both
treasury_agent = Agent(
    name="treasury_agent",
    providers=[X402Provider(wallet_path="~/.config/solana/treasury.json")]
)

# Coordinated workflow
treasury_agent.run("""
Check current cash position. If we have sufficient funds:
1. Ask AP agent to pay all approved invoices
2. Ask AR agent to send payment reminders for overdue invoices
3. Generate daily cash flow report
""")

Advanced Examples

Session-Based Transaction Management

from clawfirst import X402Provider

provider = X402Provider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/agent.json"
)

# Initialize payment session
session = await provider.call_tool('x402.initialize_payment', {
    'amount': '250 USDC',
    'recipient': '[email protected]',
    'purpose': 'Invoice #4291',
    'idempotency_key': 'invoice_4291_unique'
})

print(f"Session ID: {session.session_id}")
print(f"Expires at: {session.expires_at}")

# Authorize transaction
tx = await provider.call_tool('x402.authorize_transaction', {
    'session_id': session.session_id
})

print(f"Transaction signature: {tx.tx_signature}")

# Verify settlement
status = await provider.call_tool('x402.verify_settlement', {
    'tx_signature': tx.tx_signature
})

print(f"Settlement finalized: {status.finalized}")

Real-Time Transaction Monitoring

from clawfirst import X402WebSocket

ws = X402WebSocket('ws://localhost:3402/stream')

@ws.on('transaction.submitted')
def on_tx_submitted(event):
    print(f"Transaction submitted: {event.tx_signature}")
    notify_team(f"Payment initiated for {event.amount}")

@ws.on('transaction.confirmed')
def on_tx_confirmed(event):
    print(f"Transaction confirmed: {event.confirmations} blocks")

@ws.on('transaction.finalized')
def on_tx_finalized(event):
    print(f"Transaction finalized at block: {event.block_height}")
    update_accounting_system(event)

ws.connect()

Approval Workflow Integration

from clawfirst import X402Provider, PolicyViolationError

provider = X402Provider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/agent.json",
    approval_policy={
        "auto_approve_threshold": "1000 USDC",
        "require_human_approval": True,
        "approvers": ["[email protected]"]
    }
)

try:
    # Large payment requires approval
    result = await provider.call_tool('x402.authorize_transaction', {
        'session_id': session_id
    })
except PolicyViolationError as e:
    # Send approval request
    approval_token = await request_human_approval(
        amount=e.details['requested_amount'],
        approvers=e.details['approvers']
    )

    # Retry with approval
    result = await provider.call_tool('x402.authorize_transaction', {
        'session_id': session_id,
        'approval_token': approval_token
    })

Testing Examples

Development Environment Setup

# Generate test wallet
solana-keygen new --outfile ~/.config/solana/agent-test.json

# Fund with devnet SOL
solana airdrop 10 ~/.config/solana/agent-test.json --url devnet

# Launch MCP server on devnet
clawfirst serve \
  --network devnet \
  --wallet ~/.config/solana/agent-test.json \
  --port 3402

Integration Tests

import pytest
from openclaw import Agent
from clawfirst import X402Provider

@pytest.fixture
def test_agent():
    return Agent(
        name="test_agent",
        providers=[X402Provider(
            network="devnet",
            wallet_path="~/.config/solana/agent-test.json"
        )]
    )

async def test_payment_flow(test_agent):
    """Test complete payment workflow."""
    result = await test_agent.run(
        "Send 0.1 SOL to FVxP2R8AJoYbJD4kMjdjLWPFTPMxXYWd7fCMPyPPECYx"
    )

    assert result.success
    assert result.tx_signature is not None
    assert result.settlement_status == 'finalized'

async def test_policy_enforcement(test_agent):
    """Test approval policy enforcement."""
    result = await test_agent.run("Send 10000 USDC to vendor")

    assert result.status == 'pending_approval'
    assert result.requires_human_approval == True

Best Practices

1. Start on Devnet

Always test agent behavior on Solana devnet before mainnet deployment.

2. Implement Approval Policies

Never allow unrestricted autonomous spending. Configure multi-tier approval workflows.

3. Monitor Transaction Patterns

Set up alerting for anomalous agent behavior (velocity spikes, unusual amounts).

4. Use Idempotency Keys

Prevent duplicate payments with stable idempotency keys based on payment intent.

5. Enable Audit Logging

Maintain immutable audit trails for compliance and forensic analysis.

6. Test Failure Scenarios

Verify agent behavior during network failures, RPC timeouts, and policy violations.

7. Implement Circuit Breakers

Automatically suspend agents exhibiting suspicious transaction patterns.

8. Use HSM in Production

Never store production keys in file systems. Use hardware security modules.

Next Steps

Pick your language and explore detailed examples:

• Python (OpenClaw) - Recommended for most agent use cases

• JavaScript/TypeScript - LangChain and web-based agents

• Rust - High-performance production deployments

Additional Resources

• Getting Started - Initial setup and configuration

• MCP Tools - Complete API reference

• Authentication - Security architecture and best practices

• Error Handling - Fault tolerance patterns