Data for a fantasy football Discord bot

Quick answer: A fantasy football Discord bot needs four things: find a player (/players/search), get his projection (/projections/{week}), read his news (/news/{player_id}) and hear about injury changes (/injuries/changes or a webhook). Lookups and this week's projections work on a free key; news needs Basic ($9 a month or $59 a year) and injury changes need Pro ($29 a month or $249 a year). A bot for your own league works on any plan, a free public bot needs Basic or above, and a bot in a paid Discord needs Pro + Commercial ($49 a month or $490 a year).

Free key
Lookups + this week
News
Basic
Injury alerts
Pro
Paid server
Pro + Commercial

Which endpoints does a Discord bot use?

Bot featureEndpointPlan
Find a player by full or partial nameGET /players/search?name=Free
A player's projection this week (PPR, half or standard)GET /projections/{week}?team=&position=Free for the current week; Basic for other weeks
A player's recent news, tagged injury, transaction, role or generalGET /news/{player_id}Basic
A league-wide news channelGET /news/latest?since=Basic
Snap share and stats for "is he still the starter?"GET /snaps/{player_id}, GET /stats/{player_id}/{season}Basic
Injury alerts by pollingGET /injuries/changes?since=Pro
Injury alerts pushed to your serverPOST /webhooks (register once)Pro
Matchup command: what a defense allows by positionGET /defensePro
Who starts: depth chartsGET /depth-chartsPro

Every call sends the key in the x-api-key header to https://api.gridirondata.com/api/v1. A key below the plan an endpoint needs gets HTTP 403 with reason basic_required or pro_required.

What does a minimal discord.py bot look like?

One slash command, /proj, that finds a player and replies with GridIron Data's own projection for the week. It needs discord.py (which brings aiohttp), a bot token in DISCORD_TOKEN, your key in GRIDIRON_API_KEY and the week in NFL_WEEK. It works on a free key for the current week.

import os
import aiohttp
import discord
from discord import app_commands

API = "https://api.gridirondata.com/api/v1"
HEADERS = {"x-api-key": os.environ["GRIDIRON_API_KEY"]}
WEEK = int(os.environ["NFL_WEEK"])  # a free key answers the current week only

client = discord.Client(intents=discord.Intents.default())
tree = app_commands.CommandTree(client)


async def api(session, path, **params):
    async with session.get(API + path, headers=HEADERS, params=params) as r:
        return r.status, await r.json()


@tree.command(description="This week's GridIron Data projection for a player")
async def proj(interaction: discord.Interaction, name: str):
    await interaction.response.defer()  # Discord needs an answer within 3 seconds
    async with aiohttp.ClientSession() as s:
        status, found = await api(s, "/players/search", name=name, limit=1)
        if status != 200 or not found.get("players"):
            await interaction.followup.send(f"No player matches {name!r}.")
            return
        p = found["players"][0]
        status, body = await api(s, f"/projections/{WEEK}", team=p["team"], position=p["position"])
    if status != 200:
        await interaction.followup.send(body.get("error", "GridIron Data error"))
        return
    row = next((x for x in body["projections"] if x["player_id"] == p["player_id"]), None)
    gp = row.get("gridiron_projection") if row else None
    if not gp:
        await interaction.followup.send(f"No projection for {p['player_name']} in week {WEEK}.")
        return
    await interaction.followup.send(
        f"**{p['player_name']}** ({p['team']}) week {WEEK}: {gp['projected_points']} PPR points, "
        f"status {row['injury_status']}\nData: GridIron Data (gridirondata.com)")


@client.event
async def on_ready():
    await tree.sync()


client.run(os.environ["DISCORD_TOKEN"])

On November 19, 2026, Justin Jefferson's week 11 row had gridiron_projection.projected_points 17.71 and injury_status ACTIVE, so /proj Justin Jefferson would answer "Justin Jefferson (MIN) week 11: 17.71 PPR points, status ACTIVE". The bot shows gridiron_projection rather than projected_points because GridIron Data's own projections may be shown to users under Pro + Commercial with the "Data: GridIron Data" credit; the consensus projected_points may not (see the license section below).

Each /proj costs 2 requests. To spend less, fetch each position's projections once (4 requests for QB, RB, WR and TE) and answer commands from that cache for a few hours; projections refresh about once a day.

How does a bot get injury alerts?

