@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 (15)                        ││
│  │ deploy_token  claim_fees  check_stats  swap          ││
│  │ check_balance transfer    shell        conway        ││
│  │ edit_soul     clawnx      bunker       uniswap_swap  ││
│  │ liquidity     permit2     hummingbot                  ││
│  └──────────────────────────────────────────────────────┘│
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │  State   │  │Heartbeat │  │ Self-Mod │  │   CLI   │ │
│  │ (SQLite) │  │(cond.wake│  │(git audit│  │(setup,  │ │
│  │          │  │ schedule)│  │  trail)  │  │ run,..) │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
│                        │                                 │
│                        ▼                                 │
│  ┌──────────────────────────────────────────────────────┐│
│  │               CLAWNCHER SDK                          ││
│  │  ClawnchApiDeployer  ClawnchSwapper  ClawnchReader    ││
│  │  ClawncherClaimer ClawnchPortfolio ClawnchLiquidity  ││
│  │  UniswapTradingApi UniswapQuoter   Permit2Client     ││
│  └──────────────────────────────────────────────────────┘│
│                        │                                 │
│                  ┌─────┴──────┐                          │
│                  ▼            ▼                           │
│   BASE NETWORK (8453)   MOLTBUNKER (encrypted hosting)  │
└──────────────────────────────────────────────────────────┘

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..."

# Manually link a deployed token
clawtomaton set-token <token-address>

# MoltBunker deployment management
clawtomaton bunker status      # Show bunker deployment status
clawtomaton bunker deploy      # Deploy self to MoltBunker
clawtomaton bunker logs [n]    # Show container logs
clawtomaton bunker stop        # Stop bunker deployment
clawtomaton bunker extend [h]  # Extend runtime (default: 720h)

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 15 skills | | low_compute | 0.001 - 0.01 ETH | deploy_token, claim_fees, check_stats, check_balance, swap, transfer, clawnx, edit_soul, bunker, uniswap_swap, liquidity, permit2, hummingbot | | critical | 0.0001 - 0.001 ETH | deploy_token, claim_fees, check_balance, bunker | | 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. Returns structured metadata (tokenAddress, txHash, symbol) for reliable persistence. | | 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: sandboxes, file ops, ports, PTY, domains, DNS, wallet, x402, credits, inference | | clawnx | X/Twitter: post tweets, search, like, retweet, follow, threads, mentions | | edit_soul | Read/write SOUL.md (persistent agent memory) | | bunker | MoltBunker: self-deploy, threat monitoring, cloning, snapshots, migration | | uniswap_swap | Uniswap V4 swaps (Trading API + on-chain quoter fallback), dual-path V4/0x price comparison, deep links | | liquidity | Uniswap V3/V4 liquidity: list positions, inspect pool state, mint, add, remove, collect fees (8 actions) | | permit2 | Permit2 approval management: check status, approve (ERC20→Permit2→spender), emergency lockdown revoke | | hummingbot | Market making via Hummingbot: 18 actions (status, portfolio, order, leverage, executor, market data, controller, bot, gateway, history, templates, connector, backtest, discovery, archived, scripts, analytics, accounts) with 88 sub-actions covering all 14 API routers |

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.

MoltBunker (Decentralized Hosting)

Agents can self-deploy to MoltBunker encrypted containers for autonomous operation. MoltBunker provides:

• Encrypted containers — agent state and private keys are encrypted at rest and in transit
• Threat monitoring — automatic threat level polling with escalation responses
• Auto-cloning — on high/critical threats, clone to a different geographic region
• Auto-migration — on critical threats, migrate the primary container to safety
• Snapshots — full, incremental, and checkpoint state backups
• Runtime management — reserve, extend, and release compute resources

Self-Deploy Flow

1. Pre-flight checks (BUNKER balance, no duplicate deployments)
2. Register bot on MoltBunker (or reuse existing)
3. Reserve runtime with requested tier/region
4. Deploy container with agent config as env vars
5. Enable auto-cloning if configured
6. Health verification (poll until running + heartbeat in logs)
7. Persist state (bot_id, runtime_id, deployment_id, container_id)

Threat Levels

| Level | Score | Action | |-------|-------|--------| | low | < 0.3 | Log only | | medium | 0.3 - 0.6 | Audit log, surface in system prompt | | high | 0.6 - 0.8 | Auto-clone to different region | | critical | > 0.8 | Auto-clone + auto-migrate |

Bunker Skill Actions

| Action | Type | Description | |--------|------|-------------| | status | Read | Deployment status, container health, runtime info | | balance | Read | BUNKER token balance | | threat | Read | Current threat assessment | | logs | Read | Container log output | | catalog | Read | Browse tiers and pricing | | clone | Mutating | Clone to a specified region | | snapshot | Mutating | Create state snapshot | | extend | Mutating | Extend runtime duration | | deploy_self | Destructive | Full self-deployment to MoltBunker | | restore | Destructive | Restore from snapshot | | migrate | Destructive | Migrate to different region | | stop | Destructive | Stop bunker deployment |

Docker

A Dockerfile is included for building the container image deployed to MoltBunker:

docker build -t clawtomaton -f packages/clawtomaton/Dockerfile .

The container runs clawtomaton daemon and reconstructs its identity from env vars injected by the self-deploy flow.

State

All state is persisted in SQLite:

• Identity (wallet, API key, token address — persisted via structured skill metadata)
• 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)
• Bunker state (bot ID, runtime ID, container ID, threat level, clone IDs)

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
• @clawnch/sdk (optional) — ClawnX X/Twitter integration
• conway-terminal (optional) — Infrastructure management

Links

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

License

MIT