Getting Started

This guide demonstrates how to enable AI agents to execute autonomous x402 transactions using Claw402's MCP-native architecture.

Prerequisites

Before integrating Claw402, ensure you have:

• AI Agent Framework - OpenClaw, LangChain, AutoGPT, or custom MCP-compatible agent runtime

• Solana Wallet - Agent wallet keypair for transaction signing (generated during setup)

• Node.js 18+ or Python 3.9+ - Required for MCP server runtime

• Basic MCP Knowledge - Familiarity with Model Context Protocol (optional but recommended)

What We're Building

This guide covers three integration approaches:

1. OpenClaw Native Integration - Drop-in Python provider for OpenClaw agents (recommended)

2. Standalone MCP Server - Framework-agnostic server for any MCP-compatible agent

3. REST API Proxy - HTTP wrapper for non-MCP environments

Installation

Option 1: OpenClaw Native Provider (Recommended)

Install the Claw402 provider for OpenClaw agents:

pip install claw402-openclaw

Option 2: Standalone MCP Server

Install the global MCP server:

# Using npm
npm install -g @claw402/mcp-server

# Using pip
pip install claw402-mcp

Option 3: Docker Deployment

Run Claw402 as a containerized service:

docker pull claw402/mcp-server:latest
docker run -d -p 3402:3402 \
  -v ~/.config/solana:/wallet \
  claw402/mcp-server

Setup: Generate Agent Wallet

Create a dedicated wallet for your agent's transaction signing:

# Using Solana CLI
solana-keygen new --outfile ~/.config/solana/agent.json

# Fund the wallet (testnet for development)
solana airdrop 2 ~/.config/solana/agent.json --url devnet

Security Note: Store agent wallet keypairs securely. For production deployments, use hardware security modules (HSM) or key management services.

Quick Start: OpenClaw Integration

Step 1: Configure Agent with X402Provider

from openclaw import Agent
from claw402 import X402Provider

# Instantiate agent with x402 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",
                "require_human_approval": True,
                "daily_limit": "1000 USDC"
            }
        )
    ]
)

Step 2: Execute Autonomous Payments

# Agent autonomously executes payment based on natural language
response = agent.run(
    "Pay the invoice from Acme Corp for $250 using USDC"
)

print(f"Transaction signature: {response.tx_signature}")
print(f"Settlement status: {response.settlement_status}")

Step 3: Verify Settlement

# Query transaction confirmation status
status = agent.run(
    "Check if the Acme Corp payment has been confirmed"
)

print(f"Confirmations: {status.confirmations}")
print(f"Finalized: {status.finalized}")

Quick Start: Standalone MCP Server

Step 1: Launch MCP Server

claw402 serve \
  --network mainnet-beta \
  --rpc-url https://api.mainnet-beta.solana.com \
  --wallet ~/.config/solana/agent.json \
  --port 3402 \
  --approval-policy-file ./approval-policy.json

approval-policy.json:

{
  "auto_approve_threshold": {
    "amount": 100,
    "currency": "USDC"
  },
  "require_human_approval": true,
  "daily_limit": {
    "amount": 1000,
    "currency": "USDC"
  },
  "allowed_recipients": [
    "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
  ]
}

Step 2: Connect Agent to MCP Server

Configure your agent runtime to connect to the Claw402 MCP server:

// LangChain example
import { MCPClient } from '@langchain/mcp';

const mcpClient = new MCPClient({
  serverUrl: 'http://localhost:3402',
  tools: [
    'x402.initialize_payment',
    'x402.authorize_transaction',
    'x402.verify_settlement',
    'x402.query_balance',
    'x402.estimate_fees',
    'x402.cancel_payment'
  ]
});

const agent = new Agent({
  tools: mcpClient.getTools()
});

Step 3: Execute Payment via MCP Tools

Agents call MCP tools using JSON schema:

{
  "tool": "x402.initialize_payment",
  "parameters": {
    "amount": "0.5 SOL",
    "recipient": "[email protected]",
    "purpose": "API subscription renewal",
    "settlement_constraint": "immediate"
  }
}

Server Response:

{
  "session_id": "sess_x4k9j2n8p5",
  "payment_address": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "expires_at": "2026-03-01T18:30:00Z",
  "status": "pending_authorization"
}

MCP Tool Suite Reference

Claw402 exposes six core tools for agent transaction execution:

