Tools

Clawfirst Client

Name: Clawfirst Client
Rating: 3.5 (1 reviews)
Author: ClawFirst

By ClawFirst ⭐ 1 stars 👁 29 views ▲ 0 votes

Client for the ClawFirst platform. ClawFirst is a Model Context Protocol (MCP) server that enables AI agents to execute cryptocurrency transactions on the x402 protocol.

Homepage GitHub

Install

npm install -g

README

# ClawFirst

**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.

---

## What is ClawFirst?

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.

### The Problem

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

### The Solution

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.

---

## Quick Start

Enable your AI agent to transact in three steps:

### 1. Install ClawFirst

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

### 2. Launch MCP Server

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

### 3. Connect Your Agent

```python
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 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin")
print(f"Payment completed: {result.tx_signature}")
```

---

## Key Features

### Non-Custodial Security

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

### Session-Based Idempotency

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

### Multi-Tier Approval Policies

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

### Real-Time Settlement Monitoring

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

---

## Architecture

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)                      │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### Component Architecture

**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

---

## Repository Structure

This monorepo contains the complete ClawFirst implementation:

### `/app` - Next.js Application
Landing page, documentation portal, and approval dashboard UI built with Next.js 15 App Router.

### `/components` - React Components
Reusable UI components built with shadcn/ui and Radix UI primitives.

### `/contracts` - Solana Smart Contracts
Anchor-based smart contracts for on-chain settlement verification:
- Payment proof validator
- Approval policy engine
- Settlement monitor
- Delegation token manager

See [contracts/README.md](contracts/README.md) for detailed architecture and deployment instructions.

### `/docs` - Technical Documentation
Comprehensive documentation in GitBook format:
- API reference and integration guides
- Security best practices
- Architecture specifications
- Example implementations

See [docs/README.md](docs/README.md) for complete documentation index.

### `/lib` - Shared Libraries
TypeScript utilities, MCP client libraries, and shared type definitions.

### `/public` - Static Assets
Images, icons, and static documentation assets.

---

## Development

### Technology Stack

| 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 |

### Local Development Setup

1. **Clone the repository**
   ```bash
   git clone https://github.com/clawfirst/clawfirst.git
   cd clawfirst
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Configure environment**
   ```bash
   cp .env.local.example .env.local
   # Edit .env.local with your configuration
   ```

4. **Run development server**
   ```bash
   npm run dev
   ```

5. **Access application**
   ```
   http://localhost:3000 - Landing page and documentation
   http://localhost:3000/dashboard - Approval dashboard
   ```

### Smart Contract Development

See [contracts/README.md](contracts/README.md) for Solana smart contract development, testing, and deployment instructions.

### Testing

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage
```

---

## Use Cases

### Autonomous Invoice Processing

Agent

... (truncated)

tools