Predict.fun Developer Studio

An independent developer-focused market data explorer for the official Predict.fun Testnet API.

Independent developer tool. Not affiliated with, endorsed by, or maintained by Predict.fun.

This project was built as a demo to support an application for Predict.fun Mainnet API access. It is intentionally scoped to read-only market data exploration — there is no trading, no wallet integration, and no database.

---

Screenshots

Dashboard

Market Explorer

Market Detail (Overview, Outcomes, Orderbook)

API Explorer

API Status

---

What this is

Predict.fun Developer Studio is an independent market-data exploration demo built with the official Predict.fun Testnet API. It provides market discovery, market detail inspection, orderbook visualization, API diagnostics, and raw-response exploration.

The goal is a credible, working demo — not a production trading platform.

---

Features

• Dashboard — live connection status, market counts for the current result set, latest API latency, and a recent-markets table.
• Market Explorer — search, status and market-variant filters, cursor-based pagination, and loading/empty/error states.
• Market Detail — overview, outcomes with best bid/ask, a live orderbook (near-real-time REST polling at configurable intervals), and collapsible raw JSON panels.
• API Explorer — a safe, preset-driven request builder for the five core endpoints, with request URL preview, status code, latency, rate-limit headers, and formatted response/error JSON.
• API Status — backend health, Predict.fun base URL, API key configuration state, the latest upstream request's diagnostics, and an on-demand connectivity test.
• Light and dark themes, responsive layout, and defensive rendering of missing/null/unknown fields (the Predict.fun API is Beta).

---

Architecture

React + TypeScript (Vite)      FastAPI (Python)              Predict.fun Testnet API
┌───────────────────────┐      ┌───────────────────────┐      ┌───────────────────────┐
│ Dashboard              │      │ /api/health            │      │                       │
│ Market Explorer        │ ───► │ /api/markets           │ ───► │ https://api-testnet   │
│ Market Detail          │      │ /api/markets/{id}      │      │ .predict.fun/v1       │
│ API Explorer           │      │ /api/markets/{id}/     │      │                       │
│ API Status             │      │   orderbook            │      │                       │
│                        │      │ /api/categories        │      │                       │
│                        │      │ /api/tags              │      │                       │
│                        │      │ /api/status            │      │                       │
└───────────────────────┘      └───────────────────────┘      └───────────────────────┘

The frontend never talks to Predict.fun directly. Every request goes through the local FastAPI backend, which centralizes all upstream calls inside a single PredictClient. This is what makes the API Explorer safe: it only ever calls the five whitelisted local endpoints (no arbitrary URL proxy, no SSRF surface).

---

Tech stack

Frontend: React 19, TypeScript, Vite, Tailwind CSS v4, React Router, TanStack Query, Lucide React

Backend: FastAPI, Python 3.12+, httpx (async), Pydantic v2, pydantic-settings, Uvicorn

No database. No authentication. No Docker. No wallet or trading logic.

---

Project structure

predict-demo/
├── backend/
│   ├── app/
│   │   ├── main.py            FastAPI app, CORS, error handling, lifespan
│   │   ├── config.py          Typed settings (env vars)
│   │   ├── predict_client.py  Single async client for the Predict.fun API
│   │   ├── schemas.py         Pydantic models owned by this backend
│   │   └── routes.py          /api/* route handlers
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/                client.ts, queries.ts, types.ts
│   │   ├── components/         Layout, DataState, JsonViewer, Badge, ...
│   │   ├── pages/               Dashboard, MarketExplorer, MarketDetail, ApiExplorer, ApiStatus
│   │   ├── lib/format.ts        Defensive formatting helpers
│   │   ├── App.tsx
│   │   └── main.tsx
│   └── package.json
├── screenshots/
├── .env.example
└── README.md

---

Setup

Prerequisites

• Python 3.12+
• Node.js 20+
• No API key required — the Testnet API is open

Environment variables

Copy .env.example to backend/.env (backend) and to frontend/.env (frontend), or create them directly:

PREDICT_API_BASE_URL=https://api-testnet.predict.fun/v1
PREDICT_API_KEY=
PREDICT_REQUEST_TIMEOUT_SECONDS=15
CORS_ORIGINS=http://localhost:5173

VITE_API_BASE_URL=http://localhost:8000/api
VITE_APP_NAME=Predict.fun Developer Studio

If PREDICT_API_KEY is left empty, the backend never sends an x-api-key header — required for Testnet, which does not need a key. If a key is later configured (e.g. for Mainnet), it is only ever attached server-side and is never exposed to the frontend or returned in any API response.

---

Run commands

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS/Linux
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

The backend starts at http://localhost:8000. Interactive API docs are available at http://localhost:8000/docs.

Frontend

cd frontend
npm install
npm run dev

The frontend starts at http://localhost:5173.

Production build

cd frontend
npm run build

---

API routes (local backend)

Method	Path	Description
GET	/api/health	Backend liveness check
GET	/api/markets	List markets (supports limit, cursor, status, marketVariant, categorySlug, title)
GET	/api/markets/{market_id}	Market detail
GET	/api/markets/{market_id}/orderbook	Orderbook (bids/asks, best bid/ask, spread derived client-side)
GET	/api/categories	Category/event listings
GET	/api/tags	Tag taxonomy
GET	/api/status	Latest upstream request diagnostics (latency, status code, rate-limit headers)
POST	/api/status/check	Runs a minimal market-list request to refresh connectivity status

All routes return either {"success": true, "data": ...} or a normalized error:

{
  "success": false,
  "error": { "type": "upstream_error", "message": "...", "statusCode": 404 }
}

---

Known limitations

• Testnet contains non-production data and is not a Mainnet mirror.
• Mainnet access requires an approved API key.
• The Predict.fun API is Beta — fields can be missing, null, or unannounced; the UI renders — for anything unavailable rather than guessing.
• No trading, no wallet, no database, no historical recorder.
• Orderbook updates use REST polling (configurable 2s–30s, or off), not a public trade WebSocket stream.
• Market Explorer's search/status/variant filters apply to the currently loaded page of results (labeled "current result set"), since upstream server-side filtering behavior is not guaranteed to be exhaustive during Beta.

---

Mainnet configuration

To point this demo at Mainnet once an API key is approved, update backend/.env:

PREDICT_API_BASE_URL=https://api.predict.fun/v1
PREDICT_API_KEY=your-mainnet-key

No frontend or code changes are required — the key is attached automatically by PredictClient and never leaves the backend.

---

Roadmap

• Mainnet read-only integration after API key approval
• Historical recorder
• Replay and analytics

---

Disclaimer

Independent developer tool. Not affiliated with, endorsed by, or maintained by Predict.fun. All market data is sourced live from the official Predict.fun Testnet API.