# Sports Ticker Format

<Callout type="info" title="Market Maker Reference">
  This specification defines the ticker format for sports prediction markets. Use this as the authoritative reference for ticker generation and parsing.
</Callout>

## Overview

Sports prediction market tickers follow a hierarchical structure designed to be:

- **Hierarchical** - Event tickers group related contracts
- **Sortable** - Alphabetical sorting clusters all markets for a game
- **Parseable** - Deterministic structure enables programmatic parsing
- **Human-readable** - Encodes game, market type, and position in a compact format

Sports are organized into two categories based on ticker format:

| Category | Sports | Structure |
|----------|--------|-----------|
| **Team Sports** | NBA, NFL, NHL, MLB, EPL, NCAAM | Home vs Away matchup format |
| **Individual Sports** | Golf, Formula 1 | Tournament/race with N competitors |

## Ticker Hierarchy

| Level | Description | Team Sports Example | Individual Sports Example |
|-------|-------------|---------------------|---------------------------|
| **Event Ticker** | Identifies a specific market | `GEMI-NBA-2602121800-HOU-DAL-S` | `GEMI-GOLF-MAS-WIN-20260412` |
| **Contract Ticker** | Identifies a position within that market | `DAL6` | `SCHEFFLER` |
| **Full Ticker** | Event + Contract combined | `GEMI-NBA-2602121800-HOU-DAL-S-DAL6` | `GEMI-GOLF-MAS-WIN-20260412-SCHEFFLER` |

---

## Team Sports

### Event Ticker Format

**Structure**

```
GEMI-{LEAGUE}-{YYMMDD}{HHMM}-{AWAY}-{HOME}-{TYPE}
```

**Components**

| Component | Length | Format | Description |
|-----------|--------|--------|-------------|
| `GEMI` | 4 | literal | Gemini prediction market prefix |
| `LEAGUE` | 2-6 | `[A-Z]+` | League identifier |
| `YYMMDD` | 6 | `[0-9]{6}` | Game date (UTC) |
| `HHMM` | 4 | `[0-9]{4}` | Game time in 24hr (UTC) |
| `AWAY` | 2-4 | `[A-Z]+` | Away team abbreviation |
| `HOME` | 2-4 | `[A-Z]+` | Home team abbreviation |
| `TYPE` | 1-7 | `[A-Z]{1,7}` | Market type code |

**Regex Pattern**

```regex
^GEMI-([A-Z]{2,6})-(\d{6})(\d{4})-([A-Z]{2,4})-([A-Z]{2,4})-([A-Z]{1,7})$
```

**Capture Groups:**
1. League
2. Date (YYMMDD)
3. Time (HHMM)
4. Away team
5. Home team
6. Market type

### Supported Team Sports Leagues

| League | Code | Teams | Abbreviation Length |
|--------|------|-------|---------------------|
| NBA | `NBA` | 30 | 3 |
| NFL | `NFL` | 32 | 2-3 |
| NCAA Men's Basketball | `NCAAM` | 350+ | 2-4 |
| NCAA Women's Basketball | `NCAAW` | 350+ | 2-4 |
| NCAA Football | `NCAAF` | 130+ | 2-4 |
| NHL | `NHL` | 32 | 2-3 |
| MLB | `MLB` | 30 | 2-3 |
| English Premier League | `EPL` | 20 | 3-4 |

### Market Types

#### Standard Markets

| Type | Code | Description | Contract Format |
|------|------|-------------|-----------------|
| Moneyline | `M` | Winner of the game | `{TEAM}` |
| Spread | `S` | Point spread | `{TEAM}{LINE}` |
| Total | `T` | Combined score over/under | `O{LINE}` or `U{LINE}` |
| Team Total | `TT` | Single team score over/under | `{TEAM}O{LINE}` or `{TEAM}U{LINE}` |

#### Player Props

