Sports Market Data & Live Scores
Relevant source files
The following files were used as context for generating this wiki page:
The Sports Market Data & Live Scores system is a core module responsible for aggregating, normalizing, and synchronizing sports-related event data from multiple external providers. It provides the foundation for creating prediction markets based on professional sports and esports matches, managing live score updates, and facilitating market resolution through verified match results.
The system supports two primary providers: TheSportsDB for traditional sports (Soccer, Basketball, American Football, etc.) and PandaScore for esports (CS2, LoL, Dota 2, etc.). It encompasses functionality for searching upcoming matches, mapping blockchain events to real-world fixtures, and maintaining live scoreboards through automated synchronization and manual administrative overrides.
Sources: src/lib/sports-source/index.ts, src/app/api/sync/events/route.ts:50-60
Architecture & Data Flow
The system operates through a multi-layered architecture involving external API integration, internal data normalization, and synchronization routines.
Provider Integration Layer
The system uses a provider-agnostic interface to interact with external data sources. Each provider implementation handles specific API logic, such as endpoint construction and token authentication.
Data Normalization
Match data from different providers is converted into a standard SportsSourceCandidate structure. This normalization includes:
- Identity Resolution: Mapping provider-specific IDs to internal event slugs.
- Score Formatting: Converting varied score formats (e.g., period scores, series scores) into a unified string and segment-based format.
- Livestream Integration: Detecting and prioritizing official YouTube or Twitch streams.
Sources: src/lib/sports-source/index.ts:32-60, src/lib/sports-segment-score.ts:40-70
Key Components
1. Sports Source Service
The central logic resides in src/lib/sports-source/index.ts. It provides high-level functions for searching and resolving events.
| Function | Purpose |
|---|---|
searchSportsEvents | Queries configured providers for matches matching a query string, date, or league. |
findSportsEvents | Uses AI-extracted hints (via OpenRouter) to refine searches and find the most relevant match for a given market title. |
resolveSportsEvent | Retrieves detailed data for a specific match using a known eventId or gameId. |
scoreSportsCandidate | Calculates a confidence score (0 to 1) based on token overlap between market metadata and provider data. |
Sources: src/lib/sports-source/index.ts:1360-1415
2. Live Score Synchronization
Automated synchronization is handled via API routes that periodically poll providers for updates.
3. Sports Segment Scores
For games with multiple parts (halves, quarters, sets, or esports maps), the system tracks segmentScores. This is crucial for resolving specific market types like "1H Totals" or "Set Handicap".
| Field | Type | Description |
|---|---|---|
segment | number | The index of the game part (e.g., 1 for 1st Half). |
homeScore | number | null | Score of the home team in that segment. |
awayScore | number | null | Score of the away team in that segment. |
Sources: src/lib/sports-segment-score.ts:1-20, src/types/index.ts
Market Structure & Variants
When creating sports markets, administrators can select from several pre-defined templates that dictate which markets are automatically generated for an event.
Supported Templates
- Standard: Moneyline only (Home/Away or Home/Draw/Away).
- Soccer More Markets: Includes BTTS (Both Teams to Score), Spreads (-1.5), and Totals (1.5 to 4.5).
- Exact Score: A grid of possible score outcomes (0-0 to 3-3) plus "Any Other Score".
- Halftime Result: Specific markets for the result at the end of the first half.
- Player Props: Markets centered on individual player stats (Points, Rebounds, Assists, etc.).
Sources: src/lib/admin-sports-create.ts:100-150, src/lib/admin-sports-create.ts:800-850
Administrative Controls
The AdminEventsTable component provides an interface for manual intervention in sports data.
Manual Result Entry
Administrators can manually override automated scores in the "Match score" dialog. This includes:
- Marking a match as Final.
- Manually entering segment scores (e.g., individual set scores for Tennis).
- Searching for a specific Provider ID if automated mapping fails.
Sources: src/app/[locale]/admin/events/_components/AdminEventsTable.tsx:900-1050
Confidence Thresholds
For automated synchronization, the system employs a AUTO_SPORTS_SOURCE_CONFIDENCE_THRESHOLD (default 0.72). If a match suggested by the AI hint extraction layer has a confidence score lower than this, it requires manual confirmation by an admin before live scores will sync.
Sources: src/app/api/sync/events/route.ts:35
Metadata Schema (Sports)
Sports metadata is stored in specialized tables (event_sports and market_sports) and synchronized from the metadata hashes found on-chain.
| Field | Description |
|---|---|
sports_market_type | The specific type (e.g., moneyline, spreads, cs2_odd_even_total_rounds). |
sports_line | The numeric handicap or over/under threshold. |
sports_source_provider | The authoritative data source (thesportsdb or pandascore). |
sports_source_event_id | The unique ID in the provider's database. |
sports_teams | JSON array containing team names, abbreviations, and logo references. |
Sources: src/app/api/sync/events/route.ts:70-130
Conclusion
The Sports Market Data & Live Scores module provides a robust framework for managing real-world sports data within the prediction market. By combining multi-provider support, AI-assisted match mapping, and automated synchronization, it ensures that sports markets remain accurate and responsive to live developments while providing administrators with necessary manual overrides for resolution integrity.