Hypixel Bazaar Trader — Skyblock Oracle

Real-time market data platform and paper trading engine for Hypixel Skyblock's in-game bazaar. Ingests live bazaar prices, stores them as time-series data, and runs an automated paper trading strategy engine against them — no macros, no in-game automation, purely simulated.

Built as a hands-on project to learn a modern async Python + Next.js + TimescaleDB stack end to end: ingestion, storage, API, frontend, and a strategy backtester.

What it does

• Ingests live bazaar data for 1,500+ products every minute, bulk-inserted into a TimescaleDB hypertable with 30-day retention and idempotent writes (safe to restart/retry without duplicating rows).
• Runs a paper trading engine — composable strategy and filter abstractions, volume-based fill simulation, four live strategies on a 3-second loop, percentage-based position sizing, a 30% capital reserve, and committed-coin guards so it never over-commits capital to open orders.
• Serves a profitability leaderboard ranking all 1,900+ tracked items by flip profit, backed by a query optimized from 21s to 67ms (indexed subquery + join, instead of a naive per-item join across the full snapshot history).
• Backtests strategies against historical data via a visual strategy builder — compose filters into strategies, strategies into a profile, run it against any date range, see the resulting equity curve.

Architecture

┌──────────────┐      ┌──────────────┐      ┌──────────────────┐
│  Next.js     │─────▶│   FastAPI    │─────▶│  PostgreSQL +    │
│  (frontend)  │      │   (backend)  │      │  TimescaleDB     │
└──────────────┘      └──────┬───────┘      └─────▲────────────┘
                             │                    │
                             ▼                    │ writes
                      ┌──────────────┐            │
                      │  Poller      │────────────┘
                      │  (worker)    │
                      └──────────────┘
                      ┌──────────────┐
                      │  Trader      │
                      │  (worker)    │
                      └──────────────┘

Four independent, single-responsibility services, each in its own container:

Service	Role
poller	Fetches the Hypixel bazaar API every 60s, upserts item metadata, bulk-inserts price snapshots
backend	FastAPI — read endpoints, flip calculator, leaderboard, portfolio/order CRUD, backtest engine
frontend	Next.js — item search, price charts, flips leaderboard, trader dashboard, strategy builder + backtester
trader	Paper trading loop — evaluates strategies against live prices every 3s, places/fills simulated orders

backend and trader share strategy/filter logic from a top-level shared/ package, so trading decisions are never duplicated or allowed to drift between live trading and backtesting.

Tech stack

Python (FastAPI, SQLAlchemy 2.0 async, asyncpg, httpx), PostgreSQL 17 + TimescaleDB, Next.js + TypeScript + Tailwind, Docker Compose.

Running locally

Requires Docker and Docker Compose.

1. Create a .env in the repo root with:

   POSTGRES_USER=...
   POSTGRES_PASSWORD=...
   POSTGRES_DB=bazaar_tracker
   POSTGRES_HOST=localhost
   POSTGRES_PORT=5432
   NEXT_PUBLIC_API_URL=http://localhost:8000
   INTERNAL_API_URL=http://backend:8000
   LOG_LEVEL=INFO
   TRADER_PORTFOLIO_ID=1
   TRADER_INITIAL_COINS=1000000
   TRADER_PROFILE=basic
   

2. docker compose up --build
3. Frontend: http://localhost:3000 · API docs: http://localhost:8000/docs

Schema is created automatically on first run via db/init/. Give the poller a few minutes to populate enough history before the price charts and flip calculator have anything meaningful to show.

Project structure

hypixel-bazaar-trader/
├── poller/     # ingestion worker
├── backend/    # FastAPI service
├── frontend/   # Next.js app
├── trader/     # paper trading worker
├── shared/     # strategy/filter engine shared by backend + trader
├── shard-parser/  # offline tool generating shard fusion data for the frontend
└── db/init/    # schema + hypertable + retention policy