bots

What This Skill Does

The Towns Protocol bot skill provides a comprehensive toolkit for developers to build, deploy, and manage intelligent agents within the Towns decentralized messaging ecosystem. It streamlines the integration of blockchain operations, interactive user interfaces, and custom event handlers using the official @towns-protocol/bot SDK. Whether you are building an automated community moderator, a token-gated DAO assistant, or an interactive transaction helper, this skill manages the complexities of the two-wallet architecture, message threading, and secure interaction requests required for production-grade Towns applications.

Installation

To integrate this skill, use the ClawHub CLI: clawhub install openclaw/skills/skills/andreyz/towns-protocol. After installation, ensure you have initialized your project using bunx towns-bot init my-bot. You must configure your APP_PRIVATE_DATA and JWT_SECRET environment variables. Ensure the bot's gas wallet (associated with bot.viem.account.address) is adequately funded with Base ETH, as all on-chain transactions require network fees to be processed successfully.

Use Cases

• Automated Moderation: Deploy bots that monitor channel activity, verify user permissions via hasAdminPermission, and execute ban/unban commands based on custom logic.
• Token-Gated Community Tools: Build bots that verify asset ownership on-chain before granting access to exclusive channels or threads.
• Transaction Facilitation: Create interactive forms using sendInteractionRequest to allow users to sign transactions or approve contract calls directly within the chat interface.
• Community Management: Implement scheduled announcements, reward distribution, and automated onboarding flows for new DAO members.

Example Prompts

1. "towns bot: create a new slash command named 'verify' that checks if the user holds at least 100 TNS tokens before replying."
2. "makeTownsBot: set up a message handler that listens for @mentions, ensures the mention includes the correct <@{userId}> format, and replies in a thread."
3. "towns bot: guide me through the deployment process for my bot on Render, specifically how to handle environment variable injection for my private credentials."

Tips & Limitations

• Safety First: Always verify that receipt.status === 'success' when performing blockchain operations. Do not assume a txHash implies success.
• Wallet Architecture: Remember that the gas wallet and the treasury wallet (appAddress) serve distinct purposes. Only use the gas wallet for paying network fees.
• Interaction Handling: Slash commands and message handlers are strictly separate. Do not expect onMessage to capture input from slash command triggers.
• Mentions: You must always include the mentions array in your options when using the <@{userId}> syntax, or the client will not render the mention correctly.