README.md

metadata

title: WagerKit
emoji: 📊
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
license: mit

WagerKit 🎯

Real-time prediction market analysis with integrity scoring

WagerKit aggregates data from multiple prediction market sources (Polymarket, Kalshi, PredictIt) and provides comprehensive integrity analysis for each market.

✨ Features

• 📈 Multi-Source Aggregation: Compare odds across leading prediction markets
• 🎯 Integrity Scoring: 4-component analysis (Clarity, Liquidity, Agreement, Volatility)
• 📊 Visual Analytics: Real-time odds history charts with Chart.js
• 📥 Export Tools: PDF dossiers, CSV data exports, JSON metadata
• ⚡ Background Processing: BullMQ-powered workers for instant dashboard loads
• 🎨 Modern UI: Dark theme, responsive design with Tailwind CSS

🏗️ Architecture

┌─────────────────────────────────────┐
│      Docker Container (HF Space)    │
│                                     │
│  Redis ──► NestJS Backend (BullMQ) │
│              ↓                      │
│         Next.js Frontend            │
│           (Port 7860)               │
└─────────────────────────────────────┘

🚀 Quick Start

On Hugging Face Spaces

Simply clone this Space or visit the live demo!

Local Development

# Clone the repository
git clone <your-repo-url>
cd wagerkit

# Start with Docker Compose
docker-compose up

# Or run individually:
# Terminal 1: Redis
docker run -d -p 6379:6379 redis:7-alpine

# Terminal 2: Backend
cd backend && npm install && npm run start:dev

# Terminal 3: Frontend
cd frontend && npm install && npm run dev

Access at: http://localhost:3000

📊 Integrity Score Formula

Overall Score = 100 × (0.40×C + 0.30×L + 0.20×A + 0.10×V)

• C (Market Clarity): Resolution criteria quality, source coverage
• L (Liquidity Depth): Trading volume, update frequency
• A (Cross-Source Agreement): RMSE between sources
• V (Volatility Sanity): Price stability, spike detection

🛠️ Tech Stack

Backend:

• NestJS 10 (TypeScript)
• BullMQ (background jobs)
• Redis (job queue & cache)

Frontend:

• Next.js 14 (App Router)
• React 18
• Chart.js (visualization)
• Tailwind CSS (styling)
• jsPDF (PDF export)

📦 Deployment

See DEPLOYMENT.md for detailed instructions on:

• Hugging Face Spaces setup
• Docker configuration
• Environment variables
• Local development

🎮 Usage

1. Dashboard: View all markets with processing status badges
2. Click any card: Navigate to detailed market analysis
3. View Charts: Compare historical odds across 4 sources
4. Export Data: Download PDF dossiers, CSV odds history, or JSON metadata

📁 Project Structure

wagerkit/
├── backend/                 # NestJS backend
│   ├── src/
│   │   ├── markets/        # Markets module (BullMQ workers)
│   │   ├── auth/           # Auth module (unused in demo)
│   │   └── main.ts
│   ├── Dockerfile          # Backend Docker image
│   └── package.json
├── frontend/               # Next.js frontend
│   ├── src/
│   │   ├── app/           # App router pages
│   │   ├── components/    # Reusable components
│   │   └── lib/           # API client
│   ├── Dockerfile         # Frontend Docker image
│   └── package.json
├── Dockerfile             # Multi-stage build (HF Spaces)
├── docker-compose.yml     # Local development
├── DEPLOYMENT.md          # Detailed deployment guide
└── README.md

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License

🙏 Acknowledgments

Built with data from leading prediction markets. This is a demonstration project showcasing real-time data aggregation and integrity analysis techniques.

---

Documentation: DEPLOYMENT.md Each market includes:

• Integrity Score (0-100) with 4 sub-components:
  • Market Clarity (40% weight)
  • Liquidity Depth (30% weight)
  • Cross-Source Agreement (20% weight)
  • Volatility Sanity (10% weight)
• Odds History Chart - 24-hour price trends from 3 sources
• Data Sources - Polymarket, Kalshi, PredictIt
• Export Options:
  • ✅ Download Dossier (PDF)
  • ✅ Download Dossier (JSON)
  • ✅ Export Odds CSV
  • ✅ Export Integrity CSV

📊 Integrity Score Formula

Score = 100 × (0.40×C + 0.30×L + 0.20×A + 0.10×V)

Where:

• C = Market Clarity
• L = Liquidity Depth
• A = Cross-Source Agreement (RMSE-based)
• V = Volatility Sanity (includes spike detection)

🔧 Tech Stack

Backend

• NestJS 10
• TypeScript
• JWT Authentication (ready but disabled)
• Express.js

Frontend

• Next.js 14
• React 18
• TypeScript
• TailwindCSS
• Chart.js (for odds visualization)
• jsPDF (for PDF exports)

📝 API Endpoints

Markets

• GET /api/markets - List all markets
• GET /api/markets/:slug - Get market detail with integrity scores
• GET /api/markets/:slug/export/odds-csv - Export odds history CSV
• GET /api/markets/:slug/export/integrity-csv - Export integrity scores CSV
• GET /api/markets/:slug/export/dossier-json - Export full dossier JSON

Authentication (Optional)

• POST /api/auth/login - Login endpoint (not required for demo)

🔑 Environment Variables

Backend (backend/.env)

JWT_SECRET=wagerkit-jwt-secret-key-2024
DOME_API_KEY=your-dome-api-key-here
PORT=3001

Frontend (frontend/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:3001/api

🎨 Design Theme

• Dark purple/blue gradient background
• Card-based UI with #12121e background
• Purple (#6b21a8) and blue (#3b82f6) accent colors
• Responsive design with Tailwind CSS

🔮 DOME API Integration (Future)

The app is designed to integrate with the DOME API. To enable real data:

1. Install SDK:

   cd backend
   npm install @dome-api/sdk
   

2. Add API Key to backend/.env:

   DOME_API_KEY=your-actual-api-key
   

3. Update Service in backend/src/markets/markets.service.ts:

   • Uncomment the DOME SDK import
   • Replace simulated data methods with real API calls

Currently uses simulated data with realistic patterns for demo purposes.

🚢 Deployment

Build Production

# Backend
cd backend
npm run build
npm run start:prod

# Frontend
cd frontend
npm run build
npm start

📋 Notes

• Authentication is disabled for easy demo access
• Data is simulated but follows real market patterns
• All export features are fully functional
• Runs entirely locally - no external dependencies required

---

Built for client demo - February 2026