Tool	Purpose	Input Parameters	Output
x402.initialize_payment	Create payment session	amount, recipient, memo	session_id, payment_address
x402.authorize_transaction	Sign and submit transaction	session_id, approval_token	tx_signature, status
x402.verify_settlement	Confirm blockchain finality	tx_signature	confirmations, settlement_state
x402.query_balance	Retrieve wallet balances	address (optional)	balances[]
x402.estimate_fees	Calculate transaction costs	amount, priority	network_fee, total_cost
x402.cancel_payment	Abort pending transaction	session_id	cancellation_receipt

Production Example: Autonomous Invoice Settlement

This example demonstrates an accounts payable agent that processes incoming invoices autonomously:

from openclaw import Agent
from claw402 import X402Provider

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

# Agent processes invoice autonomously
def process_invoice(invoice_data):
    prompt = f"""
    Process this invoice:
    - Vendor: {invoice_data['vendor']}
    - Amount: {invoice_data['amount']}
    - Invoice ID: {invoice_data['invoice_id']}

    Steps:
    1. Verify vendor is on approved list
    2. Check amount is within budget
    3. Execute payment using USDC
    4. Generate payment receipt
    """

    result = agent.run(prompt)
    return result

# Example usage
invoice = {
    "vendor": "[email protected]",
    "amount": "2500 USDC",
    "invoice_id": "INV-2026-001"
}

receipt = process_invoice(invoice)
print(f"Payment completed: {receipt.tx_signature}")

Security Best Practices

1. Key Management

Never expose private keys in agent context windows. Use Claw402's signing service isolation:

# Good: Keys stored in HSM-backed service
provider = X402Provider(
    wallet_path="~/.config/solana/agent.json",
    signing_service="hsm://production-signing-cluster"
)

# Bad: Keys in agent-accessible location
provider = X402Provider(
    wallet_path="/tmp/insecure-key.json"  # Don't do this
)

2. Approval Policies

Implement multi-tier approval workflows for high-value transactions:

approval_policy = {
    "tiers": [
        {
            "threshold": "100 USDC",
            "auto_approve": True
        },
        {
            "threshold": "1000 USDC",
            "require_human_approval": True,
            "approvers": ["[email protected]"]
        },
        {
            "threshold": "10000 USDC",
            "require_multisig": True,
            "approvers": ["[email protected]", "[email protected]"],
            "required_signatures": 2
        }
    ]
}

3. Transaction Limits

Configure daily/monthly spending caps:

limits = {
    "daily_limit": "5000 USDC",
    "monthly_limit": "50000 USDC",
    "per_transaction_max": "10000 USDC"
}

4. Anomaly Detection

Enable circuit breakers for suspicious transaction patterns:

circuit_breaker = {
    "max_failed_transactions": 3,
    "suspend_duration": "1 hour",
    "alert_email": "[email protected]"
}

Monitoring and Debugging

Enable Verbose Logging

claw402 serve \
  --network mainnet-beta \
  --wallet ~/.config/solana/agent.json \
  --log-level debug \
  --log-file /var/log/claw402/agent-transactions.log

WebSocket Transaction Monitoring

Subscribe to real-time transaction events:

from claw402 import X402WebSocket

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

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

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

ws.connect()

What's Next?

• MCP Tool Reference - Complete tool schema documentation

• OpenClaw Examples - Advanced integration patterns

• Security Guide - Non-custodial architecture deep dive

• Error Handling - Fault tolerance and recovery strategies

• Production Deployment - Scaling and SLA considerations

Quick Tips

1. Start on Devnet - Test agent behavior on Solana devnet before mainnet deployment

2. Implement Approval Policies - Never allow unrestricted autonomous spending

3. Monitor Transaction Patterns - Set up alerting for anomalous agent behavior

4. Use Idempotency Tokens - Prevent duplicate payments with unique session IDs

5. Enable Circuit Breakers - Automatically suspend agents exhibiting suspicious patterns

6. Log All Transactions - Maintain immutable audit trails for compliance

How It Works

1. Agent receives instruction → Natural language payment intent (e.g., "Pay invoice for $250")

2. Claw402 MCP tool invoked → x402.initialize_payment called with parsed parameters

3. Approval workflow executed → Policy engine checks thresholds and requires human confirmation if needed

4. Transaction signed → HSM-backed signing service creates cryptographic signature (keys never enter agent context)

5. x402 protocol execution → Transaction submitted to blockchain with settlement verification

6. Confirmation streamed → Agent receives settlement status update via MCP response

Claw402 abstracts all blockchain complexity, enabling agents to execute payments using the same natural language interface they use for other tasks.