sports-ticker – OpenClaw Skill

---

name: sports-ticker version: 3.0.3 description: Live sports alerts for Soccer, NFL, NBA, NHL, MLB, F1 and more. Real-time scoring with FREE ESPN API. Track any team from any major league worldwide. metadata: {"clawdbot":{"requires":{"bins":["python3"],"env":[]}}}

Sports Ticker

Track your favorite teams across multiple sports with FREE live alerts!

Supports: ⚽ Soccer • 🏈 NFL • 🏀 NBA • 🏒 NHL • ⚾ MLB • 🏎️ F1

First Run (Onboarding)

When no config.json exists, running the setup script launches an interactive wizard:

python3 scripts/setup.py

The wizard asks:

1. 📺 Which sports? — Pick from Soccer, NFL, NBA, NHL, MLB, F1
2. 🏆 Which teams? — Choose from popular teams or search for any team
3. 🔔 Alert style? — Live scores, final only, or daily digest
4. ⏰ Game-day reminders? — Get a heads-up 30 mins before kick-off
5. 🌙 Quiet hours? — Pause alerts while you sleep

After setup, your config.json is ready and you can start tracking!

Re-run setup anytime:

python3 scripts/setup.py --force  # Overwrites existing config

Quick Start

# First time? Just run setup!
python3 scripts/setup.py  # Interactive wizard

# Find team IDs (any sport)
python3 scripts/setup.py find "Lakers" basketball
python3 scripts/setup.py find "Chiefs" football
python3 scripts/setup.py find "Barcelona" soccer

# Test
python3 scripts/ticker.py

Config Example

{
  "teams": [
    {
      "name": "Barcelona",
      "emoji": "🔵🔴",
      "sport": "soccer",
      "espn_id": "83",
      "espn_leagues": ["esp.1", "uefa.champions"]
    },
    {
      "name": "Lakers",
      "emoji": "🏀💜💛",
      "sport": "basketball",
      "espn_id": "13",
      "espn_leagues": ["nba"]
    }
  ]
}

Commands

# Ticker for all teams
python3 scripts/ticker.py

# Live monitor (for cron)
python3 scripts/live_monitor.py

# League scoreboard
python3 scripts/ticker.py league nba basketball
python3 scripts/ticker.py league nfl football
python3 scripts/ticker.py league eng.1 soccer

# 📅 Schedule - View upcoming fixtures (NEW in v3!)
python3 scripts/schedule.py                    # All teams, next 14 days
python3 scripts/schedule.py --days 30          # Look further ahead
python3 scripts/schedule.py --team spurs       # Specific team
python3 scripts/schedule.py --compact          # One-liner format
python3 scripts/schedule.py --json             # JSON output

# 🤖 Auto Setup Crons - Generate match-day crons (NEW in v3!)
python3 scripts/auto_setup_crons.py            # All teams, next 7 days
python3 scripts/auto_setup_crons.py --team spurs --days 14
python3 scripts/auto_setup_crons.py --json     # Machine-readable
python3 scripts/auto_setup_crons.py --commands # OpenClaw CLI commands

# ESPN direct
python3 scripts/espn.py leagues
python3 scripts/espn.py scoreboard nba basketball
python3 scripts/espn.py search "Chiefs" football

Alert Types

• 🏟️ Game start (kick-off / tip-off)
• ⚽🏈🏀⚾ Scoring plays (goals, touchdowns, 3-pointers, home runs)
• 🟥 Red cards / Ejections
• ⏸️ Halftime / Period breaks
• 🏁 Final results (WIN/LOSS/DRAW)

ESPN API (Free!)

No key needed. Covers all major sports and 50+ leagues worldwide.

Supported Sports:

• Soccer: Premier League, La Liga, Champions League, MLS, and 30+ more
• Football: NFL
• Basketball: NBA, WNBA, NCAA
• Hockey: NHL
• Baseball: MLB
• Racing: Formula 1

