Authentication

Claw402 implements a non-custodial security model where AI agents execute transactions without exposing private keys to agent context windows.

Security Architecture

Non-Custodial Design Principles

Claw402's security architecture ensures cryptographic keys never enter AI agent context:

1. Hardware Security Module (HSM) Isolation - Private keys stored in HSM-backed signing enclaves

2. Delegated Signing - Agents request signatures without accessing key material

3. Time-Bounded Delegation - Signing permissions expire after configurable durations

4. Multi-Party Approval - High-value transactions require human confirmation

Agent Wallet Configuration

Generating Agent Wallets

Create dedicated wallets for agent transaction signing:

# Solana mainnet wallet
solana-keygen new --outfile ~/.config/solana/agent-mainnet.json

# Development/testing wallet
solana-keygen new --outfile ~/.config/solana/agent-devnet.json

Securing Wallet Keypairs

Production Deployment Best Practices:

# Set restrictive file permissions
chmod 400 ~/.config/solana/agent-mainnet.json

# Store in HSM-backed vault (recommended for production)
aws kms create-key --description "Claw402 Agent Signing Key"

# Use environment-specific key storage
# Development: Local filesystem
# Staging: Cloud KMS
# Production: Hardware Security Module

OpenClaw Provider Configuration

Configure agent wallet through X402Provider:

from claw402 import X402Provider

# Development configuration (local wallet)
dev_provider = X402Provider(
    network="devnet",
    wallet_path="~/.config/solana/agent-devnet.json"
)

# Production configuration (HSM-backed)
prod_provider = X402Provider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/agent-mainnet.json",
    signing_service="hsm://production-signing-cluster",
    hsm_config={
        "provider": "aws-kms",
        "key_id": "arn:aws:kms:us-east-1:123456789012:key/abcd1234",
        "region": "us-east-1"
    }
)

Approval Policies

Policy Configuration

Approval policies define authorization rules for autonomous agent transactions:

approval_policy = {
    # Automatic approval for transactions below threshold
    "auto_approve_threshold": {
        "amount": 100,
        "currency": "USDC"
    },

    # Require human approval for high-value transactions
    "require_human_approval": True,
    "human_approval_threshold": {
        "amount": 1000,
        "currency": "USDC"
    },

    # Daily spending limits
    "daily_limit": {
        "amount": 5000,
        "currency": "USDC"
    },

    # Monthly spending caps
    "monthly_limit": {
        "amount": 50000,
        "currency": "USDC"
    },

    # Per-transaction maximum
    "per_transaction_max": {
        "amount": 10000,
        "currency": "USDC"
    },

    # Recipient whitelist
    "allowed_recipients": [
        "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
        "[email protected]"
    ],

    # Recipient blacklist (takes precedence over whitelist)
    "blocked_recipients": [
        "[email protected]"
    ],

    # Time-based restrictions
    "allowed_hours": {
        "start": "09:00",
        "end": "17:00",
        "timezone": "America/New_York"
    },

    # Circuit breaker configuration
    "circuit_breaker": {
        "max_failed_transactions": 3,
        "suspend_duration": "1 hour",
        "alert_channels": ["email", "slack"]
    }
}

Multi-Tier Approval Workflows

Implement graduated approval requirements based on transaction value:

multi_tier_policy = {
    "tiers": [
        {
            "name": "micropayments",
            "max_amount": "10 USDC",
            "auto_approve": True,
            "require_confirmation": False
        },
        {
            "name": "standard",
            "max_amount": "1000 USDC",
            "auto_approve": True,
            "require_confirmation": True,
            "confirmation_method": "email"
        },
        {
            "name": "elevated",
            "max_amount": "10000 USDC",
            "require_human_approval": True,
            "approvers": ["[email protected]"],
            "timeout": "24 hours"
        },
        {
            "name": "critical",
            "max_amount": "100000 USDC",
            "require_multisig": True,
            "approvers": [
                "[email protected]",
                "[email protected]",
                "[email protected]"
            ],
            "required_signatures": 2,
            "timeout": "48 hours"
        }
    ]
}

Policy Enforcement

Claw402 enforces approval policies at the signing service layer:

# Agent attempts payment
response = agent.run("Pay vendor $5000 for services")

# Claw402 policy engine evaluates transaction:
# 1. Check amount against tiers
# 2. Amount = $5000 → "elevated" tier
# 3. elevated tier requires human approval
# 4. Send approval request to [email protected]
# 5. Transaction pending until human confirms

# Human receives approval notification:
# Subject: Transaction Approval Required
# Amount: $5000 USDC
# Recipient: [email protected]
# Purpose: Payment for services
# Approve: https://claw402.xyz/approve/tx_abc123

MCP Server Authentication

Server-to-Agent Authentication

When running standalone MCP server, authenticate agent connections:

# Generate server API key
claw402 keys generate --output ~/.claw402/server-key.txt

# Launch server with authentication
claw402 serve \
  --network mainnet-beta \
  --wallet ~/.config/solana/agent.json \
  --port 3402 \
  --require-auth \
  --api-key-file ~/.claw402/server-key.txt

Agent Client Configuration

Configure agent to authenticate with MCP server:

from claw402 import X402Provider

provider = X402Provider(
    server_url="http://localhost:3402",
    api_key="sk_claw402_abc123...",
    network="mainnet-beta"
)

mTLS (Mutual TLS) Authentication

For production deployments, enable mutual TLS:

# Generate server certificate
openssl req -x509 -newkey rsa:4096 \
  -keyout server-key.pem \
  -out server-cert.pem \
  -days 365 -nodes

# Generate client certificate
openssl req -x509 -newkey rsa:4096 \
  -keyout client-key.pem \
  -out client-cert.pem \
  -days 365 -nodes

# Launch server with mTLS
claw402 serve \
  --tls-cert server-cert.pem \
  --tls-key server-key.pem \
  --client-ca client-cert.pem \
  --require-client-cert

Session Management

Transaction Sessions

Each payment operation creates a unique session with expiration:

# Initialize payment creates session
session = agent.call_tool("x402.initialize_payment", {
    "amount": "0.5 SOL",
    "recipient": "[email protected]"
})

# Session object contains:
{
    "session_id": "sess_x4k9j2n8p5",
    "expires_at": "2026-03-01T18:30:00Z",  # 30-minute TTL
    "status": "pending_authorization",
    "idempotency_key": "idem_abc123..."
}

Idempotency

Prevent duplicate transactions using idempotency keys:

# Agent retries failed request with same idempotency key
response1 = agent.call_tool("x402.authorize_transaction", {
    "session_id": "sess_x4k9j2n8p5",
    "idempotency_key": "idem_abc123"
})

# Network error, agent retries
response2 = agent.call_tool("x402.authorize_transaction", {
    "session_id": "sess_x4k9j2n8p5",
    "idempotency_key": "idem_abc123"  # Same key
})

# Claw402 returns cached response, no duplicate transaction
assert response1.tx_signature == response2.tx_signature

Audit Logging

Transaction Audit Trails

Claw402 maintains immutable audit logs for all agent transactions:

# Enable comprehensive audit logging
provider = X402Provider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/agent.json",
    audit_config={
        "enabled": True,
        "log_level": "detailed",
        "log_destination": "s3://company-audit-logs/claw402/",
        "retention_days": 2555,  # 7 years for compliance
        "include_context": True  # Log agent prompts/responses
    }
)

Audit Log Format

Audit logs contain complete transaction context:

{
  "timestamp": "2026-03-01T17:45:23.123Z",
  "event_type": "transaction.authorized",
  "session_id": "sess_x4k9j2n8p5",
  "agent_id": "agent_payment_assistant",
  "transaction": {
    "tx_signature": "5j7s...",
    "amount": "250 USDC",
    "recipient": "[email protected]",
    "purpose": "Invoice payment INV-2026-001"
  },
  "approval": {
    "policy_tier": "standard",
    "auto_approved": true,
    "human_approver": null,
    "approval_timestamp": "2026-03-01T17:45:22.456Z"
  },
  "context": {
    "agent_prompt": "Pay the invoice from Acme Corp for $250",
    "tool_parameters": { "amount": "250 USDC", "recipient": "[email protected]" }
  },
  "security": {
    "signing_service": "hsm://production-cluster",
    "ip_address": "10.0.1.42",
    "user_agent": "claw402-python/1.0.0"
  }
}

