PredictEngine API: Developer Integration Guide

API Architecture Overview

PredictEngine's API is built on FastAPI (Python 3.11) and follows RESTful conventions. All endpoints are prefixed with /api/ and return JSON responses using ORJSONResponse for high-performance serialization. The API runs on Uvicorn with 4 workers behind an HTTPS reverse proxy.

The API provides access to all platform functionality: market data, trading operations, bot management, wallet operations, analytics, and more. Whether you want to build a custom trading dashboard, integrate PredictEngine into an existing application, or create advanced trading algorithms, the API gives you full programmatic control.

Authentication with Clerk JWT

All authenticated endpoints require a valid Clerk JWT token in the Authorization header as a Bearer token. PredictEngine uses Clerk for identity management, and JWT tokens are verified server-side using the Clerk secret key. Upon verification, the API maps the Clerk user ID to the corresponding Supabase user record.

To obtain a JWT token, authenticate through the PredictEngine frontend (which uses Clerk's authentication flow) and extract the session token. For server-to-server integrations, use Clerk's API to generate long-lived tokens. Include the token in every request: Authorization: Bearer <your_jwt_token>.

Key API Endpoints

The API is organized into logical route groups. /api/markets provides real-time Polymarket data including prices, volumes, and order books. /api/trade handles direct market trading with buy and sell operations. /api/bots manages bot CRUD operations, start/stop controls, and status monitoring.

Additional endpoints include /api/wallet for balance queries and withdrawals, /api/ai for AI strategy generation, /api/analytics for platform statistics, and /api/leaderboard for public ranking data. Each endpoint group has its own rate limits configured through SlowAPI middleware.

Rate Limiting and Best Practices

PredictEngine uses SlowAPI rate limiting to protect the platform and ensure fair usage. Default limits are 60 requests per minute for authenticated endpoints and 30 per minute for unauthenticated (public) endpoints. Market data endpoints have higher limits (120/min) to support real-time applications.

Best practices for API integration: use connection pooling for HTTP clients (httpx recommended), implement exponential backoff for rate-limited responses (HTTP 429), cache market data locally with a 5-second TTL to reduce API calls, and always handle error responses gracefully. The API returns standard HTTP status codes with descriptive error messages in the response body.

Frequently Asked Questions