🏆 Sports Ticker

Live sports alerts with scoring updates and real-time stats — completely FREE!

Track soccer, football, basketball, hockey, baseball, F1, and more!

Built for OpenClaw but works standalone too.

✨ Features

• 🎯 Multi-sport support — Soccer, NFL, NBA, NHL, MLB, F1, and more!
• ⚽ Live scoring alerts with player names and times
• 🟥 Key events — cards, touchdowns, home runs, goals
• ⏸️ Period updates — Halftime, quarters, intermissions
• 🏁 Final results with WIN/LOSS/DRAW
• 📊 Multi-team support — track as many teams as you want
• 📅 Schedule/Fixtures — view upcoming matches for next 30 days (NEW in v3!)
• 🤖 Auto-cron generation — never miss a match, set up alerts automatically (NEW in v3!)
• 🔄 Auto-scheduling — cron jobs for match days (OpenClaw)
• 💰 100% FREE — no API keys, no subscriptions!

🎯 The Secret Sauce: ESPN API

This skill uses ESPN's public API which provides:

• Real-time scores across multiple sports
• Scoring plays with player names and timestamps
• Game events (touchdowns, goals, home runs, etc.)
• Match/game statistics

No API key required! ESPN's API is open and free to use.

Supported Sports & Leagues

⚽ Soccer/Football

• Premier League (eng.1), La Liga (esp.1), Bundesliga (ger.1), Serie A (ita.1)
• Champions League (uefa.champions), Europa League (uefa.europa)
• MLS (usa.1), Liga MX (mex.1), and 20+ more

🏈 American Football

• NFL (nfl)

🏀 Basketball

• NBA (nba), WNBA (wnba), NCAA (mens-college-basketball)

🏒 Hockey

• NHL (nhl)

⚾ Baseball

• MLB (mlb)

🏎️ Racing

• Formula 1 (f1)

🚀 Quick Start

1. Install

# Clone or copy to your skills directory
clawhub install sports-ticker

# Or manually
git clone https://github.com/your-repo/sports-ticker
cd sports-ticker

2. Run the Setup Wizard 🧙‍♂️

First time? The interactive wizard makes setup a breeze!

python3 scripts/setup.py

The wizard walks you through:

1. 📺 Pick your sports — Soccer, NFL, NBA, NHL, MLB, F1
2. 🏆 Choose your teams — Popular picks or search any team
3. 🔔 Set alert style — Live scores / Final only / Daily digest
4. ⏰ Game-day reminders — Get notified 30 mins before kick-off
5. 🌙 Quiet hours — No alerts while you sleep

Example:

╔═══════════════════════════════════════════════════════╗
║   🏆  SPORTS TICKER  🏆                               ║
║   ⚽ 🏈 🏀 🏒 ⚾ 🏎️                                    ║
║   Never miss a goal, touchdown, or checkered flag!   ║
╚═══════════════════════════════════════════════════════╝

3. Or Configure Manually

# Find team IDs directly
python3 scripts/setup.py find "Lakers" basketball
python3 scripts/setup.py find "Chiefs" football
python3 scripts/setup.py find "Barcelona" soccer

Common team IDs for reference:

Soccer:

• Tottenham: 367, Arsenal: 359, Liverpool: 364, Man City: 382, Man United: 360
• Barcelona: 83, Real Madrid: 86, Bayern: 132, PSG: 160, Juventus: 111

American Sports:

• Lakers: 13, Warriors: 9, Celtics: 2 (NBA)
• Chiefs: 12, 49ers: 25, Cowboys: 6 (NFL)
• Maple Leafs: 10, Oilers: 22, Rangers: 4 (NHL)
• Yankees: 10, Dodgers: 19, Red Sox: 2 (MLB)

3. Create config.json

cp config.example.json config.json

Edit config.json:

