Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 18+ - JavaScript runtime
  • Python 3.11+ - Backend runtime
  • Redis - Caching and task queue
  • MetaMask or Coinbase Wallet - For blockchain interactions

​
Installation

1

Clone the Repository

Clone the Proteus repository and navigate to the project directory:
git clone https://github.com/timepoint-ai/proteus.git
cd proteus
2

Install Node Dependencies

Install JavaScript dependencies for smart contract development:
npm install
3

Set Up Python Environment

Create a virtual environment and install Python dependencies:
# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies with test tools
pip install -e ".[test]"
4

Configure Environment Variables

Copy the example environment file and configure it:
cp .env.example .env
Update .env with the following required variables:
.env
# Network Configuration
NETWORK=base-sepolia
CHAIN_ID=84532
RPC_URL=https://sepolia.base.org

# Deployer Wallet (for contract deployment)
DEPLOYER_PRIVATE_KEY=your_private_key_here

# Redis
REDIS_URL=redis://localhost:6379

# Firebase (for email authentication)
FIREBASE_API_KEY=your_key
FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
FIREBASE_PROJECT_ID=your-project
FIREBASE_APP_ID=your_app_id

# Coinbase (for embedded wallet)
COINBASE_PROJECT_ID=your_project_id

​
Firebase Setup

Proteus uses Firebase for email authentication:
1

Create Firebase Project

  1. Go to Firebase Console
  2. Create a new project
  3. Note your project credentials
2

Enable Authentication

  1. Navigate to Authentication > Sign-in method
  2. Enable Email/Password
  3. Enable Email link (passwordless sign-in)
3

Configure Authorized Domains

Add your development domain (e.g., localhost) to the authorized domains list.
4

Copy Credentials

Copy your Firebase credentials to the .env file created earlier.

​
Get Test ETH

To deploy contracts and interact with the BASE Sepolia testnet, you’ll need test ETH:
  1. Visit the BASE Sepolia Faucet
  2. Request 0.1 ETH to your deployer wallet address
  3. Wait for the transaction to confirm (usually 1-2 minutes)

​
Compile Smart Contracts

Compile the Solidity smart contracts: 
make compile

​
Deploy Contracts

Deploy contracts to BASE Sepolia testnet: 
make deploy-testnet

​
Verify Contracts

After deployment, verify your contracts on Basescan: 
npx hardhat verify --network baseSepolia <CONTRACT_ADDRESS>

​
Contract Addresses

The following contracts are already deployed on BASE Sepolia:
ContractAddressStatus
PredictionMarketV20x5174Da96BCA87c78591038DEe9DB1811288c9286Recommended
GenesisNFT0x1A5D4475881B93e876251303757E60E524286A2460/100 minted
PredictionMarket (V1)0x667121e8f22570F2c521454D93D6A87e44488d93Deprecated
Use PredictionMarketV2 for all new development. It includes:
  • Complete market lifecycle (create → submit → resolve → claim)
  • On-chain Levenshtein distance for winner determination
  • 7% platform fee with pull-based collection
V1 is deprecated (no resolution mechanism).

​
Run the Application

1

Start Redis

Start the Redis server in a terminal:
redis-server
Verify Redis is running:
redis-cli ping
# Expected output: PONG
2

Start Flask Backend

In a new terminal, activate your virtual environment and start the Flask server:
source .venv/bin/activate
python main.py
The server will start at http://localhost:5000
3

Start Celery Worker (Optional)

For background tasks, start a Celery worker in another terminal:
source .venv/bin/activate
celery -A app.celery worker --loglevel=info
4

Access the Application

Open your browser and navigate to:
http://localhost:5000

​
Troubleshooting

Get more test ETH from the BASE Sepolia faucet.
  • Check gas limits in hardhat.config.js
  • Verify RPC endpoint is responding
  • Ensure wallet has enough ETH
  • Verify authorized domains include your URL
  • Check API key restrictions in Google Cloud Console
  • Confirm email/password authentication is enabled
Ensure Redis server is running:
redis-cli ping
If it returns “Connection refused”, start Redis:
redis-server

​
Next Steps

Run Tests

Learn how to run the 259+ test suite

Architecture

Understand the system design

Deploy

Deploy to Railway or mainnet

API Reference

Explore the API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us