Does the route return current prices year-round?

No. It returns the latest line held for the player. The freshness block tells the client whether that line is live, recent or stale.

Can a missing line render as zero?

No. Zero is a possible number; missing means the market is not present. Keep those states distinct.

Is the rolling hit rate a prediction?

No. It is historical context computed from the documented sample, not a guarantee about the next game.

Do full-game odds come with the same Free access?

No. The exact odds route carries its own Edge plan floor.

Tutorial · 9 min · endpoints verified 2026-09-22

How to build an NBA props tracker

Fetch a player line, show the rolling hit-rate context, and make stale or missing prices impossible to mistake for a current market.

API coverage and endpoint overview: Explore the NBA API

Why this is hard

A returned line is not automatically a current line

The useful product is not a number in a card. It is a line tied to a player, market, timestamp and sample window, with a visible state when any of those pieces is absent or old.

Off-season and settled prices can remain queryable, so freshness must render beside the line.
A rolling hit rate needs its sample window; the percentage alone is incomplete.
Player ids must come from a served discovery path rather than a name guess.
A missing market is an empty state, not a synthetic 0.5 line.

Path 1 · recommended

Have your AI agent build it

Use MCP to inspect basketball coverage and find the player context. The player-props route itself is REST-only, so have the agent call it over HTTP with the same account.

1. Connect the MCP server

Add the server in your MCP client and sign in with your Big Balls account. Your client registers itself and handles the token exchange — there is no key to copy.

MCP client configjson

{
  "mcpServers": {
    "bigballs-sports-data": {
      "url": "https://mcp.bigballsdata.com/mcp"
    }
  }
}

2. Tools your agent gets

find_players
Find canonical player IDs by name for use with player-stat tools.
get_player_stats
Per-player career or per-season totals and per-game rates.
get_coverage
Machine-readable map of what we hold and what we do not.

3. Ask for what you want

Paste this at your agent. It is written to make the model check coverage before it designs anything, which is what stops it inventing a field we do not serve.

Prompttext

Build an NBA player-props tracker. Check basketball coverage first,
resolve a canonical player id, then call the NBA props REST endpoint. Render the
line, market, rolling sample and freshness together. If the response is stale or
has no line, show that state and do not substitute a plausible value.

What the agent cannot reach

The MCP server does not expose the NBA props route. It can establish coverage and identity, but the line and freshness block must come from REST.

Path 2 · hand-coded

Build it yourself

The tracker follows a served player id into the props response and treats freshness as data, not footer copy.

01
Resolve the player before the market
Use a served NBA player list or leader row and retain the identifier required by the props route. Do not resolve a player by display name inside the card.
Start from a served leaderboardbash
```
curl -s "https://api.bigballsdata.com/v1/nba/leaders?stat=pts&limit=25" \
  -H "Authorization: Bearer $BBS_API_KEY"
```
02
Fetch one documented prop market
Request the player route and keep market, line, prices, sample window and freshness from the same response.
Fetch the player props responsebash
```
curl -s "https://api.bigballsdata.com/v1/nba/players/$PLAYER_ID/props" \
  -H "Authorization: Bearer $BBS_API_KEY"
```
03
Gate the current-price presentation
Only style a line as current when its freshness status supports that claim. Keep stale, recent and missing states visible and preserve the response timestamp.
Model freshness explicitlytypescript
```
const state = response.data?.line == null
  ? 'missing'
  : response.freshness?.status ?? 'unknown';

return { state, dataAsOf: response.freshness?.data_as_of ?? null, line: response.data?.line ?? null };
```

Reference

Every endpoint this tutorial uses

All on the gateway at api.bigballsdata.com. Verified against production on 2026-09-22.

Method	Path	Returns	Why you need it	Plan
GET	/v1/nba/leaders	Qualified NBA leaders with player identity and team context	A served identity source for the player selector.	Free
GET	/v1/nba/players/:id/props	Held player lines, rolling hit-rate context and freshness metadata	The tracker card and the source of its freshness state. Read the freshness guide.	Free

Pricing, honestly

Player props start free; game markets are separate

The player props route has a Free entry point. Current full-game odds are an Edge capability and must not be implied by access to a player line.

Free player context

texttext

GET /v1/nba/players/:id/props

Edge game markets

texttext

GET /v1/matches/:id/odds

Freshness metadata is part of the Free response contract.
An upgrade does not make an old line current.
Game markets and player props are different product surfaces.
Missing markets remain honest empty states on every plan.

See the full plan ladder →

Other build guides

Known gaps

What the first tracker leaves out

Ship the trustworthy line card before adding portfolio or alerting features.

No synthetic consensus line when multiple books or markets are absent.
No automatic bet recommendation derived from a hit rate alone.
No “live” badge without a freshness state that supports it.

Questions

Does the route return current prices year-round?: No. It returns the latest line held for the player. The freshness block tells the client whether that line is live, recent or stale.
Can a missing line render as zero?: No. Zero is a possible number; missing means the market is not present. Keep those states distinct.
Is the rolling hit rate a prediction?: No. It is historical context computed from the documented sample, not a guarantee about the next game.
Do full-game odds come with the same Free access?: No. The exact odds route carries its own Edge plan floor.

Related APIs

Other APIs you can build with:

NBA API — Live Scores, Box Scores & Props Free Basketball API: Scores & Stats NCAA Basketball API WNBA API

Also on this sport

NBA Player Props API NBA Shot Chart API

Stats reference

NBA Player Stats API NBA Player Props API Odds & two-source verification

Build the honest props tracker

Start free, keep the timestamp beside the line, and let stale data look stale.