{
  "teams": [
    {
      "name": "Liverpool",
      "short_name": "Liverpool",
      "emoji": "🔴",
      "sport": "soccer",
      "espn_id": "364",
      "espn_leagues": ["eng.1", "uefa.champions"],
      "enabled": true
    },
    {
      "name": "Los Angeles Lakers",
      "short_name": "Lakers",
      "emoji": "🏀💜💛",
      "sport": "basketball",
      "espn_id": "13",
      "espn_leagues": ["nba"],
      "enabled": true
    },
    {
      "name": "Kansas City Chiefs",
      "short_name": "Chiefs",
      "emoji": "🏈",
      "sport": "football",
      "espn_id": "12",
      "espn_leagues": ["nfl"],
      "enabled": true
    }
  ],
  "alerts": {
    "goals": true,
    "red_cards": true,
    "halftime": true,
    "fulltime": true,
    "kickoff": true
  }
}

4. Test It

# Show ticker for your teams
python3 scripts/ticker.py

# Check live matches
python3 scripts/live_monitor.py --verbose

# View a specific league
python3 scripts/ticker.py league eng.1 soccer
python3 scripts/ticker.py league nfl football
python3 scripts/ticker.py league nba basketball

# 📅 View upcoming fixtures (NEW in v3!)
python3 scripts/schedule.py                      # All teams, 14 days
python3 scripts/schedule.py --team spurs --days 30
python3 scripts/schedule.py --json               # JSON output

# 🤖 Auto-generate match crons (NEW in v3!)
python3 scripts/auto_setup_crons.py --team spurs --days 14
python3 scripts/auto_setup_crons.py --json       # For OpenClaw cron API
python3 scripts/auto_setup_crons.py --commands   # CLI commands

# ESPN API commands
python3 scripts/espn.py leagues           # List all sports/leagues
python3 scripts/espn.py leagues soccer    # List soccer leagues
python3 scripts/espn.py scoreboard nba basketball
python3 scripts/espn.py search "Lakers" basketball

📱 Example Alerts

⚽ Soccer Goal:

🎉 GOAL! 23'
⚽ Marcus Rashford (Manchester United)
Manchester United 1-0 Liverpool

🏈 NFL Touchdown:

🎉 TOUCHDOWN! Q2 3:42
🏈 Patrick Mahomes (Kansas City Chiefs)
Chiefs 14-7 Bills

🏀 NBA 3-Pointer:

🎉 3-POINTER! Q3 8:15
🎯 LeBron James (Los Angeles Lakers)
Lakers 78-72 Warriors

🏒 NHL Goal:

🎉 GOAL! P2 12:34
🏒 Connor McDavid (Edmonton Oilers)
Oilers 3-2 Maple Leafs

Final Score:

🏁 FINAL - WIN! 🎉✅ 🏈
Kansas City Chiefs 31-24 Buffalo Bills

🤖 OpenClaw Integration

Automatic Cron Setup

The easiest way to set up match-day alerts is with the setup script:

# Run the setup script with your Telegram ID and timezone
python3 scripts/setup_crons.py <telegram_id> <timezone>

# Example
python3 scripts/setup_crons.py 123456789 "Europe/London"
python3 scripts/setup_crons.py 123456789 "America/New_York"

# Just view the cron configs without creating
python3 scripts/setup_crons.py --list

This creates 3 cron jobs:

Cron Job	Schedule	Purpose
football-match-check	Daily 9 AM	Checks if your teams play today
spurs-live-ticker	Every 2 mins (disabled)	Live updates during matches
spurs-reminder	Dynamic (disabled)	30-min pre-match reminder

How Auto-Scheduling Works

1. Morning check — football-match-check runs at 9 AM daily
2. Match found? — If any team plays today, it:
   • Updates spurs-live-ticker to start 5 mins before kickoff
   • Sets spurs-reminder for 30 mins before kickoff
   • Enables both crons
3. During match — spurs-live-ticker runs every 2 mins, sending goals/cards/events
4. No match? — Both crons stay disabled (no spam!)

Manual Cron Setup

