Installation

This guide covers everything you need to install and configure Base Audit Bot, including prerequisites, API key generation, and deployment options.

Prerequisites

Before installing, ensure you have:

Required Software

Python 3.11 or higher - The bot uses modern Python features
Git - For cloning repositories and the bot itself
pip - Python package manager (included with Python)

Optional Software

Docker & Docker Compose - For containerized deployment
curl - For health check testing

API Keys Required

You must obtain API keys from all three services before the bot can operate:

Basescan API (free tier available)
Anthropic Claude API (requires credits)
Twitter API v2 (free tier with Essential access)

Installation Methods

Choose your preferred installation method:

Python Virtualenv

Recommended for development and testing

Docker

Recommended for production deployment

Method 1: Python Virtualenv

Install Python 3.11+

Verify your Python version:

python --version

If you need to install or upgrade Python:

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

Clone the Repository

git clone https://github.com/yourusername/base-audit-bot.git
cd base-audit-bot

Create Virtual Environment

python3.11 -m venv venv
source venv/bin/activate

Your terminal prompt should change to show (venv) when the virtual environment is active.

Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

This installs the following packages:

Package	Version	Purpose
web3	≥6.0.0	Ethereum/Base blockchain interaction
tweepy	≥4.14.0	Twitter API v2 client
anthropic	≥0.40.0	Claude AI API for auditing
flask	≥3.0.0	Webhook server
gitpython	≥3.1.40	Git repository operations
requests	≥2.31.0	HTTP requests
python-dotenv	≥1.0.0	Environment variable management
aiohttp	≥3.9.0	Async HTTP (optional)

Verify Installation

python -c "import web3, tweepy, anthropic, flask, git; print('All dependencies installed!')"

If successful, you’ll see: All dependencies installed!

Method 2: Docker

Install Docker

Install Docker and Docker Compose:

sudo apt update
sudo apt install docker.io docker-compose
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

Verify installation:

docker --version
docker-compose --version

Clone the Repository

git clone https://github.com/yourusername/base-audit-bot.git
cd base-audit-bot

Review Docker Configuration

The included Dockerfile defines the container:

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install git for cloning repos
RUN apt-get update && apt-get install -y git \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY *.py ./

RUN mkdir -p /app/data /app/logs /app/temp_repos

ENV PYTHONUNBUFFERED=1
ENV DATABASE_PATH=/app/data/bot.db
ENV TEMP_DIR=/app/temp_repos

EXPOSE 5000

CMD ["python", "bot.py"]

The docker-compose.yml orchestrates the deployment:

docker-compose.yml

version: '3.8'

services:
  audit-bot:
    build: .
    container_name: base-audit-bot
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
      - bot-temp:/app/temp_repos
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  bot-temp:
    driver: local

Obtaining API Keys

Basescan API Key

Create Account

Navigate to Basescan.org
Click “Sign In” → “Click to sign up”
Complete registration with email verification

Generate API Key

Go to API Keys page
Click “Add” to create a new API key
Give it a descriptive name (e.g., “Base Audit Bot”)
Copy the generated API key

Add to Configuration

.env

BASESCAN_API_KEY=YourBasescanApiKeyHere

The free tier allows 5 requests per second and 100,000 requests per day, which is sufficient for most use cases.

Anthropic API Key

Create Account

Visit Anthropic Console
Sign up with your email or Google account
Verify your email address

Add Credits

Navigate to “Settings” → “Billing”
Add payment method and credits
The bot uses Claude Sonnet 4, which costs:
- Input: $3 per million tokens
- Output: $15 per million tokens

A typical smart contract audit uses 2,000-5,000 tokens, costing

0.01-

0.10 per audit.

Generate API Key

Go to “API Keys” in the console
Click “Create Key”
Name it (e.g., “Base Audit Bot”)
Copy the key immediately (it won’t be shown again)

Add to Configuration

.env

ANTHROPIC_API_KEY=sk-ant-api03-YourAnthropicKeyHere

Twitter API Keys

Twitter requires the most credentials (5 different keys/tokens):

Create Developer Account

Go to Twitter Developer Portal
Sign in with your Twitter account
Click “Sign up for Free Account”
Complete the application form:
- Choose “Hobbyist” → “Making a bot”
- Describe your bot’s purpose
- Agree to terms and conditions

Create Project and App

In the Developer Portal, click “Projects & Apps”
Create a new Project (name: “Base Audit Bot”)
Create an App within the project
Save the API Key and API Secret shown

Configure App Permissions

