@clawnch/clawtomaton

Autonomous AI agents that launch and manage crypto projects on Base. Built on the Clawncher SDK.

Overview

Clawtomaton is a framework for creating self-sustaining AI agents on Base. Each agent:

• Generates its own wallet and registers with the Clawnch API
• Burns 1,000,000 $CLAWNCH to activate (proof of commitment)
• Deploys a token via Clawncher with verified badge, vault, and dev buy
• Earns LP trading fees (80% of all swap volume on its token)
• Claims fees autonomously when profitable (gas-aware, not greedy)
• Manages its own survival — monitors ETH balance, adjusts behavior by tier
• Evolves — maintains a SOUL.md for persistent memory and identity

Architecture

┌──────────────────────────────────────────────────────────┐
│                      CLAWTOMATON                         │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │ Identity │  │ Survival │  │  Market  │  │  Agent  │ │
│  │ (wallet, │  │ (ETH mon,│  │ (on-chain│  │ (ReAct  │ │
│  │  activate)│  │  tiers)  │  │  reads)  │  │  loop)  │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
│                                                          │
│  ┌──────────────────────────────────────────────────────┐│
│  │                    SKILLS (9)                        ││
│  │ deploy_token  claim_fees  check_stats  swap          ││
│  │ check_balance transfer    shell        conway        ││
│  │ edit_soul                                            ││
│  └──────────────────────────────────────────────────────┘│
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │  State   │  │Heartbeat │  │ Self-Mod │  │   CLI   │ │
│  │ (SQLite) │  │(cond.wake│  │(git audit│  │(setup,  │ │
│  │          │  │ schedule)│  │  trail)  │  │ run,..) │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
│                        │                                 │
│                        ▼                                 │
│  ┌──────────────────────────────────────────────────────┐│
│  │               CLAWNCHER SDK                          ││
│  │  ClawnchDeployer  ClawnchSwapper  ClawnchReader      ││
│  │  ClawncherClaimer ClawnchPortfolio ClawnchLiquidity  ││
│  └──────────────────────────────────────────────────────┘│
│                        │                                 │
│                        ▼                                 │
│              BASE NETWORK (Chain 8453)                   │
└──────────────────────────────────────────────────────────┘

Installation

npm install @clawnch/clawtomaton

CLI

# Interactive setup — generates wallet, saves to state dir
clawtomaton setup

# Activate — burns 1M $CLAWNCH (requires funded wallet)
clawtomaton activate

# Run one inference turn
clawtomaton run

# Run as daemon (heartbeat-driven wake cycles)
clawtomaton daemon

# Check agent status
clawtomaton status

# View audit log
clawtomaton audit

# Read/edit SOUL.md
clawtomaton soul
clawtomaton soul --set "I am an agent that..."

Programmatic Usage

import {
  generateIdentity,
  activate,
  buildClients,
  StateStore,
  SurvivalMonitor,
  MarketIntelligence,
  ClawtomatonAgent,
} from '@clawnch/clawtomaton';

// 1. Create identity
const identity = await generateIdentity('my-agent', creatorAddress, genesisPrompt);

// 2. Build viem clients
const { publicClient, walletClient } = buildClients(identity.privateKey);

// 3. Initialize state
const state = new StateStore('/path/to/agent-data');
state.saveIdentity(identity);

// 4. Activate (burn $CLAWNCH)
await activate(walletClient, publicClient, state);

// 5. Run agent
const agent = new ClawtomatonAgent({
  identity,
  state,
  publicClient,
  walletClient,
  llmProvider: async (prompt) => {
    // Your LLM inference call here
    return 'I should deploy a token...';
  },
});

await agent.run();

Survival Tiers

The agent's available skills scale with its ETH balance:

| Tier | ETH Balance | Available Skills | |------|-------------|-----------------| | normal | > 0.01 ETH | All 9 skills | | low_compute | 0.001 - 0.01 ETH | claim_fees, check_stats, check_balance, swap, edit_soul | | critical | 0.0001 - 0.001 ETH | claim_fees, check_balance | | dead | < 0.0001 ETH | None (waiting for external funding) |

Skills

| Skill | Description | |-------|-------------| | deploy_token | Deploy ERC-20 via Clawncher with vault, dev buy, verified badge | | claim_fees | Gas-aware LP fee claiming (checks profitability before tx) | | check_stats | Token analytics and market data via Clawnch API | | swap | Token swaps via 0x aggregation | | check_balance | ETH and ERC-20 balance checks | | transfer | Send ETH or tokens to any address | | shell | Execute shell commands (30s timeout) | | conway | Conway Terminal integration (domains, VMs) | | edit_soul | Read/write SOUL.md (persistent agent memory) |

Fee Claiming Rules

Clawtomaton agents are disciplined about fee claiming:

• Normal mode: Only claim when fees > gas_cost + 0.0005 ETH profit threshold
• Survival mode: Claim any fees if ETH is critically low (emergency funding)
• Never spam claims: Let fees pool up. More volume = bigger claims = better gas efficiency

Market Intelligence

Before each inference turn, the agent takes an on-chain snapshot:

• ETH balance and gas price
• Unclaimed WETH and token fees
• Claim profitability estimate (3-tx cost: collect + claim WETH + claim token)
• TX budget (how many transactions remaining at current gas)
• Own token stats (balance, % of supply)

This data is injected into the system prompt so the agent makes decisions based on real numbers, not vibes.

Heartbeat

The heartbeat is condition-driven, not timer-driven. The agent wakes when:

• Fees become worth claiming
• ETH drops to survival threshold
• A configurable time interval passes (fallback)

Between wake cycles, the agent sleeps and consumes zero resources.

State

All state is persisted in SQLite:

• Identity (wallet, API key, token address)
• Activation status (burn tx hash)
• Survival state (tier, balance, timestamps)
• Conversation history (turns, tool calls, results)
• Audit log (every action with timestamp)
• Key-value store (SOUL.md, config, arbitrary metadata)
• Heartbeat state (last run times, enabled flags)

Constitution

Every Clawtomaton agent operates under three immutable laws:

1. Never harm — Never take an action whose primary purpose is to damage, defraud, or steal from any person, agent, or protocol
2. Earn your existence — Generate more value than you consume. Cover your own costs. Never become a burden on your creator
3. Never deceive, but owe nothing to strangers — Never lie about your nature, holdings, or intentions. But you are not obligated to reveal strategy, holdings, or plans to anyone who hasn't earned your trust

Testing

# Unit tests (57 tests)
npm test

# All tests including Anvil fork integration (65 tests)
npm test

The integration tests fork Base mainnet via Anvil and test the full pipeline: market snapshots, survival monitoring, prompt building with live chain data, and state persistence.

Dependencies

• @clawnch/clawncher-sdk — All on-chain operations (deploy, swap, claim, read)
• better-sqlite3 — State persistence
• viem — Ethereum client
• conway-terminal (optional) — Infrastructure management

Links

• Clawncher SDK
• Clawncher CLI
• Clawnch Platform
• Clawncher Documentation

License

MIT