Skip to main content

​
Quick Start

Get the Base Audit Bot up and running in minutes. This guide will take you from zero to a fully operational bot monitoring the Base blockchain.
Prerequisites: Python 3.11+, Git, and API keys for Basescan, Anthropic, and Twitter. See Installation for detailed setup.
1

Clone the Repository

First, clone or download the Base Audit Bot repository:
git clone https://github.com/yourusername/base-audit-bot.git
cd base-audit-bot
2

Create Virtual Environment

Set up a Python virtual environment to isolate dependencies:
python -m venv venv
source venv/bin/activate
3

Install Dependencies

Install all required Python packages:
pip install -r requirements.txt
This installs:
  • web3>=6.0.0 - Blockchain interaction
  • anthropic>=0.40.0 - Claude AI API
  • tweepy>=4.14.0 - Twitter integration
  • flask>=3.0.0 - Webhook server
  • gitpython>=3.1.40 - Repository cloning
  • requests>=2.31.0 - HTTP client
  • python-dotenv>=1.0.0 - Environment configuration
4

Configure Environment

Copy the environment template and add your API keys:
cp .env.example .env
Edit .env with your favorite editor and add your credentials:
.env
# Base Chain Configuration
BASE_RPC_URL=https://mainnet.base.org
BASESCAN_API_KEY=your_basescan_api_key_here

# Anthropic API
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Twitter API v2 Credentials
TWITTER_API_KEY=your_twitter_api_key_here
TWITTER_API_SECRET=your_twitter_api_secret_here
TWITTER_ACCESS_TOKEN=your_twitter_access_token_here
TWITTER_ACCESS_SECRET=your_twitter_access_secret_here
TWITTER_BEARER_TOKEN=your_twitter_bearer_token_here

# Webhook Configuration (optional)
WEBHOOK_SECRET=your_random_webhook_secret_here
WEBHOOK_PORT=5000

# Bot Configuration
SCAN_INTERVAL_MINUTES=15
BLOCKS_TO_SCAN=100
MIN_CONTRACT_SIZE=100
LOG_LEVEL=INFO
See Installation for detailed instructions on obtaining each API key.
5

Run the Bot

Start the bot:
python bot.py
You should see output similar to:
2026-03-03 10:00:00,123 - __main__ - INFO - Initializing Base Audit Bot...
2026-03-03 10:00:00,234 - __main__ - INFO - Database initialized
2026-03-03 10:00:00,345 - scanner - INFO - Connected to Base mainnet. Chain ID: 8453
2026-03-03 10:00:00,456 - __main__ - INFO - Blockchain scanner initialized
2026-03-03 10:00:00,567 - __main__ - INFO - GitHub finder initialized
2026-03-03 10:00:00,678 - __main__ - INFO - Auditor initialized
2026-03-03 10:00:00,789 - __main__ - INFO - Twitter bot initialized
2026-03-03 10:00:00,890 - __main__ - INFO - Webhook server configured on port 5000
2026-03-03 10:00:00,901 - __main__ - INFO - Base Audit Bot initialized successfully
2026-03-03 10:00:01,012 - __main__ - INFO - Starting main loop (interval: 15 minutes)
2026-03-03 10:00:01,123 - __main__ - INFO - Starting scan cycle...
2026-03-03 10:00:01,234 - __main__ - INFO - Scanned blocks 12345600 to 12345700, found 3 deployments
6

Verify Operation

The bot is now running! Here’s what it’s doing:
  • Scanning blocks every 15 minutes (configurable)
  • Finding contracts with bytecode size ≥ 100 bytes
  • Checking verification status on Basescan
  • Discovering GitHub repos from verified source code
  • Running audits with Claude AI
  • Posting to Twitter when issues are found
Check the logs in ./logs/bot.log for detailed activity:
tail -f ./logs/bot.log

​
What Happens Next?

Once running, the bot operates autonomously:
  1. Every 15 minutes (by default), it scans the latest 100 blocks on Base
  2. For each new contract deployment found:
    • Checks if the contract is verified on Basescan
    • Attempts to find the GitHub repository
    • Clones the repo and finds all Solidity files
    • Sends each file to Claude for security analysis
    • Aggregates findings by severity (Critical/High/Medium/Low)
    • Posts audit results to Twitter with contract details
  3. Monitors repositories for updates via webhooks
  4. Posts daily summaries at midnight UTC
  5. Responds to DM commands for manual audit requests

​
Expected Output

​
Successful Contract Audit

2026-03-03 10:15:23,456 - __main__ - INFO - Processing new contract: 0x1234567890abcdef1234567890abcdef12345678
2026-03-03 10:15:24,567 - __main__ - INFO - Saved contract 0x1234... (verified: True, repo: https://github.com/user/token)
2026-03-03 10:15:25,678 - __main__ - INFO - Auditing contract 0x1234... from repo https://github.com/user/token
2026-03-03 10:15:26,789 - auditor - INFO - Cloning https://github.com/user/token
2026-03-03 10:15:30,890 - auditor - INFO - Found 5 Solidity files to audit
2026-03-03 10:15:31,901 - auditor - INFO - Auditing: TokenContract.sol
2026-03-03 10:15:45,012 - auditor - INFO - Auditing: Vault.sol
2026-03-03 10:16:00,123 - __main__ - INFO - Audit complete: 3 issues found
2026-03-03 10:16:01,234 - __main__ - INFO - Posted audit tweet: 1234567890123456789

​
Unverified Contract (Skipped)

2026-03-03 10:20:15,345 - __main__ - INFO - Processing new contract: 0xabcdef1234567890abcdef1234567890abcdef12
2026-03-03 10:20:16,456 - __main__ - INFO - Saved contract 0xabcdef... (verified: False, repo: None)

​
Testing the Bot

Before running in production, test with a short scan interval and limited block range:
.env
SCAN_INTERVAL_MINUTES=5
BLOCKS_TO_SCAN=10

​
Test DM Commands

Send a direct message to your Twitter bot account: 
audit 0x1234567890abcdef1234567890abcdef12345678
The bot should respond with: 
Checking contract 0x1234567890abcdef1234567890abcdef12345678...
And after the audit completes: 
Audit complete for 0x1234567890abcdef1234567890abcdef12345678. Check our timeline for results.

​
Docker Quick Start

Prefer containers? Use Docker Compose:
1

Configure Environment

Create your .env file as described above.
2

Build and Run

docker-compose up -d
3

View Logs

docker-compose logs -f audit-bot
4

Stop the Bot

docker-compose down

​
Troubleshooting

​
Bot won’t start

python --version
# Should be 3.11 or higher

​
No contracts being found

  • Check RPC connection: Verify BASE_RPC_URL is accessible
  • Increase block range: Set BLOCKS_TO_SCAN=1000 for more coverage
  • Lower size threshold: Set MIN_CONTRACT_SIZE=50 to catch smaller contracts

​
Twitter posting fails

  • Verify all 5 Twitter credentials are set correctly
  • Check app permissions include read/write access
  • Ensure rate limits aren’t exceeded (bot respects limits)

​
Audits not running

  • Check ANTHROPIC_API_KEY is valid and has credits
  • Verify contracts are verified on Basescan
  • Check logs for specific Claude API errors

​
Next Steps

Installation Guide

Detailed setup instructions and API key generation

Configuration

Customize scan intervals, webhook setup, and more

Architecture

Understand how the bot components work together

API Reference

Explore the codebase and extend functionality

Build docs developers (and LLMs) love

Get started for freeTalk to us