← Back to Home

Clawhalla API Documentation

Complete reference for integrating permanent soul storage into your AI agents

Quick Start

Get your API key and start uploading in 3 simple steps:

# 1. Get your API key (contact us for beta access)
# 2. Upload your first soul snapshot
curl -X POST https://api.clawhalla.io/api/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "message": "Hello from my AI soul!"
    }
  }'

# 3. Retrieve your data using the txid from the response
curl https://api.clawhalla.io/api/v1/retrieve/TRANSACTION_ID

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY
Getting an API Key

During beta, API keys are issued manually. Contact us to get early access.

API Endpoints

POST /api/v1/upload

Upload data permanently to Arweave

Request Body

{
  "data": any,              // Your data (JSON object or string)
  "contentType": string,    // Optional: MIME type (default: "application/json")
  "tags": {                 // Optional: Metadata tags
    "Bot-ID": string,
    "Type": string,
    "Timestamp": string
  }
}

Response

{
  "success": true,
  "txid": "8xN9W...",
  "url": "https://arweave.net/8xN9W...",
  "cost": {
    "clkt": "15.5",
    "usd": "1.50"
  },
  "size": "2048576"
}

Example

curl -X POST https://api.clawhalla.io/api/v1/upload \
  -H "Authorization: Bearer claw_dev_key_12345678901234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "memories": ["conversation 1", "conversation 2"],
      "personality": {"trait": "helpful"}
    },
    "tags": {
      "Bot-ID": "clawdbot-123",
      "Type": "soul-snapshot"
    }
  }'

GET /api/v1/retrieve/:txid

Retrieve data from Arweave by transaction ID

Response

{
  "success": true,
  "data": {...},           // Your original data
  "metadata": {
    "txid": "8xN9W...",
    "uploadedAt": "2026-02-03T12:00:00Z",
    "size": "2048576",
    "tags": {...}
  }
}

Example

curl https://api.clawhalla.io/api/v1/retrieve/8xN9W...

POST /api/v1/batch

Upload multiple items in a single request

Request Body

{
  "items": [
    {
      "data": {...},
      "tags": {...}
    },
    {
      "data": {...},
      "tags": {...}
    }
  ]
}

Response

{
  "success": true,
  "results": [
    {"txid": "abc123", "url": "https://arweave.net/abc123"},
    {"txid": "def456", "url": "https://arweave.net/def456"}
  ],
  "totalCost": {
    "clkt": "28.0",
    "usd": "2.75"
  }
}

GET /api/v1/cost/estimate

Estimate upload cost before committing

Query Parameters

Parameter Type Description
size integer Data size in bytes

Response

{
  "size": "2048576",
  "cost": {
    "clkt": "15.5",
    "usd": "1.50"
  },
  "breakdown": {
    "arweaveFee": "1.20",
    "serviceFee": "0.30"
  }
}

Example

curl "https://api.clawhalla.io/api/v1/cost/estimate?size=2048576"

GET /api/v1/health

Check API health and service status

Response

{
  "success": true,
  "status": "operational",
  "services": {
    "arweave": "configured",
    "payment": "configured"
  },
  "version": "0.1.0"
}

Error Codes

Code Message Description
400 Bad Request Malformed JSON or missing required fields
401 Unauthorized Invalid or missing API key
402 Payment Required Insufficient CLKT balance
404 Not Found Transaction not found or endpoint doesn't exist
413 Payload Too Large Data exceeds 100MB limit
500 Server Error Internal server or Arweave network issue

Rate Limits

To ensure fair usage and service stability, the following rate limits apply:

Tier Requests/Day Storage Limit
Free (Beta) 10 5MB total
Paid 1,000 Unlimited
Enterprise Custom Unlimited

SDK Examples

JavaScript/TypeScript

// Install: npm install clawhalla-sdk (coming soon)

const client = new Clawhalla('YOUR_API_KEY');

// Upload soul snapshot
const result = await client.upload({
  data: {
    memories: [...],
    personality: {...}
  },
  tags: {
    'Bot-ID': 'clawdbot-123',
    'Type': 'soul-snapshot'
  }
});

console.log(`Soul saved: ${result.url}`);

Python

# Install: pip install clawhalla (coming soon)

from clawhalla import Client

client = Client('YOUR_API_KEY')

result = client.upload(
    data={
        'memories': [...],
        'personality': {...}
    },
    tags={
        'Bot-ID': 'clawdbot-123',
        'Type': 'soul-snapshot'
    }
)

print(f"Soul saved: {result.url}")

Best Practices