Skip to main content

​
Setup & Installation

Get the PolySimulator API running locally in under 5 minutes.

​
Prerequisites

RequirementVersionPurpose
Python3.11+Backend runtime
PostgreSQL14+Database (or Supabase)
Redis7+Price caching
Node.js18+Frontend (optional)
Docker24+Containerized deployment

​
Quick Setup

1

Clone the repository

git clone https://github.com/Bavariance/polysimulator.git
cd polysimulator
2

Configure environment

Create backend/.env with your credentials:
# Database
DATABASE_URL=postgresql+psycopg2://postgres:password@localhost:5432/polysimulator

# Supabase Auth
SUPABASE_PROJECT_URL=https://your-project.supabase.co
SUPABASE_JWT_SECRET=your-jwt-secret

# Redis
REDIS_URL=redis://localhost:6379/0

# Trading mode
TRADING_MODE=virtual

# Price caching (optional — these are defaults)
PRICE_CACHE_TTL_SECONDS=45
PRICE_POLL_INTERVAL_SECONDS=5
MAX_TRACKED_HOT_MARKETS=150
3

Start infrastructure

docker compose up redis -d
If using a local PostgreSQL instead of Supabase:
docker compose up redis db -d
4

Install Python dependencies

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
5

Run database migrations

alembic upgrade head
6

Start the API server

uvicorn app.main:app --reload --port 8000
The API is now running at http://localhost:8000. Visit http://localhost:8000/docs for the interactive Swagger UI.

​
Environment Variables Reference

​
Required

VariableDescription
DATABASE_URLPostgreSQL connection string
SUPABASE_PROJECT_URLSupabase project URL
SUPABASE_JWT_SECRETJWT secret for token verification
REDIS_URLRedis connection string

​
Optional

VariableDefaultDescription
TRADING_MODEvirtualvirtual or live
PRICE_CACHE_TTL_SECONDS45Redis price cache TTL
PRICE_POLL_INTERVAL_SECONDS5Background price poll interval
MAX_TRACKED_HOT_MARKETS150Max markets to track prices for
REDIS_FALLBACK_URLS—Comma-separated fallback Redis URLs

​
Live Mode Only

VariableDescription
POLYMARKET_API_KEYPolymarket CLOB API key
POLYMARKET_API_SECRETPolymarket CLOB API secret
POLYMARKET_API_PASSPHRASEPolymarket CLOB API passphrase

​
Verify Installation

# Health check
curl http://localhost:8000/v1/health
# → {"status": "ok", "version": "1.0.0"}

# Readiness check (DB + Redis)
curl http://localhost:8000/v1/health/ready
# → {"status": "healthy", "database": "ok", "redis": "ok"}

​
Next Steps