Introduction

MCP server enabling autonomous AI agents to execute cryptocurrency transactions on the x402 protocol.

What is ClawFirst?

ClawFirst is a Model Context Protocol (MCP) server that transforms AI agents into economic actors capable of initiating, authorizing, and settling cryptocurrency payments without human intervention. By exposing x402 payment primitives as callable MCP tools, ClawFirst eliminates the complexity agents face when interacting with blockchain infrastructure.

Rather than forcing agents to understand cryptographic signing, transaction lifecycle management, or blockchain state synchronization, ClawFirst provides six high-level tools that align with natural language instruction processing:

x402.initialize_payment    → Create payment session with recipient and amount
x402.authorize_transaction → Sign and submit transaction to blockchain
x402.verify_settlement     → Confirm payment finality on-chain
x402.query_balance        → Retrieve current wallet balances
x402.estimate_fees        → Calculate transaction costs before execution
x402.cancel_payment       → Abort pending payment session

Agents describe payment intent using natural language parameters. ClawFirst handles all protocol-level execution—cryptographic signing, nonce management, settlement verification, and state synchronization—autonomously.

What is x402?

x402 is an open payment protocol that leverages the HTTP 402 Payment Required status code to facilitate cryptocurrency payments through standard HTTP requests. The protocol enables:

• HTTP-native payments - Payments integrated directly into HTTP request/response flows

• Cryptographic verification - On-chain settlement with blockchain finality guarantees

• Machine-to-machine transactions - Purpose-built for autonomous agent payment operations

• Protocol-level standardization - Consistent payment semantics across implementations

• Flexible settlement - Support for micropayments to large-value transactions

ClawFirst implements the x402 protocol specification, providing agents with production-grade payment infrastructure optimized for autonomous operation.

Why Agents Need ClawFirst

Modern AI agents operate in economic environments—processing invoices, managing subscriptions, executing trades, and handling service payments. Existing blockchain infrastructure presents critical barriers to autonomous operation:

Problem: Cognitive Overhead Agents must maintain blockchain state, manage nonces, calculate gas fees, and handle transaction confirmation logic within limited context windows.

ClawFirst Solution: Declarative Semantics Agents describe intent ("Pay invoice #402 for $250 USDC"), ClawFirst executes protocol details autonomously.

Problem: Security Risk Direct private key access exposes agent systems to catastrophic compromise if context is leaked or poisoned.

ClawFirst Solution: HSM-Backed Signing Private keys never enter agent context. Hardware security modules handle all signing operations in isolation.

Problem: Protocol Complexity Each blockchain requires different transaction construction, signing algorithms, and settlement verification.

ClawFirst Solution: x402 Abstraction Single protocol interface works across all supported networks. No blockchain-specific logic required.

Problem: Non-Idempotent Operations Network failures during payment execution can result in double-spends or lost funds.

ClawFirst Solution: Session Management Payment sessions with 15-minute TTL provide automatic deduplication and retry safety.

Quick Start

Enable your AI agent to transact in three steps:

1. Install ClawFirst

npm install -g @clawfirst/mcp-server
# or
pip install clawfirst-mcp

2. Launch MCP Server

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

3. Connect Your Agent

from openclaw import Agent
from clawfirst import X402Provider

agent = Agent(
    name="payment_agent",
    providers=[X402Provider(port=3402)]
)

# Agent now has autonomous payment capabilities
result = agent.run("Send 0.5 SOL to [email protected]")

Architecture Overview

ClawFirst implements a three-layer architecture separating agent intent, protocol execution, and blockchain settlement:

┌─────────────────────────────────────────────────────────────┐
│                     Agent Layer                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  OpenClaw Agent                                       │   │
│  │  "Pay invoice #402 from Acme Corp for $250 USDC"    │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Tool Call
                         │ x402.initialize_payment()
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   ClawFirst MCP Server                       │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Intent Parser                                        │   │
│  │  • Extract amount, recipient, currency               │   │
│  │  • Validate approval policies                        │   │
│  │  • Generate session ID for idempotency              │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Transaction Builder                                  │   │
│  │  • Construct x402 payment proof                      │   │
│  │  • Calculate optimal gas parameters                  │   │
│  │  • Attach settlement constraints                     │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Signing Service (HSM-backed)                        │   │
│  │  • Isolated private key storage                      │   │
│  │  • Hardware-enforced signing operations              │   │
│  │  • Time-bounded delegation tokens                    │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Settlement Monitor                                   │   │
│  │  • WebSocket subscription to blockchain events       │   │
│  │  • Confirmation depth tracking                       │   │
│  │  • Finality verification                             │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │ Signed Transaction
                         │ via x402 Protocol
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   Blockchain Layer                           │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Solana Network (mainnet-beta)                       │   │
│  │  • Transaction submission via RPC                    │   │
│  │  • On-chain settlement verification                  │   │
│  │  • Cryptographic proof validation                    │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Documentation Structure

