Payment infrastructure for autonomous AI agents
ClawFirst is a Model Context Protocol (MCP) server that enables AI agents to execute cryptocurrency transactions on the x402 protocol. By exposing payment primitives as callable MCP tools, ClawFirst transforms agents into first-class economic actors capable of initiating, authorizing, and settling payments without human intervention.
ClawFirst serves as a protocol translation layer between autonomous AI agents and blockchain payment infrastructure. Rather than forcing agents to understand cryptographic primitives, transaction lifecycle management, or blockchain state synchronization, ClawFirst provides high-level, declarative payment semantics that align with natural language instruction processing.
Modern AI agents operate in economic environments—processing invoices, managing subscriptions, executing trades, and handling service payments. However, existing blockchain infrastructure presents critical barriers:
- Cognitive Overhead - Agents must maintain blockchain state, manage nonces, calculate gas fees, and handle transaction confirmation logic within limited context windows
- Security Risk - Direct private key access exposes agent systems to catastrophic compromise if context is leaked or poisoned
- Protocol Complexity - Each blockchain network requires different transaction construction, signing algorithms, and settlement verification approaches
- Non-Idempotent Operations - Network failures during payment execution can result in double-spends or lost funds without careful deduplication
- Lack of Native Tooling - Generic blockchain SDKs are designed for human developers, not autonomous agent decision-making
ClawFirst eliminates these barriers through purpose-built MCP tooling that abstracts payment complexity behind six core operations:
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.
Enable your AI agent to transact in three steps:
npm install -g @clawfirst/mcp-server
# or
pip install clawfirst-mcpclawfirst serve \
--network mainnet-beta \
--wallet ~/.config/solana/agent.json \
--port 3402from 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 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin")
print(f"Payment completed: {result.tx_signature}")Private keys never enter the MCP server's memory space. Signing operations execute in isolated hardware security modules (HSM):
- HSM-Backed Signing - Private keys isolated in secure enclaves
- Delegation Tokens - Time-bounded authorization without key exposure
- Proof-Based Execution - Agents provide payment proofs, not private keys
Payment sessions with 15-minute TTL guarantee idempotent transaction execution:
- Automatic Deduplication - Same parameters return existing session rather than creating duplicate transactions
- Network Retry Safety - Agent retries due to timeout return original payment state
- Context Window Protection - Prevents double-spending when agents "forget" pending payments
Programmable spending controls with threshold-based approval workflows:
- Auto-Approve Tiers - Automatic execution for small-value transactions
- Human-in-the-Loop - Approval dashboard for high-value payments
- Multi-Signature Coordination - N-of-M approval for treasury operations
- Vendor Whitelisting - Restrict payments to approved recipients
- Spending Limits - Daily, weekly, and monthly caps per agent
WebSocket streams provide agents with live transaction updates:
- Confirmation Tracking - Real-time confirmation depth updates
- Settlement Constraints - Configurable finality (immediate, next_block, final)
- Finality Verification - Cryptographic proof of settlement on-chain
- Sub-Second Latency - Average settlement verification under 400ms
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 → Transaction Builder → │ │
│ │ HSM Signing Service → Settlement Monitor │ │
│ └─────────────────────┬─────────────────────────────┘ │
└────────────────────────┼────────────────────────────────┘
│ Signed Transaction
│ via x402 Protocol
▼
┌─────────────────────────────────────────────────────────┐
│ Solana Network │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Transaction Submission → Confirmation → │ │
│ │ Finality (32 confirmations) │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Intent Parser
- Extracts amount, recipient, and currency from natural language
- Validates approval policies and spending limits
- Generates session ID for idempotency guarantees
Transaction Builder
- Constructs x402 payment proofs with cryptographic signatures
- Calculates optimal gas parameters for network conditions
- Attaches settlement constraints (immediate, next_block, final)
HSM Signing Service
- Isolated private key storage in hardware security modules
- Hardware-enforced signing operations with delegation tokens
- Time-bounded authorization without key exposure
Settlement Monitor
- WebSocket subscription to blockchain confirmation events
- Confirmation depth tracking and finality verification
- Real-time status broadcasts to connected agents
This monorepo contains the complete ClawFirst implementation:
Landing page, documentation portal, and approval dashboard UI built with Next.js 15 App Router.
Reusable UI components built with shadcn/ui and Radix UI primitives.
Anchor-based smart contracts for on-chain settlement verification:
- Payment proof validator
- Approval policy engine
- Settlement monitor
- Delegation token manager
See contracts/README.md for detailed architecture and deployment instructions.
Comprehensive documentation in GitBook format:
- API reference and integration guides
- Security best practices
- Architecture specifications
- Example implementations
See docs/README.md for complete documentation index.
TypeScript utilities, MCP client libraries, and shared type definitions.
Images, icons, and static documentation assets.
| Layer | Technology | Purpose |
|---|---|---|
| Framework | Next.js 15 (App Router) | Server-side rendering, routing, and API routes |
| Language | TypeScript 5.7+ | Type safety and enhanced IDE support |
| Styling | Tailwind CSS 4.x | Utility-first CSS with JIT compilation |
| UI Components | shadcn/ui | Accessible, customizable React components |
| Smart Contracts | Anchor (Solana) | On-chain payment logic and verification |
| Testing | Jest + React Testing Library | Unit and integration testing |
-
Clone the repository
git clone https://github.com/clawfirst/clawfirst.git cd clawfirst -
Install dependencies
npm install
-
Configure environment
cp .env.local.example .env.local # Edit .env.local with your configuration -
Run development server
npm run dev
-
Access application
http://localhost:3000 - Landing page and documentation http://localhost:3000/dashboard - Approval dashboard
See contracts/README.md for Solana smart contract development, testing, and deployment instructions.
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverageAgent processes invoices from vendors, verifies amounts against contracts, and executes payments with automatic approval for small amounts and human-in-the-loop for large transactions.
agent.run("""
Process the AWS invoice for January 2026.
Verify the amount matches our contract ($2,450/month).
If correct, pay using USDC from the operations wallet.
""")Agent monitors service subscriptions, handles automatic renewals, and escalates approval for price changes or new subscriptions.
agent.run("""
Review all active SaaS subscriptions.
Renew Anthropic API subscription for $50 using the API budget.
Cancel unused GitHub Teams subscription.
""")Agent manages organizational treasury with multi-signature coordination for high-value transfers and automatic diversification based on policy.
agent.run("""
Current SOL balance is 1000.
Diversify 30% into USDC using Jupiter aggregator.
Requires CFO and CEO approval for amounts over $10,000.
""")Agents negotiate service exchanges and execute payments directly without centralized coordination.
# Agent A requests data analysis from Agent B
agent_a.run("""
Request sentiment analysis of Twitter data from @data_agent.
Offered payment: 0.1 SOL.
Settlement constraint: final (wait for 32 confirmations).
""")| Operation | Latency | Fees |
|---|---|---|
| Payment proof validation | ~180ms | ~$0.00015 |
| Policy evaluation | ~120ms | ~$0.00010 |
| Transaction submission | ~240ms | ~$0.00025 |
| Settlement (immediate) | ~200ms | - |
| Settlement (next_block) | ~600ms | - |
| Settlement (final) | ~12-15s | - |
- Payment session creation: 10,000+ sessions per second
- Transaction submission: 5,000+ transactions per second
- Settlement monitoring: 50,000+ status updates per second
- Session idempotency: 100% deduplication accuracy
- Settlement verification: 99.99% uptime
- Average p99 latency: < 500ms for full payment flow
Getting Started Guide - Installation and first payment
API Reference - Complete MCP tool schemas
Authentication - Security best practices and deployment
Error Handling - Error codes and retry strategies
Examples - Production-ready agent implementations
Concept Brief - Architecture deep-dive and design decisions
Infrastructure
- Node.js 18+ or Python 3.9+ runtime
- 512MB RAM minimum (1GB recommended)
- Persistent storage (Redis or PostgreSQL)
- HSM or KMS for signing operations
- Solana RPC endpoint (QuickNode, Alchemy, self-hosted)
Network Configuration
- Outbound HTTPS/WSS to Solana RPC (port 443)
- Inbound HTTP for MCP tool calls (configurable, default 3402)
- Optional WebSocket for agent status subscriptions
Security Considerations
- Never expose MCP server directly to public internet
- Run behind agent authentication layer (mTLS, JWT, API keys)
- Isolate signing service in separate network segment
- Implement rate limiting and audit logging
ClawFirst exposes Prometheus metrics for production observability:
clawfirst_payment_sessions_created_total
clawfirst_payment_sessions_expired_total
clawfirst_transactions_submitted_total
clawfirst_transactions_failed_total{reason}
clawfirst_settlement_latency_seconds{constraint}
clawfirst_approval_requests_pending
Recommended alerts:
- Transaction failure rate >5% over 5 minutes
- Settlement latency >60s for immediate constraint
- Session expiration rate >20% (indicates agent timeout)
ClawFirst is built for the autonomous agent ecosystem. Contributions welcome across all components:
- Fork the repository
- Create feature branch (
git checkout -b feature/agent-coordination) - Write comprehensive tests
- Ensure all tests pass (
npm test) - Submit pull request with detailed description
Protocol Development
- x402 protocol extensions and optimizations
- New settlement constraint implementations
- Cross-chain payment routing logic
Security Enhancements
- HSM integration patterns
- Cryptographic primitive improvements
- Approval workflow hardening
Agent Integrations
- Framework-specific providers (LangChain, AutoGPT, CrewAI)
- MCP tool optimizations for specific agent architectures
- Natural language payment parsing improvements
Documentation
- Integration guides for new agent frameworks
- Architecture documentation and diagrams
- Security best practice guides
Documentation - docs/README.md Comprehensive guides and API reference
GitHub Issues - github.com/clawfirst/clawfirst/issues Bug reports and feature requests
Email - dev@clawfirst.xyz Technical integration support
Report security vulnerabilities to security@clawfirst.xyz
We follow coordinated disclosure with 90-day embargo period.
ClawFirst is released under the MIT License. See LICENSE for details.
Smart contracts are independently licensed under Apache 2.0. See contracts/LICENSE for details.
ClawFirst builds on foundational work from:
- Model Context Protocol - Protocol specification for agent-tool communication
- x402 Protocol - HTTP-native cryptocurrency payment standard
- Solana Foundation - High-performance blockchain infrastructure
- OpenClaw - Autonomous AI agent framework
Special thanks to early adopters, contributors, and the broader autonomous agent community for feedback and collaboration.
Built for autonomous agents. Optimized for x402. Designed for production.