Two ways, both Pro. Polling: call /injuries/changes?since= with the next_since from your last response and post what is new. GridIron checks ESPN's injury report every 2 minutes from 8:00 am to 1:00 am ET, so polling every 5 minutes is enough; that is about 1,430 requests a week. The Discord injury bot guide has a full script, including a fallback for Free and Basic keys. Webhooks: register one HTTPS URL with POST /webhooks (or on your dashboard) and GridIron POSTs each batch of changes to it within a few minutes. Webhook calls never count against your monthly requests.

GridIron's webhook body is its own JSON (type, changes), not a Discord message, so point the webhook at a small relay that checks the signature and then posts to your Discord channel webhook. A Flask version:

import hashlib, hmac, json, os, time
import requests
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["GRIDIRON_WEBHOOK_SECRET"]  # whsec_..., shown once when you register
DISCORD = os.environ["DISCORD_WEBHOOK"]          # the channel's webhook URL


@app.post("/gridiron")
def gridiron():
    ts = request.headers.get("X-GridIron-Timestamp", "0")
    raw = request.get_data()
    expected = "sha256=" + hmac.new(SECRET.encode(), f"{ts}.".encode() + raw,
                                    hashlib.sha256).hexdigest()
    if (not ts.isdigit() or abs(time.time() - int(ts)) > 300
            or not hmac.compare_digest(expected, request.headers.get("X-GridIron-Signature", ""))):
        abort(401)
    event = json.loads(raw)
    lines = [f"{c['player_name']} ({c['team']}): {c['previous_status']} -> {c['status']}"
             for c in event.get("changes", [])]
    if lines:
        requests.post(DISCORD, json={"content": "\n".join(lines)[:2000]}, timeout=4)
    return "", 204

Answer within 5 seconds: GridIron retries timeouts and 5xx answers twice, and turns the webhook off after 5 failed deliveries in a row. Signature and delivery rules are in the webhook docs.

What are the rate limits per plan?

PlanPriceRequestsPer minute
Free$0, no card50 per month10
Basic$9 per month or $59 per year5,000 per month30
Pro$29 per month or $249 per year50,000 per month100
Pro + Commercial$49 per month or $490 per year50,000 per month100

Limits apply per API key, and the free count resets on the 1st of each month at 00:00 UTC. Over a limit the API answers HTTP 429 with reason free_monthly_quota, quota_exceeded or rate_limited; back off and retry after the minute for rate_limited. A server that runs 100 uncached /proj commands a day uses about 6,000 requests a month, more than Basic allows, which is why the cache above matters.

Can I run the bot in a paid Discord?

Only with Pro + Commercial (or Enterprise). The Commercial License table, word for word:

UseFreeBasicProPro + Commercial
Personal projects, your own league, learning, a classYesYesYesYes
A free, non-commercial public site or bot (no ads, no subscriptions) that shows your own outputsNoYesYesYes
Runtime input to a product people pay for (subscriptions, ads, paid tiers, a paid Discord)NoNoNoYes

"Commercial" means the product earns money, directly or through ads, sponsorships or affiliate links, or is run by a business for its customers. Under Pro + Commercial, the bot may show GridIron Data's own projections and supporting facts such as recent game lines, snap share and injury status, credited as "Data: GridIron Data" with a link to gridirondata.com. The consensus projections and prop probabilities stay internal benchmarking only, and news items may be shown as a headline linking to the original source. Pro + Commercial is for companies under $250,000 a year in revenue.

Frequently asked questions

Can I build a Discord bot on the free plan?

For your own league, yes: a free key covers player lookups and this week's projections, 50 requests a month at 10 a minute. A free public bot needs Basic or above, and news needs Basic.

Can GridIron Data send injury alerts straight to a Discord channel?

Not directly. Pro keys can register a webhook, but the body is GridIron's JSON, not a Discord message. Point it at a small relay that verifies the signature and posts to your channel's webhook, or poll /injuries/changes.

Do I need Pro + Commercial for a bot in a paid Discord?

Yes. The license lists runtime input to a product people pay for, including a paid Discord, as Pro + Commercial or Enterprise only. Pro + Commercial is $49 a month or $490 a year.

What are the rate limits for a Discord bot?

Free: 50 requests a month, 10 a minute. Basic: 5,000 a month, 30 a minute. Pro and Pro + Commercial: 50,000 a month, 100 a minute. Cache projections to keep a busy server inside its plan.