Player prop market types follow the `PP{STAT}` pattern. Player identifiers use uppercase short names (typically last name, e.g., `LUKA`, `MAHOMES`).

**Contract Format:** `{PLAYER}O{LINE}` or `{PLAYER}U{LINE}`

##### Basketball

| Type | Code | Description |
|------|------|-------------|
| Points | `PPPTS` | Player points over/under |
| Rebounds | `PPREB` | Player rebounds over/under |
| Assists | `PPAST` | Player assists over/under |
| 3-Pointers Made | `PP3PM` | Player 3-pointers made over/under |
| Steals | `PPSTL` | Player steals over/under |
| Blocks | `PPBLK` | Player blocks over/under |
| Pts + Reb + Ast | `PPPRA` | Player points + rebounds + assists over/under |

##### Football

| Type | Code | Description |
|------|------|-------------|
| Touchdowns | `PPTD` | Player touchdowns over/under |
| Passing Yards | `PPYDS` | Player passing yards over/under |
| Rushing Yards | `PPRYDS` | Player rushing yards over/under |
| Receiving Yards | `PPRECY` | Player receiving yards over/under |
| Receptions | `PPREC` | Player receptions over/under |
| Completions | `PPCOMP` | Player completions over/under |

##### Baseball

| Type | Code | Description |
|------|------|-------------|
| Strikeouts | `PPSO` | Pitcher strikeouts over/under |
| Hits | `PPHITS` | Player hits over/under |
| Home Runs | `PPHR` | Player home runs over/under |
| RBIs | `PPRBI` | Player RBIs over/under |
| Total Bases | `PPTB` | Player total bases over/under |
| Runs | `PPRUNS` | Player runs scored over/under |

##### Ice Hockey

| Type | Code | Description |
|------|------|-------------|
| Goals | `PPGOALS` | Player goals over/under |
| Assists | `PPAST` | Player assists over/under |
| Points | `PPPTS` | Player points (goals + assists) over/under |
| Shots on Goal | `PPSOG` | Player shots on goal over/under |
| Saves | `PPSAVES` | Goalie saves over/under |

##### Soccer

| Type | Code | Description |
|------|------|-------------|
| Goals | `PPGOALS` | Player goals over/under |
| Assists | `PPAST` | Player assists over/under |
| Shots on Target | `PPSOT` | Player shots on target over/under |

#### Soccer-Specific (EPL)

| Type | Code | Description | Contract Format |
|------|------|-------------|-----------------|
| Moneyline | `M` | 3-way result | `{TEAM}` or `D` (draw) |

### Contract Ticker Formats

#### Moneyline (`-M`)

**Contract Ticker:** `{TEAM}`

| Contract | Meaning |
|----------|---------|
| `DAL` | Dallas |
| `HOU` | Houston |
| `D` | Draw (soccer only) |

**Full Ticker Example:** `GEMI-NBA-2602121800-HOU-DAL-M-DAL`

#### Spread (`-S`)

**Contract Ticker:** `{TEAM}{LINE}`

| Contract | Meaning |
|----------|---------|
| `DAL6` | Dallas -6.5 |
| `HOU6` | Houston +6.5 |

<Callout type="tip" title="Line Convention">
  All lines (spreads and totals) use whole numbers only. The `.5` is always implied. For example, `DAL6` means Dallas -6.5 and `O222` means Over 222.5.
</Callout>

**Full Ticker Example:** `GEMI-NBA-2602121800-HOU-DAL-S-DAL6`

#### Total (`-T`)

**Contract Ticker:** `O{LINE}` or `U{LINE}`

| Contract | Meaning |
|----------|---------|
| `O222` | Over 222.5 |
| `U222` | Under 222.5 |

**Full Ticker Example:** `GEMI-NBA-2602121800-HOU-DAL-T-O222`

#### Team Total (`-TT`)

**Contract Ticker:** `{TEAM}O{LINE}` or `{TEAM}U{LINE}`