Security Best Practices

1. Key Rotation

Rotate agent wallet keys periodically:

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

# Migrate funds to new wallet
solana transfer NEW_ADDRESS ALL --from OLD_KEYPAIR

# Update agent configuration
# Delete old keypair after migration confirmation

2. Least Privilege Principle

Grant agents minimum required permissions:

# Good: Restrictive policy
restrictive_policy = {
    "auto_approve_threshold": "10 USDC",
    "daily_limit": "100 USDC",
    "allowed_recipients": ["[email protected]"]
}

# Bad: Permissive policy
permissive_policy = {
    "auto_approve_threshold": "1000000 USDC",  # Too high
    "daily_limit": None,  # No limit
    "allowed_recipients": None  # Any recipient
}

3. Anomaly Detection

Enable automated anomaly detection:

anomaly_config = {
    "enabled": True,
    "rules": [
        {
            "name": "velocity_check",
            "condition": "transactions_per_hour > 100",
            "action": "suspend_agent"
        },
        {
            "name": "amount_spike",
            "condition": "transaction_amount > 3 * daily_average",
            "action": "require_human_approval"
        },
        {
            "name": "unusual_recipient",
            "condition": "recipient not in historical_recipients",
            "action": "flag_for_review"
        }
    ]
}

4. Network Segmentation

Isolate agent signing infrastructure:

Production Architecture:

┌─────────────────┐
│   Agent Runtime │
│  (Public Cloud) │
└────────┬────────┘
         │ MCP Protocol (TLS)
         │
┌────────▼────────┐
│   MCP Server    │
│  (Private VPC)  │
└────────┬────────┘
         │ Internal Only
         │
┌────────▼────────┐
│ Signing Service │
│  (HSM Cluster)  │
│  (Isolated VPC) │
└─────────────────┘

Testing Authentication

Verify Agent Wallet

Test wallet configuration:

# Check wallet balance
solana balance ~/.config/solana/agent.json

# Verify network connectivity
solana cluster-version

# Test signing (devnet)
solana transfer \
  --from ~/.config/solana/agent-devnet.json \
  RECIPIENT_ADDRESS 0.001 \
  --url devnet

Validate Approval Policies

Test policy enforcement:

# Attempt transaction below threshold (should auto-approve)
small_tx = agent.run("Send 5 USDC to [email protected]")
assert small_tx.auto_approved == True

# Attempt transaction above threshold (should require approval)
large_tx = agent.run("Send 5000 USDC to [email protected]")
assert large_tx.requires_approval == True
assert large_tx.status == "pending_human_approval"

Authentication Errors

Common Error Codes

Code	Description	Resolution
INVALID_WALLET	Wallet keypair invalid or inaccessible	Verify wallet file path and permissions
INSUFFICIENT_BALANCE	Agent wallet has insufficient funds	Add funds to agent wallet
POLICY_VIOLATION	Transaction violates approval policy	Adjust transaction or update policy
APPROVAL_TIMEOUT	Human approval not received within timeout	Request approval re-submission
SESSION_EXPIRED	Transaction session TTL exceeded	Re-initialize payment session
SIGNATURE_FAILED	HSM signing operation failed	Check HSM connectivity and credentials

Error Handling Example

from claw402 import X402Error, PolicyViolationError

try:
    response = agent.run("Pay vendor $50000")
except PolicyViolationError as e:
    print(f"Transaction blocked: {e.policy_name}")
    print(f"Reason: {e.violation_reason}")
    print(f"Required approval: {e.approvers}")
except X402Error as e:
    print(f"Transaction failed: {e.code}")
    print(f"Message: {e.message}")

WebSocket Authentication

For real-time transaction monitoring, WebSocket connections require authentication:

from claw402 import X402WebSocket

ws = X402WebSocket(
    url='wss://api.claw402.xyz/stream',
    api_key='sk_claw402_abc123...',
    agent_id='agent_payment_assistant'
)

ws.connect()

See WebSocket API for complete documentation.