If you prefer manual setup, here are the cron expressions:

# Daily match check at 9 AM
0 9 * * *    # football-match-check

# Live ticker every 2 minutes (enable only during matches)
*/2 * * * *  # spurs-live-ticker

# Pre-match reminder (set to 30 mins before kickoff)
30 14 * * *  # spurs-reminder (example: 2:30 PM for 3 PM kickoff)

Cron Payload Examples

Match Check (daily):

{
  "message": "Check if any configured teams play today. If a match is found, update spurs-live-ticker to start 5 mins before kickoff and run for 3 hours. Enable spurs-reminder for 30 mins before kickoff."
}

Live Ticker (during matches):

{
  "message": "Run python3 scripts/live_monitor.py and send any new events (goals, cards, halftime, fulltime). Only message if there are updates."
}

Live Monitor Script

During matches, run every 2 minutes:

python3 scripts/live_monitor.py

The script only outputs when there are new events (goals, cards, etc.), making it perfect for cron-based alerting.

🔧 Scripts Reference

Script	Purpose
ticker.py	Show current status of your teams
live_monitor.py	Check for live updates (for cron)
schedule.py	📅 View upcoming fixtures (v3)
auto_setup_crons.py	🤖 Generate match crons (v3)
espn.py	Direct ESPN API access
setup.py	Interactive setup wizard
config.py	Configuration management

📅 Schedule & Auto-Crons (v3 Feature)

The Problem (v2)

The old scoreboard-only approach meant:

• Only TODAY's matches were visible
• If your daily cron didn't run, you'd miss matches
• No advance notice of upcoming fixtures

The Solution (v3)

Schedule API scans future dates to find your team's fixtures:

# See what's coming up
python3 scripts/schedule.py --team spurs --days 30

# Output:
# 🐓 Tottenham Hotspur - Upcoming Fixtures
# 📅 Sat 07 Feb 12:30 UTC | @ Man United (Premier League)
#    📍 Old Trafford
# 📅 Tue 10 Feb 19:30 UTC | vs Newcastle (Premier League)
#    📍 Tottenham Hotspur Stadium

Auto-Cron Generator creates match-day cron jobs:

python3 scripts/auto_setup_crons.py --team spurs --days 14

# Generates:
# ✅ spurs-reminder-2026-02-07 (30 mins before kickoff)
# ✅ spurs-ticker-start-2026-02-07 (starts monitoring)
# ⏸️ spurs-ticker-2026-02-07 (every 2 mins during match)

Workflow

1. Run schedule.py weekly to see upcoming fixtures
2. Run auto_setup_crons.py --json to generate cron configs
3. Feed the JSON to OpenClaw cron API
4. Never miss a match again! 🎉

🌐 ESPN API Reference

Base URL: https://site.api.espn.com/apis/site/v2/sports

Endpoints

# Scoreboard (all today's games)
/{sport}/{league}/scoreboard

# Game details with events
/{sport}/{league}/summary?event={event_id}

# Team info
/{sport}/{league}/teams/{team_id}

Sport & League Codes

Soccer: soccer/eng.1, soccer/esp.1, soccer/uefa.champions Football: football/nfl Basketball: basketball/nba, basketball/wnba Hockey: hockey/nhl Baseball: baseball/mlb Racing: racing/f1

📄 License

MIT — use it however you want!

📚 ESPN API Resources

• Public ESPN API Documentation — comprehensive endpoint list
• ESPN OpenAPI Spec — formal OpenAPI/Swagger schema
• Interactive API Explorer — try endpoints in browser
• Zuplo Guide — overview & alternatives

⚠️ Note: ESPN's API is unofficial/undocumented. It's stable and widely used, but could change without notice. The skill handles errors gracefully.

🙏 Credits

• ESPN for their awesome (and free!) API
• pseudo-r, zuplo, and the community for API documentation
• Built with ❤️ for football fans everywhere

---

Happy tracking! ⚽🏆