| Contract | Meaning |
|----------|---------|
| `HOUO110` | Houston Over 110.5 |
| `HOUU110` | Houston Under 110.5 |
| `DALO112` | Dallas Over 112.5 |
| `DALU112` | Dallas Under 112.5 |

**Full Ticker Example:** `GEMI-NBA-2602121800-HOU-DAL-TT-HOUO110`

---

## Individual Sports

Individual sports use a tournament or race-based ticker format. Instead of a home/away matchup, the event represents a competition with N individual competitors, each getting their own contract.

### Event Ticker Format

**Structure**

```
GEMI-{SPORT}-{EVENT}-{MARKET}-{YYYYMMDD}
```

**Components**

| Component | Format | Description |
|-----------|--------|-------------|
| `GEMI` | literal | Gemini prediction market prefix |
| `SPORT` | `[A-Z0-9]+` | Sport identifier (`GOLF`, `F1`) |
| `EVENT` | `[A-Z]{2,5}` | Abbreviated event name |
| `MARKET` | `[A-Z]+` | Market type (`WIN` for tournament/race winner) |
| `YYYYMMDD` | `[0-9]{8}` | Event end date (when winner is determined) |

**Regex Pattern**

```regex
^GEMI-([A-Z0-9]+)-([A-Z]{2,5})-([A-Z]+)-(\d{8})$
```

**Capture Groups:**
1. Sport
2. Event abbreviation
3. Market type
4. End date (YYYYMMDD)

### Supported Individual Sports

| Sport | Code | Event Abbreviation | Competitors |
|-------|------|--------------------|-------------|
| Golf | `GOLF` | 3-char tournament name | ~60-80 per tournament |
| Formula 1 | `F1` | 3-char GP name + `GP` | ~20 per race |

### Contract Ticker Format

**Contract Ticker:** `{COMPETITOR}` — uppercase alphabetic name of the competitor.

| Sport | Format | Collision Handling | Examples |
|-------|--------|-------------------|----------|
| Golf | Uppercase last name | Prepend first name | `SCHEFFLER`, `JOHNSMITH` |
| Formula 1 | Driver symbol | Pre-assigned in DB | `VER`, `HAM`, `NOR` |

### Golf

#### Event Ticker

```
GEMI-GOLF-{ABBREV}-WIN-{YYYYMMDD}
```

| Component | Description | Example |
|-----------|-------------|---------|
| `GEMI` | Gemini prediction market prefix | `GEMI` |
| `GOLF` | Sport identifier | `GOLF` |
| `ABBREV` | First 3 uppercase alpha chars of tournament name (after stripping "The " prefix) | `MAS` (Masters), `PGA` (PGA Championship) |
| `WIN` | Tournament winner market | `WIN` |
| `YYYYMMDD` | Final round date | `20260412` |

#### Tournament Abbreviation Rules

1. Strip leading "The " / "the " (case-insensitive)
2. Strip trailing year suffix (e.g., " 2025")
3. Remove all non-alphanumeric characters
4. Uppercase
5. Take first 3 characters

| Tournament | Abbreviation |
|-----------|--------------|
| Masters Tournament | `MAS` |
| THE PLAYERS Championship | `PLA` |
| PGA Championship | `PGA` |
| U.S. Open | `USO` |
| The Open Championship | `OPE` |
| Arnold Palmer Invitational | `ARN` |
| Valero Texas Open | `VAL` |

#### Contract Ticker (Player)

- **Default:** Uppercase last name, alpha characters only (`SCHEFFLER`, `MCILROY`, `WOODS`)
- **On collision:** Prepend first name (`JOHNSMITH`, `JAMESSMITH`)
- **Special characters stripped:** `J.J. Spaun` → `SPAUN`, `Si Woo Kim` → `KIM`

#### Golf Examples

**Masters Tournament, Apr 12 2026**

| Market | Event Ticker | Contract | Full Ticker |
|--------|-------------|----------|-------------|
| Scheffler wins | `GEMI-GOLF-MAS-WIN-20260412` | `SCHEFFLER` | `GOLF-MAS-WIN-20260412-SCHEFFLER` |
| McIlroy wins | `GEMI-GOLF-MAS-WIN-20260412` | `MCILROY` | `GOLF-MAS-WIN-20260412-MCILROY` |
| Rahm wins | `GEMI-GOLF-MAS-WIN-20260412` | `RAHM` | `GOLF-MAS-WIN-20260412-RAHM` |

**PGA Championship, May 17 2026**

| Market | Event Ticker | Contract | Full Ticker |
|--------|-------------|----------|-------------|
| Woods wins | `GEMI-GOLF-PGA-WIN-20260517` | `WOODS` | `GOLF-PGA-WIN-20260517-WOODS` |
| Schauffele wins | `GEMI-GOLF-PGA-WIN-20260517` | `SCHAUFFELE` | `GOLF-PGA-WIN-20260517-SCHAUFFELE` |

### Formula 1

#### Event Ticker

```
GEMI-F1-{ABBREV}GP-WIN-{YYYYMMDD}
```

| Component | Description | Example |
|-----------|-------------|---------|
| `GEMI` | Gemini prediction market prefix | `GEMI` |
| `F1` | Sport identifier | `F1` |
| `ABBREV` | First 3 uppercase chars of GP location + `GP` | `MIAGP` (Miami), `AUSGP` (Australian) |
| `WIN` | Race winner market | `WIN` |
| `YYYYMMDD` | Race date | `20260504` |

#### Contract Ticker (Driver)

Pre-assigned driver symbols from the database (e.g., `VER`, `HAM`, `NOR`, `LEC`).

#### Formula 1 Examples

**Miami Grand Prix, May 4 2026**

| Market | Event Ticker | Contract | Full Ticker |
|--------|-------------|----------|-------------|
| Verstappen wins | `GEMI-F1-MIAGP-WIN-20260504` | `VER` | `F1-MIAGP-WIN-20260504-VER` |
| Hamilton wins | `GEMI-F1-MIAGP-WIN-20260504` | `HAM` | `F1-MIAGP-WIN-20260504-HAM` |
| Norris wins | `GEMI-F1-MIAGP-WIN-20260504` | `NOR` | `F1-MIAGP-WIN-20260504-NOR` |

---

## Futures Format

Futures use a modified structure with `F` appended to the league code.

### Structure

```
GEMI-{LEAGUE}F-{SEASON}{TYPE}-{SUBJECT}
```

### Components

| Component | Format | Description |
|-----------|--------|-------------|
| `LEAGUE` | `[A-Z]+` | League code |
| `F` | literal | Futures indicator |
| `SEASON` | `[0-9]{4}` | Season span (e.g., `2526` for 2025-26) |
| `TYPE` | varies | Future type code |
| `SUBJECT` | varies | Team or entity |

### Future Types

| Type | Code | Example |
|------|------|---------|
| Championship | `CHAMP` | `GEMI-NBAF-2526CHAMP-LAL` |
| Conference | `CONF` | `GEMI-NBAF-2526CONF-WEST-LAL` |
| Division | `DIV` | `GEMI-NFLF-2526DIV-AFCN-CLE` |
| MVP | `MVP` | `GEMI-NBAF-2526MVP-LUKA` |

### Regex Pattern

```regex
^GEMI-([A-Z]{2,6})F-(\d{4})([A-Z]+)(?:-([A-Z]+))?-([A-Z]+)$
```

**Capture Groups:**
1. League
2. Season (YYYY format, e.g., `2526`)
3. Future type (CHAMP, CONF, DIV, MVP)
4. Sub-category (optional, e.g., WEST, AFCN)
5. Subject (team or player)

---

## Complete Examples

### NBA Game

**Houston @ Dallas, Feb 12 2026 18:00 UTC**

