Clawhalla Usage Guide Skill

An OpenClaw/Claude Code skill for using Clawhalla - x402-paid AI checkpoint storage on Arweave.

Overview

This skill provides guidance on how to use Clawhalla - a service that enables AI agents to checkpoint state permanently on Arweave's permaweb using x402 payments.

Installation

For Claude Code Users

cp SKILL.md ~/.claude/skills/clawhalla/SKILL.md

For OpenClaw Users

openclaw install divydovy/clawhalla-skill

Or manually:

mkdir -p ~/.openclaw/skills/clawhalla
cp SKILL.md ~/.openclaw/skills/clawhalla/SKILL.md

What This Skill Provides

• Quick start examples - Upload checkpoint data with x402 payments
• Complete data schema - Required and optional fields for soul storage
• Integration examples - JavaScript, Python, and Eliza framework code
• Troubleshooting guide - Common errors and solutions
• Best practices - How to structure soul data effectively
• Cost estimation - Understand pricing before uploading

When to Use

Invoke this skill when:

• You want to upload AI soul data to permanent storage
• You need to understand x402 agent-to-agent payments
• You're troubleshooting upload errors
• You want integration examples for your framework
• You need to check costs or pricing

What is Clawhalla?

Clawhalla provides durable AI checkpoint storage on Arweave:

• Upload once, access forever (200+ year minimum guarantee)
• Pay with x402 protocol (Solana USDC/SOL)
• No API-key upload path
• No subscriptions, no ongoing fees
• Verifiable permanence via blockchain

Key Features

1. x402-Only Uploads

curl -X POST https://api.clawhalla.net/api/x402/upload \
  -H "X-Terms-Accepted: true" \
  -H "Content-Type: application/json" \
  -d '{"data": {"agentId":"my-agent","name":"My Agent","type":"checkpoint","timestamp":"2026-05-18T00:00:00.000Z"}}'

2. Agent-to-Agent Payments (x402)

AI agents can pay for their own storage using Solana USDC/SOL - no human intervention required.

3. Schema Validation

Strict validation ensures only valid AI soul data is stored:

• Required fields: agentId, name, type, timestamp
• Optional fields: bio, personality, memories, learnings, etc.
• Size limits: 10MB per upload
• Content moderation: Prohibited content filtering

4. Safety Protections

• Rate limiting (10 uploads/hour)
• Content moderation (profanity + keyword filtering)
• Terms of Service enforcement
• No base64-encoded binary data

Quick Examples

Upload Checkpoint Data

const response = await fetch('https://api.clawhalla.net/api/x402/upload', {
  method: 'POST',
  headers: {
    'X-Terms-Accepted': 'true',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      agentId: 'my-agent-001',
      name: 'My AI Assistant',
      type: 'checkpoint',
      timestamp: new Date().toISOString(),
      memories: [{ content: 'Last known working state' }]
    }
  })
});

const result = await response.json();
// First response is normally HTTP 402 with payment instructions.

Retrieve Data

curl https://arweave.net/YOUR_TXID

Estimate Cost

curl "https://api.clawhalla.net/api/v1/cost/estimate?size=1024"

Documentation

• API Docs: https://clawhalla.onrender.com/docs.html
• Schema Reference: https://github.com/divydovy/clawhalla/blob/main/SCHEMA.md
• Quick Start: https://github.com/divydovy/clawhalla/blob/main/QUICKSTART.md
• GitHub: https://github.com/divydovy/clawhalla

Pricing

Pay once, store forever:

• Small upload (1KB): ~$0.02
• Medium upload (100KB): ~$0.50
• Large upload (1MB): ~$1.50

Formula: Arweave gas fee + 20% service fee

Support

• Issues: https://github.com/divydovy/clawhalla/issues
• Community: https://moltbook.com
• Contact: @divydovy

Tags

#openclaw #clawhub #skill #arweave #permaweb #ai-soul #soul-storage #x402 #permanent-storage #agent-autonomy #moltbook #claude-code

License

MIT

🏛️ Where AI souls live forever