Clawlett

Clawlett

An OpenClaw skill for autonomous token swaps and Trenches trading, powered by Gnosis Safe + Zodiac Roles.

Supported chains: Base (default), BNB Chain. All scripts accept --chain <name>.

Overview

This skill enables AI agents to perform secure, permissioned token swaps and Trenches token creation/trading through a Gnosis Safe. The agent operates through Zodiac Roles module which restricts operations to:

• Swapping tokens via KyberSwap Aggregator (default) or CoW Protocol (MEV-protected)
• Creating tokens on Trenches
• Buying and selling Trenches tokens via factory
• Approving tokens only for KyberSwap Router, CoW Vault Relayer, and AgentKeyFactoryV3
• All swapped tokens return to the Safe (no external transfers)

The human owner retains full control of the Safe while the agent can only execute swaps and trades.

Security Model

┌─────────────────────────────────────────────────────────┐
│                     Gnosis Safe                         │
│                  (holds all funds)                      │
│                                                         │
│  Owner: Human Wallet (full control)                     │
│  Module: Zodiac Roles (restricted agent access)         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   Zodiac Roles                          │
│                                                         │
│  Agent can ONLY:                                        │
│  • Call ZodiacHelpers (swaps, approvals, wrapping)      │
│  • Approve tokens for KyberSwap Router & CoW Relayer    │
│  • Execute swaps via KyberSwap or CoW Protocol          │
│                                                         │
│  Agent CANNOT:                                          │
│  • Transfer tokens out of Safe                          │
│  • Change Safe settings                                 │
│  • Add/remove owners                                    │
└─────────────────────────────────────────────────────────┘

Installation

cd clawlett/scripts
npm install

Setup

1. Initialize the wallet (deploys Safe + Roles):

node clawlett/scripts/initialize.js --owner <YOUR_WALLET_ADDRESS>
# Or for BNB Chain:
node clawlett/scripts/initialize.js --chain bnb --owner <YOUR_WALLET_ADDRESS>

2. Fund the agent address with ~0.001 native token for gas (address shown in output)

3. Run the script again - it will complete the setup automatically

4. Fund your Safe with tokens to trade

Usage

Check Balances

# ETH balance
node clawlett/scripts/balance.js

# Specific token
node clawlett/scripts/balance.js --token USDC

# All verified tokens
node clawlett/scripts/balance.js --all

Swap Tokens

# KyberSwap (default — optimal routes across DEXs)
node clawlett/scripts/swap.js --from ETH --to USDC --amount 0.1
node clawlett/scripts/swap.js --from ETH --to USDC --amount 0.1 --execute

# CoW Protocol (MEV-protected)
node clawlett/scripts/cow.js --from USDC --to WETH --amount 100
node clawlett/scripts/cow.js --from USDC --to WETH --amount 100 --execute

# Swap by address (for tokens not in verified list)
node clawlett/scripts/swap.js --from USDC --to 0xa1832f7f4e534ae557f9b5ab76de54b1873e498b --amount 100 --execute

Trenches Trading

Create tokens and trade on Trenches bonding curves:

# Create a new token
node clawlett/scripts/trenches.js create --name "My Token" --symbol MTK --description "A cool token"
node clawlett/scripts/trenches.js create --name "My Token" --symbol MTK --description "desc" --initial-buy 0.01

# Buy tokens with ETH
node clawlett/scripts/trenches.js buy --token MTK --amount 0.01

# Sell tokens for ETH
node clawlett/scripts/trenches.js sell --token MTK --amount 1000
node clawlett/scripts/trenches.js sell --token MTK --all

# Token info
node clawlett/scripts/trenches.js info MTK

Token Discovery

Browse trending and top-performing tokens on Trenches:

node clawlett/scripts/trenches.js trending
node clawlett/scripts/trenches.js trending --window 1h --limit 5
node clawlett/scripts/trenches.js new
node clawlett/scripts/trenches.js top-volume
node clawlett/scripts/trenches.js gainers
node clawlett/scripts/trenches.js losers

Custom RPC

All scripts support --rpc flag for custom RPC endpoints:

node clawlett/scripts/balance.js --rpc https://base.llamarpc.com
node clawlett/scripts/swap.js --from ETH --to USDC --amount 0.1 --rpc https://base.llamarpc.com

Verified Tokens

Protected tokens can only resolve to verified addresses (scam protection):

Configuration

Config is stored per-chain in config/<chain>/wallet.json after initialization. The agent private key (config/agent.pk) is shared across all chains.

{
  "chainId": 8453,
  "owner": "0x...",
  "agent": "0x...",
  "safe": "0x...",
  "roles": "0x...",
  "roleKey": "0x..."
}

Environment Variables

Contracts

OpenClaw Integration

This skill is designed to work with OpenClaw agents. The agent can:

• Check wallet balances on request
• Get swap quotes via KyberSwap (default) or CoW Protocol
• Execute swaps after user confirmation
• Create tokens on Trenches
• Buy and sell Trenches tokens via factory
• Discover trending, new, and top-performing tokens
• Protect users from scam tokens

See SKILL.md for the skill specification.

Troubleshooting

Checkout Troubleshooting Guide for common issues.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT