Core API & Webhook Handlers
Relevant source files
The following files were used as context for generating this wiki page:
- src/app/llms.txt/route.ts
- src/app/[locale]/admin/api/event-creations/ai/route.ts
- src/lib/sports-source/index.ts
- src/app/[locale]/admin/events/calendar/_components/admin-create-event-form-utils.ts
- src/app/[locale]/admin/(general)/_actions/update-general-settings.ts/_actions/update-general-settings.ts)
- src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx
The Core API and Webhook Handlers system provides a unified interface for prediction market interactions, administrative operations, and external service integrations. It facilitates decentralized market discovery, real-time activity tracking, and automated event management through a combination of public-facing endpoints and protected administrative APIs.
The system is architected to handle complex workflows, such as AI-assisted market creation, KYC verification via Sumsub, and sports data resolution from multiple providers like TheSportsDB and PandaScore. By leveraging asynchronous processing and structured data validation, the API ensures high reliability for both frontend consumers and backend automation tools.
Public Frontend API Surface
The project exposes a set of frontend API routes designed to power the user interface with real-time data and market metadata. These endpoints are primarily consumed by the platform's home, category, and search surfaces.
Primary Frontend Endpoints
| Endpoint | Description | Implementation Detail |
|---|---|---|
/api/events | Paginated listing of prediction events. | Used by search and category pages. |
/api/event-activity | Live feed of trades and interactions for a specific condition. | Requires conditionId. |
/api/holders | Retrieves top holder data for a market. | Requires conditionId. |
/api/embed/events/slug/{slug} | CORS-enabled event payload for external embeds. | Facilitates third-party widgets. |
/api/market-context | Returns structured context for event tooling. | POST endpoint. |
Sources: src/app/llms.txt/route.ts:133-160
Administrative AI & Content APIs
The administrative API includes specialized handlers for creating and validating market content using Large Language Models (LLMs) via OpenRouter. These handlers reside within the admin/api namespace and require administrator privileges.
Event Creation AI Workflow
The event-creations/ai route manages two distinct operational modes:
- generate_rules: Generates deterministic, Polymarket-style resolution rules based on market parameters and external reference samples.
- check_content: Validates market metadata (titles, dates, categories) for linguistic accuracy, safety, and logical consistency.
The AI check specifically rejects content that encourages real-world harm (violence, death, war) and validates that recurring templates contain necessary date variables.
Sources: src/app/[locale]/admin/api/event-creations/ai/route.ts:571-770
Content Validation Rules
| Category | Check Description | Logic Location |
|---|---|---|
| Mandatory | Ensures titles, categories, and end dates are present. | buildMandatoryErrors |
| Language | Validates English usage, ignoring proper nouns. | checkMessages (System Prompt) |
| Deterministic | Verifies resolution source URL format and rule objectivity. | isValidHttpUrl / AICheck |
| Coherence | Compares end dates against reliable public data for context. | isTimezoneOnlyDateReason |
Sources: src/app/[locale]/admin/api/event-creations/ai/route.ts:407-550
External Data & Integration Handlers
The API system integrates with third-party providers to resolve market outcomes and manage user identities.
Sports Data Resolution
The SportsSource module provides a unified interface to query multiple providers. It uses a confidence-based scoring system to match market titles against external game data.
Webhook and Identity Integrations
Identity verification is handled via Sumsub. The integration supports different enforcement levels:
- Disabled: No KYC required.
- Observe only: Verification is optional and does not block account actions.
- Required: Users must be verified to interact with Technology Features.
Sources: src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx:392-415
Service Endpoint Configuration
The system resolves service URLs (Gamma, CLOB, Data) from environment variables during runtime to support different network environments (e.g., Amoy vs. Polygon Mainnet).
| Service | Purpose | Source Env Variable |
|---|---|---|
| Gamma API | Discovery and search metadata. | publicRuntimeEnv.gammaUrl |
| CLOB API | Order book and trade execution. | publicRuntimeEnv.clobUrl |
| Data API | Analytics, holders, and leaderboards. | publicRuntimeEnv.dataUrl |
| WebSocket | Real-time price and event streams. | publicRuntimeEnv.wsClobUrl |
Sources: src/app/llms.txt/route.ts:165-188
API Communication Utilities
Administrative interfaces use a set of utility functions to handle API requests, specifically for EIP-712 authentication challenges and transaction preparing.
// Example of the multi-step signature preparation flow
export async function fetchAdminApi(pathname: string, init?: RequestInit) {
const normalizedPath = pathname.startsWith('/') ? pathname : `/${pathname}`
const primaryUrl = `/admin/api${normalizedPath}`
const primaryResponse = await fetch(primaryUrl, init)
// Logic for locale-aware fallback ...
return primaryResponse
}
Sources: src/app/[locale]/admin/events/calendar/_components/admin-create-event-form-utils.ts:193-210
The admin-create-event-form-utils module also provides standard error mapping for signature flows, translating complex RPC errors into user-friendly messages for wallet providers.
Sources: src/app/[locale]/admin/events/calendar/_components/admin-create-event-form-utils.ts:468-485
Conclusion
The Core API & Webhook Handlers form the backbone of the prediction market's backend-to-frontend communication. By centralizing AI validation, sports data resolution, and integration management, the architecture maintains strict control over market integrity while providing the flexibility needed for decentralized operations. Consistency in error handling and service discovery across these handlers ensures a robust developer experience for both internal platform evolution and external SDK integration.