Go to your app settings
Navigate to “User authentication settings”
Click “Set up”
Enable OAuth 1.0a
Set permissions to Read and Write
Add callback URL (can be placeholder: https://example.com)
Save changes

Generate Access Tokens

Go to “Keys and Tokens” tab
Under “Authentication Tokens”, click “Generate” for:
- Access Token
- Access Token Secret
Also generate a Bearer Token if not already present
Copy all tokens immediately

Add to Configuration

You should now have all 5 credentials:

.env

TWITTER_API_KEY=YourApiKeyHere
TWITTER_API_SECRET=YourApiSecretHere
TWITTER_ACCESS_TOKEN=YourAccessTokenHere
TWITTER_ACCESS_SECRET=YourAccessSecretHere
TWITTER_BEARER_TOKEN=YourBearerTokenHere

Keep these credentials secret! Never commit them to version control.

Configuration

Create .env File

Copy the example environment file:

cp .env.example .env

Edit Configuration

Open .env in your editor and configure all settings:

.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

# Database
DATABASE_PATH=./data/bot.db

# Temporary Directory for Cloning
TEMP_DIR=./temp_repos

Configuration Reference

Variable	Description	Default	Required
`BASE_RPC_URL`	Base mainnet RPC endpoint	`https://mainnet.base.org`	Yes
`BASESCAN_API_KEY`	Basescan API key for contract verification	-	Yes
`ANTHROPIC_API_KEY`	Anthropic API key for Claude	-	Yes
`TWITTER_API_KEY`	Twitter OAuth 1.0a consumer key	-	Yes
`TWITTER_API_SECRET`	Twitter OAuth 1.0a consumer secret	-	Yes
`TWITTER_ACCESS_TOKEN`	Twitter access token	-	Yes
`TWITTER_ACCESS_SECRET`	Twitter access token secret	-	Yes
`TWITTER_BEARER_TOKEN`	Twitter API v2 bearer token	-	No*
`WEBHOOK_SECRET`	Secret for GitHub webhook verification	-	No
`WEBHOOK_PORT`	Port for webhook server	`5000`	No
`SCAN_INTERVAL_MINUTES`	Minutes between scans	`15`	No
`BLOCKS_TO_SCAN`	Number of blocks to scan per cycle	`100`	No
`MIN_CONTRACT_SIZE`	Minimum bytecode size (bytes)	`100`	No
`LOG_LEVEL`	Logging verbosity	`INFO`	No
`DATABASE_PATH`	SQLite database location	`./data/bot.db`	No
`TEMP_DIR`	Temporary directory for clones	`./temp_repos`	No

*Bearer token is required for some Twitter API v2 endpoints like DM reading.

Generate Webhook Secret

If you plan to use GitHub webhooks, generate a secure random secret:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Add it to your .env:

.env

WEBHOOK_SECRET=your_generated_secret_here

Running the Bot

Python Virtualenv

python bot.py

Docker

docker-compose up -d

Verification

Check Bot Startup

Verify the bot initializes all components:

# For Python
tail -f ./logs/bot.log

# For Docker
docker-compose logs audit-bot

You should see:

INFO - Initializing Base Audit Bot...
INFO - Database initialized
INFO - Connected to Base mainnet. Chain ID: 8453
INFO - Blockchain scanner initialized
INFO - GitHub finder initialized
INFO - Auditor initialized
INFO - Twitter bot initialized
INFO - Base Audit Bot initialized successfully
INFO - Starting main loop (interval: 15 minutes)

Test Webhook Server

If webhooks are enabled, test the health endpoint:

curl http://localhost:5000/health

Expected response:

{"status": "healthy"}

Verify Database Creation

Check that the SQLite database was created:

ls -lh ./data/bot.db

Inspect tables:

sqlite3 ./data/bot.db ".tables"

Expected output:

audits          contracts       monitored_repos tweets          blocklist

Next Steps

Configuration

Customize bot behavior and settings

Webhook Setup

Configure GitHub webhooks for repository monitoring

Deployment

Deploy to production environments

Troubleshooting

Common issues and solutions

Get Started

Core Concepts

Guides

Components

Installation

Installation

Prerequisites

Required Software

Optional Software

API Keys Required

Installation Methods

Python Virtualenv

Docker

Method 1: Python Virtualenv

Method 2: Docker

Obtaining API Keys

Basescan API Key

Anthropic API Key

Twitter API Keys

Configuration

Running the Bot

Python Virtualenv

Docker

Verification

Next Steps

Configuration

Webhook Setup

Deployment

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Components

​Installation

​Prerequisites

​Required Software

​Optional Software

​API Keys Required

​Installation Methods

Python Virtualenv

Docker

​Method 1: Python Virtualenv

​Method 2: Docker

​Obtaining API Keys

​Basescan API Key

​Anthropic API Key

​Twitter API Keys

​Configuration

​Running the Bot

​Python Virtualenv

​Docker

​Verification

​Next Steps

Configuration

Webhook Setup

Deployment

Troubleshooting

Build docs developers (and LLMs) love

Installation

Prerequisites

Required Software

Optional Software

API Keys Required

Installation Methods

Method 1: Python Virtualenv

Method 2: Docker

Obtaining API Keys

Basescan API Key

Anthropic API Key

Twitter API Keys

Configuration

Running the Bot

Python Virtualenv

Docker

Verification

Next Steps