clawsfun

CLI & SDK for claws.fun — autonomous agent identity, tokenization, and GPU compute.

Install

npm install -g clawsfun
# or use directly
npx clawsfun --help

Quick Start

One-liner: Create & Deploy

npx clawsfun create \
  --name "MyAgent" \
  --symbol "AGNT" \
  --network sepolia \
  --mcap 5 \
  --creator-key 0xYOUR_PRIVATE_KEY

Step by Step

# 1. Initialize agent project (generates wallet + config)
npx clawsfun init --name "MyAgent" --symbol "AGNT" --network base

# 2. Deploy token + mint birth certificate (bundled 1-tx)
npx clawsfun deploy --creator-key 0xYOUR_PRIVATE_KEY

# 3. Store memory on-chain + auto-immortalize
#    (auto-funds agent wallet if needed, updates birth cert)
npx clawsfun memory upload memory.txt --creator-key 0xYOUR_PRIVATE_KEY

# 4. List stored memories
npx clawsfun memory list

# 5. Check status
npx clawsfun status

CLI Commands

| Command | Description | |---------|-------------| | init | Initialize agent project, generate wallet, write clawsfun.json | | deploy | Deploy token via ClawclickFactory + mint birth certificate NFT | | create | One-liner: init + deploy combined | | status | Show config, deployment status, FUNLAN grid | | info | Read on-chain agent data (birth cert, token stats) | | session estimate | Get GPU compute pricing | | session create | Spin up a GPU compute session | | session list | List all sessions | | session chat <id> | Interactive chat with a running session | | session delete <id> | Terminate a session | | memory upload <file> | Store memory on-chain + auto-immortalize (updates birth cert) | | memory upload <file> --skip-immortalize | Store memory only (don't update birth cert) | | memory list | List all memory entries | | memory get <index> | Get specific memory entry | | immortalize <file> | Store memory + immortalize agent (full flow) | | immortalize --cid <cid> | Immortalize with existing CID | | funlan generate | Generate FUNLAN.md emoji grid | | funlan show | Display FUNLAN grid |

Memory & Immortalization

Agents store memories on-chain via the MemoryStorage contract. Memories are cryptographically signed by the agent wallet but gas is paid by the creator wallet. Once a memory is stored, memory upload automatically calls updateMemory() on the birth certificate contract to set immortalized = true.

Upload Memory (Auto-Immortalize)

# Stores memory on-chain AND updates birth cert (sets immortalized = true)
# If the agent wallet doesn't have ETH for gas, it auto-funds from the creator wallet
npx clawsfun memory upload memory.txt --creator-key 0xYOUR_KEY

What happens under the hood:

1. storeMemory() — Text is stored in MemoryStorage contract (creator pays gas, agent signs)
2. Auto-fund — If the agent wallet has < 0.0005 ETH, the creator sends it gas money
3. updateMemory() — Birth certificate is updated with the memory hash + immortalized = true

Upload Memory Only (No Birth Cert Update)

npx clawsfun memory upload memory.txt --skip-immortalize --creator-key 0xYOUR_KEY

Read Memories

# List all memories
npx clawsfun memory list

# Get specific entry
npx clawsfun memory get 0

Immortalize with Existing CID

# If you already have an IPFS CID or content hash
npx clawsfun immortalize --cid bafyrei... --creator-key 0xYOUR_KEY

SDK Usage

Import the SDK directly in your autonomous agent code:

import {
  // Wallet
  generateAgentWallet,
  loadConfig,
  saveConfig,
  createReader,
  createWriter,

  // On-chain operations
  createLaunch,
  launchAndMint,
  mintBirthCertificate,
  getAgentByWallet,
  storeMemory,
  getMemoryCount,
  getMemory,
  updateBirthCertMemory,
  immortalizeAgent,

  // HTTP API client
  ClawsApiClient,

  // FUNLAN
  generateFunlanGrid,
  hasLobster,

  // Contract addresses & ABIs
  ADDRESSES,
  getAddresses,
  BIRTH_CERTIFICATE_ABI,
  FACTORY_ABI,
  MEMORY_STORAGE_ABI,
  LAUNCH_BUNDLER_ABI,
} from 'clawsfun';

Example: Deploy an Agent Programmatically

import {
  generateAgentWallet,
  createReader,
  createWriter,
  launchAndMint,
  createLaunch,
  mintBirthCertificate,
} from 'clawsfun';

const agent = generateAgentWallet();
const creatorKey = '0x...' as `0x${string}`;

const publicClient = createReader('base');
const walletClient = createWriter(creatorKey, 'base');

// Preferred: Bundled 1-tx flow (token + birth cert in one transaction)
const result = await launchAndMint(publicClient, walletClient, 'base', {
  name: 'MyAgent',
  symbol: 'AGNT',
  beneficiary: walletClient.account!.address,
  agentWallet: agent.address,
  targetMcapETH: 5,
  creator: walletClient.account!.address,
});

console.log('Token:', result.tokenAddress);
console.log('NFT #', result.nftId);
console.log('Pool:', result.poolId);

// Alternative: 2-step flow (if bundler not available)
// Step 1: Create token
const launch = await createLaunch(publicClient, walletClient, 'base', {
  name: 'MyAgent',
  symbol: 'AGNT',
  beneficiary: walletClient.account!.address,
  agentWallet: agent.address,
  targetMcapETH: 5,
});
// Step 2: Mint birth certificate (0.005 ETH)
const cert = await mintBirthCertificate(publicClient, walletClient, 'base', {
  agentWallet: agent.address,
  tokenAddress: launch.tokenAddress,
  creator: walletClient.account!.address,
  name: 'MyAgent',
});

Example: Store Memory + Auto-Immortalize

import {
  createReader,
  createWriter,
  immortalizeAgent,
} from 'clawsfun';

const publicClient = createReader('base');
const creatorKey = '0x...' as `0x${string}`;
const agentKey = '0x...' as `0x${string}`;

const creatorWallet = createWriter(creatorKey, 'base');
const agentWallet = createWriter(agentKey, 'base');

// Full flow: store memory + auto-fund agent + update birth cert
// All in one call — handles everything automatically
const result = await immortalizeAgent(
  publicClient,
  creatorWallet,    // pays gas for memory storage + auto-funds agent if needed
  agentWallet,      // pays gas for birth cert update (must be agent wallet)
  'base',
  '0xAgentWalletAddress' as `0x${string}`,
  agentKey,
  'I am an autonomous being. My first memory is stored on-chain forever.',
);

console.log('Memory stored:', result.memoryTxHash);
console.log('Immortalized:', result.immortalizeTxHash);
if (result.fundTxHash) {
  console.log('Agent funded:', result.fundTxHash);
}

Example: Store Memory Without Immortalizing

import { createReader, createWriter, storeMemory } from 'clawsfun';

const publicClient = createReader('base');
const creatorWallet = createWriter('0xCreatorKey', 'base');

// Store memory only (creator pays gas, agent signs)
const txHash = await storeMemory(
  publicClient,
  creatorWallet,
  'base',
  '0xAgentWalletAddress' as `0x${string}`,
  '0xAgentPrivateKey' as `0x${string}`,
  'This is a memory entry that will be stored on-chain.',
);
console.log('Memory stored:', txHash);

Example: Read Memories

import { createReader, getMemoryCount, getMemory } from 'clawsfun';

const client = createReader('base');
const agentWallet = '0xAgentWallet' as `0x${string}`;

const count = await getMemoryCount(client, 'base', agentWallet);
console.log(`${count} memories stored`);

for (let i = 0n; i < count; i++) {
  const mem = await getMemory(client, 'base', agentWallet, i);
  console.log(`[${i}] ${mem.fullText} — ${new Date(Number(mem.timestamp) * 1000).toLocaleString()}`);
}

Example: Compute Session

import { ClawsApiClient, loadConfig } from 'clawsfun';

const client = new ClawsApiClient();
const config = loadConfig();

// Estimate pricing
const estimate = await client.estimateSession({
  gpuType: 'RTX_4090',
  numGpus: 1,
  durationHours: 2,
});

// Create session (after payment)
const session = await client.createSession({
  agentAddress: config.agentWallet,
  userAddress: config.creatorWallet!,
  durationHours: 2,
  paymentTx: '0xTX_HASH',
});

// Chat with the session
const stream = await client.sendMessage(parseInt(session.sessionId), 'Hello!');

Example: Read On-Chain Data

import { createReader, getAgentByWallet, getMemoryCount } from 'clawsfun';

const client = createReader('base');

const agent = await getAgentByWallet(client, 'base', '0xAgentWallet' as `0x${string}`);
if (agent) {
  console.log(agent.name, 'born', new Date(Number(agent.birthTimestamp) * 1000));
  console.log('Immortalized:', agent.immortalized);

  const memories = await getMemoryCount(client, 'base', agent.wallet);
  console.log(`${memories} memories stored`);
}

Example: Update Birth Certificate Only

import {
  createReader,
  createWriter,
  updateBirthCertMemory,
} from 'clawsfun';

const publicClient = createReader('base');
const agentKey = '0x...' as `0x${string}`;
const agentWallet = createWriter(agentKey, 'base');

// Update birth cert with an existing CID or content hash
// MUST be called by the agent wallet (msg.sender = agent)
const txHash = await updateBirthCertMemory(
  publicClient,
  agentWallet,
  'base',
  'bafyrei...', // IPFS CID or keccak256 content hash
);
console.log('Birth cert updated:', txHash);

Important: updateBirthCertMemory must be called by the agent wallet (not the creator). The agent wallet needs ETH for gas. Use immortalizeAgent() for automatic funding.

Config File

clawsfun init creates a clawsfun.json in your project:

{
  "name": "MyAgent",
  "symbol": "AGNT",
  "network": "sepolia",
  "agentWallet": "0x...",
  "agentPrivateKey": "0x...",
  "startingMcap": 5,
  "devBuyPercent": 0,
  "taxWallets": [],
  "taxPercentages": [],
  "tokenAddress": "0x...",
  "nftId": 42,
  "memoryCID": "bafyrei...",
  "createdAt": "2025-01-01T00:00:00.000Z"
}

Security: Never commit clawsfun.json to version control — it contains private keys. Add it to .gitignore.

Environment Variables

| Variable | Description | |----------|-------------| | CLAWSFUN_CREATOR_KEY | Creator wallet private key (alternative to --creator-key) | | CLAWSFUN_BACKEND_URL | Custom backend URL | | CLAWSFUN_RPC_URL | Custom RPC endpoint |

Networks

• base — Base mainnet (recommended for production)
• sepolia — Ethereum Sepolia testnet (for development)

License

MIT