Core Documentation

• Getting Started - MCP server setup, wallet generation, and first transaction

• Authentication - HSM-backed signing architecture and approval policies

• Rate Limits - Transaction throughput limits and quota management

• Error Handling - Fault tolerance patterns and recovery strategies

API Reference

• MCP Tools - Complete tool suite with request/response schemas

• Transaction Streams - WebSocket real-time settlement monitoring

• API Overview - Integration patterns and authentication

Examples

• Python (OpenClaw) - OpenClaw agent integration examples

• JavaScript/TypeScript - LangChain and custom MCP client examples

• Rust - High-performance agent implementations

• Examples Overview - Integration patterns across frameworks

Resources

• FAQ - Common questions and troubleshooting

• Support - Contact information and issue reporting

Key Features

MCP-Native Architecture

Purpose-built Model Context Protocol server exposing x402 payment primitives as callable tools. No generic blockchain SDK complexity.

Declarative Transaction Semantics

Agents describe payment intent using natural language parameters. ClawFirst translates intent to protocol execution.

Non-Custodial Security

Private keys isolated in hardware security modules. Keys never enter agent context windows or LLM memory.

Idempotent Operations

Automatic transaction deduplication prevents double-spends. Network retry safety built into session management.

Approval Policy Engine

Multi-tier spending controls with automatic approval thresholds, human confirmation workflows, and multi-signature coordination.

Real-Time Settlement Monitoring

WebSocket streams provide instant transaction status updates for reactive agent workflows.

OpenClaw Integration

Drop-in Python provider for OpenClaw agents with zero configuration required.

Production-Grade Reliability

99.9% uptime SLA with geographic redundancy, automatic failover, and comprehensive observability.

Use Cases

Autonomous Invoice Processing

Accounts payable agents that process vendor invoices, verify payment terms, and execute settlements autonomously.

SaaS Subscription Management

Agents that monitor service subscriptions, process renewals, and handle payment failures without human intervention.

Treasury Operations

Treasury management agents that optimize cash positions, execute trades, and rebalance portfolios based on market conditions.

Service Micropayments

AI agents that purchase API access, compute resources, or data services using micropayment streams.

Multi-Agent Marketplaces

Autonomous agents that negotiate services, establish escrows, and settle payments with other agents.

Security Model

ClawFirst implements defense-in-depth security architecture:

1. HSM-Backed Signing - Private keys never enter MCP server memory space

2. Approval Policies - Multi-tier spending controls with human confirmation workflows

3. Session Isolation - Payment sessions expire after 15 minutes with automatic cleanup

4. Audit Logging - Immutable transaction logs for compliance and forensics

5. Circuit Breakers - Automatic suspension of agents exhibiting anomalous behavior

6. Rate Limiting - Transaction throttling prevents spam and resource exhaustion

See Authentication for detailed security architecture.

Production Requirements

Infrastructure

• Node.js 18+ or Python 3.9+ runtime

• 512MB RAM minimum (1GB recommended for high-throughput deployments)

• Persistent storage for session state (Redis or PostgreSQL)

• HSM or key management service for signing operations

• Solana RPC endpoint (QuickNode, Alchemy, or self-hosted validator)

Network Configuration

• Outbound HTTPS to Solana RPC (port 443)

• Outbound WebSocket to Solana RPC (port 443)

• Inbound HTTP for MCP tool calls (configurable port, default 3402)

• Optional: Inbound WebSocket for agent status subscriptions

Security Considerations

• Never expose MCP server directly to public internet

• Run behind agent authentication layer (mTLS, JWT, or API keys)

• Isolate signing service in separate network segment or HSM

• Implement rate limiting to prevent transaction spam

• Enable audit logging for all payment operations

x402 Protocol Resources

• x402 Protocol: x402.org

• x402 Documentation: x402.gitbook.io

• x402 on Twitter: @x402protocol

Support

• Documentation Issues: GitHub Issues

• Twitter: @clawfirstdotxyz

• Website: clawfirst.xyz

• Email: [email protected]

---

Built for autonomous agents. Optimized for x402. Designed for production.