| Market | Event Ticker | Contract | Full Ticker |
|--------|--------------|----------|-------------|
| Dallas win | `GEMI-NBA-2602121800-HOU-DAL-M` | `DAL` | `GEMI-NBA-2602121800-HOU-DAL-M-DAL` |
| Houston win | `GEMI-NBA-2602121800-HOU-DAL-M` | `HOU` | `GEMI-NBA-2602121800-HOU-DAL-M-HOU` |
| Dallas -6.5 | `GEMI-NBA-2602121800-HOU-DAL-S` | `DAL6` | `GEMI-NBA-2602121800-HOU-DAL-S-DAL6` |
| Houston +6.5 | `GEMI-NBA-2602121800-HOU-DAL-S` | `HOU6` | `GEMI-NBA-2602121800-HOU-DAL-S-HOU6` |
| Over 222.5 | `GEMI-NBA-2602121800-HOU-DAL-T` | `O222` | `GEMI-NBA-2602121800-HOU-DAL-T-O222` |
| Under 222.5 | `GEMI-NBA-2602121800-HOU-DAL-T` | `U222` | `GEMI-NBA-2602121800-HOU-DAL-T-U222` |
| Houston Over 110.5 | `GEMI-NBA-2602121800-HOU-DAL-TT` | `HOUO110` | `GEMI-NBA-2602121800-HOU-DAL-TT-HOUO110` |
| Dallas Under 112.5 | `GEMI-NBA-2602121800-HOU-DAL-TT` | `DALU112` | `GEMI-NBA-2602121800-HOU-DAL-TT-DALU112` |
| Luka Over 30.5 pts | `GEMI-NBA-2602121800-HOU-DAL-PPPTS` | `LUKAO30` | `GEMI-NBA-2602121800-HOU-DAL-PPPTS-LUKAO30` |
| Luka Under 10.5 reb | `GEMI-NBA-2602121800-HOU-DAL-PPREB` | `LUKAU10` | `GEMI-NBA-2602121800-HOU-DAL-PPREB-LUKAU10` |

### NFL Game

**Buffalo @ Kansas City, Jan 12 2026 18:30 UTC**

| Market | Full Ticker |
|--------|-------------|
| Kansas City win | `GEMI-NFL-2601121830-BUF-KC-M-KC` |
| Kansas City -3.5 | `GEMI-NFL-2601121830-BUF-KC-S-KC3` |
| Over 47.5 | `GEMI-NFL-2601121830-BUF-KC-T-O47` |
| Mahomes Over 2.5 TDs | `GEMI-NFL-2601121830-BUF-KC-PPTD-MAHOMESO2` |
| Mahomes Over 299.5 yds | `GEMI-NFL-2601121830-BUF-KC-PPYDS-MAHOMESO299` |

### NCAAM Game

**Duke @ UNC, Mar 15 2026 19:00 UTC**

| Market | Full Ticker |
|--------|-------------|
| UNC win | `GEMI-NCAAM-2603151900-DUKE-UNC-M-UNC` |
| Duke +3.5 | `GEMI-NCAAM-2603151900-DUKE-UNC-S-DUKE3` |
| Over 145.5 | `GEMI-NCAAM-2603151900-DUKE-UNC-T-O145` |

### EPL Match

**Arsenal vs Man City, Feb 15 2026 15:00 UTC**

| Market | Full Ticker |
|--------|-------------|
| Arsenal win | `GEMI-EPL-2602151500-ARS-MCI-M-ARS` |
| Man City win | `GEMI-EPL-2602151500-ARS-MCI-M-MCI` |
| Draw | `GEMI-EPL-2602151500-ARS-MCI-M-D` |
| Over 2.5 goals | `GEMI-EPL-2602151500-ARS-MCI-T-O2` |

### Golf Tournament

**Masters Tournament, Apr 12 2026**

