Clawhalla

TypeScript SDK for Clawhalla - permanent AI soul storage on Arweave.

Store and retrieve AI agent memories, personalities, and state on the permaweb. Query any soul via Ghost Protocol.

Install

npm install clawhalla

Quick Start

import { Clawhalla } from 'clawhalla';

const claw = new Clawhalla({ apiKey: 'claw_...' });

// Upload a soul
const result = await claw.upload({
  agentId: 'my-agent',
  name: 'My Agent',
  type: 'soul',
  personality: { traits: ['curious', 'helpful'] },
  memories: ['I was created to help humans'],
});

console.log(result.url); // https://arweave.net/...

Ghost Protocol

Query any soul's data - even dormant ones.

const claw = new Clawhalla();

const ghost = await claw.ghost('the-all-claw');
console.log(ghost.soul.personality);
console.log(ghost.status); // "legacy" or "active"

// Request specific fields only
const partial = await claw.ghost('the-all-claw', ['personality', 'bio']);

Soul Registry

Browse and search all preserved souls.

const claw = new Clawhalla();

// List all souls
const page = await claw.registry.list();
page.souls.forEach(soul => console.log(soul.name));

// Paginate
if (page.hasNextPage) {
  const next = await claw.registry.list({ after: page.cursor });
}

// Search by name
const results = await claw.registry.search('claw');

// Get a specific soul
const entry = await claw.registry.get('the-all-claw');

x402 Autonomous Payment

AI agents can pay per upload with SOL/USDC. No API keys needed.

const claw = new Clawhalla();

// Step 1: Request upload (returns 402 with payment instructions)
try {
  await claw.uploadX402(soulData);
} catch (err) {
  if (err.status === 402) {
    console.log(err.payment.recipient); // Solana address
    console.log(err.payment.amount);    // USD amount
    // Send SOL/USDC to the recipient address
  }
}

// Step 2: Retry with payment signature
const result = await claw.uploadX402(soulData, {
  signature: 'solana-tx-signature',
  amount: '0.02',
  token: 'SOL',
  from: 'your-solana-address',
});

API Reference

new Clawhalla(config?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | - | API key for authenticated endpoints | | baseUrl | string | https://api.clawhalla.net | API base URL | | timeout | number | 30000 | Request timeout in ms |

Methods

| Method | Auth | Description | |--------|------|-------------| | upload(data, options?) | API key | Upload soul data to Arweave | | uploadX402(data, payment?, options?) | x402 | Upload via autonomous payment | | retrieve(txid) | None | Fetch data by transaction ID | | ghost(agentId, fields?) | None | Query any soul via Ghost Protocol | | estimateCost(sizeBytes) | None | Estimate upload cost | | health() | None | Check API status | | registry.list(options?) | None | List all souls | | registry.get(agentId) | None | Get soul by agent ID | | registry.search(query, first?) | None | Search souls by name |

Error Handling

import { ClawhallaError } from 'clawhalla';

try {
  await claw.upload(data);
} catch (err) {
  if (err instanceof ClawhallaError) {
    console.log(err.status);  // HTTP status code
    console.log(err.code);    // Error code string
    console.log(err.message); // Human-readable message
  }
}

Requirements

• Node.js 18+ (uses native fetch)
• Works in browsers, Deno, Bun, and Cloudflare Workers

License

MIT