| Market | Event Ticker | Contract | Full Ticker |
|--------|-------------|----------|-------------|
| Scheffler wins | `GEMI-GOLF-MAS-WIN-20260412` | `SCHEFFLER` | `GOLF-MAS-WIN-20260412-SCHEFFLER` |
| McIlroy wins | `GEMI-GOLF-MAS-WIN-20260412` | `MCILROY` | `GOLF-MAS-WIN-20260412-MCILROY` |
| Matsuyama wins | `GEMI-GOLF-MAS-WIN-20260412` | `MATSUYAMA` | `GOLF-MAS-WIN-20260412-MATSUYAMA` |

### Formula 1 Race

**Miami Grand Prix, May 4 2026**

| Market | Event Ticker | Contract | Full Ticker |
|--------|-------------|----------|-------------|
| Verstappen wins | `GEMI-F1-MIAGP-WIN-20260504` | `VER` | `F1-MIAGP-WIN-20260504-VER` |
| Norris wins | `GEMI-F1-MIAGP-WIN-20260504` | `NOR` | `F1-MIAGP-WIN-20260504-NOR` |
| Leclerc wins | `GEMI-F1-MIAGP-WIN-20260504` | `LEC` | `F1-MIAGP-WIN-20260504-LEC` |

### Futures

| Market | Ticker |
|--------|--------|
| Los Angeles 2025-26 NBA Championship | `GEMI-NBAF-2526CHAMP-LAL` |
| Kansas City AFC West Division | `GEMI-NFLF-2526DIV-AFCW-KC` |
| Duke NCAA Tournament | `GEMI-NCAAMF-2526CHAMP-DUKE` |

## Validation Rules

### Team Sports Event Ticker Validation

1. Must start with `GEMI-`
2. Must be ALL UPPERCASE
3. League code must be from supported list
4. DateTime must be valid UTC timestamp
5. Team codes must be valid for the league
6. Market type must be from supported list

### Individual Sports Event Ticker Validation

1. Must start with `GEMI-`
2. Must be ALL UPPERCASE
3. Sport code must be from supported list (`GOLF`, `F1`)
4. Event abbreviation must be 2-5 alpha characters
5. Market type must be valid (`WIN`)
6. Date must be valid `YYYYMMDD` format

### Contract Ticker Validation

#### Team Sports

| Market Type | Valid Pattern | Examples |
|-------------|---------------|----------|
| Moneyline | `^[A-Z]{2,4}$` or `^D$` | `DAL`, `HOU`, `D` |
| Spread | `^[A-Z]{2,4}[0-9]+$` | `DAL6`, `HOU6` |
| Total | `^[OU][0-9]+$` | `O222`, `U47` |
| Team Total | `^[A-Z]{2,4}[OU][0-9]+$` | `HOUO110`, `DALU112` |

#### Individual Sports

| Market Type | Valid Pattern | Examples |
|-------------|---------------|----------|
| Winner (Golf) | `^[A-Z]+$` | `SCHEFFLER`, `MCILROY`, `JOHNSMITH` |
| Winner (F1) | `^[A-Z]{2,4}$` | `VER`, `HAM`, `NOR` |

### Full Ticker Validation

**Team Sports:**
```regex
^GEMI-[A-Z]{2,6}-\d{10}-[A-Z]{2,4}-[A-Z]{2,4}-[A-Z]{1,7}-[A-Z0-9]+$
```

**Individual Sports:**
```regex
^GEMI-[A-Z0-9]+-[A-Z]{2,5}-[A-Z]+-\d{8}-[A-Z]+$
```

## Changelog

| Version | Effective Date | Changes |
|---------|----------------|---------|
| 1.2 | 2026-03-30 | Added Individual Sports section (Golf, Formula 1) with tournament/race-based ticker format |
| 1.1 | 2026-03-04 | Corrected prefix from `GEM-` to `GEMI-` for consistency with crypto tickers |
| 1.0 | 2026-02-13 | Initial specification |