NBA Odds API Integration: A Complete Developer Guide

Why NBA Odds API Integration Matters for Developers

The NBA is one of the most heavily bet sports in North America, with lines moving fast, player props proliferating nightly, and sharp money shifting spreads within minutes of tip-off. If you're building a sports betting app, a fantasy analytics tool, or a line-shopping dashboard, integrating a reliable NBA odds API is the foundation everything else is built on.

MoneyLine's NBA odds API gives you normalized, real-time odds data across all major markets — moneyline, spread, and totals — aggregated from multiple bookmakers into a single, consistent JSON response. Instead of scraping individual sportsbooks or stitching together inconsistent data formats, you get one clean endpoint that speaks the same schema every time.

The free tier is available for both personal and commercial use, making it accessible whether you're a solo developer prototyping a new idea or an engineering team shipping a production product. You can explore the full offering at the [NBA Odds API](/nba-odds-api) landing page.

Core Endpoints You'll Use for NBA Odds Integration

MoneyLine's API is organized around a small set of focused endpoints. For NBA odds integration, you'll primarily interact with three: `/v1/events`, `/v1/odds`, and `/v1/player-props`. Each returns normalized JSON so you don't need to write separate parsers for different bookmakers.

**`/v1/events`** — This is your starting point. Filter by `leagueId` for the NBA to get a list of upcoming and live games. Each event in the response carries an `eventId` that you'll use to query odds and props. Events also include team names, game status, and scores so you can build a complete game feed from a single call.

**`/v1/odds`** — Pass an `eventId` (retrieved from `/v1/events`) to get the full odds picture for that game. The response contains a summary section with `moneyline`, `spread`, and `total` arrays, each item shaped as `{ name, point?, fairOdds, bestOdds, avgOdds }`. It also includes a `bookmakers` array where each entry has `bookmakerId`, `bookmakerName`, `sourceType`, and a `markets` array. Each market has a `marketType` and an `outcomes` array of `{ name, point?, price }` objects.

**`/v1/player-props`** — NBA player props are where a lot of the betting value lives, especially for points, rebounds, assists, and three-pointers made. This endpoint returns prop lines nested under each player, with `teamAbbr` and `teamName` fields for easy display. You can filter by `eventId` and prop type to keep responses lean.

For sharper use cases, `/v1/edge` surfaces positive expected value (+EV) and arbitrage opportunities, and `/v1/best-bets` provides model-driven picks. `/v1/ai/chat` lets you embed a conversational betting assistant directly in your product.

Making Your First NBA Odds API Request

Authentication is handled via a single request header: `x-api-key`. Include your API key in every request. There are no OAuth flows or token refreshes to manage — just set the header and start making calls.

Here's a step-by-step integration flow for displaying NBA game odds in your app:

**Step 1: Fetch NBA events.** Call `GET /v1/events?leagueId=NBA` with your `x-api-key` header. Parse the response to extract `eventId` values for games you want to display. Store the team names and game timestamps alongside each `eventId` for your UI layer.

**Step 2: Fetch odds for a specific game.** Call `GET /v1/odds?eventId={eventId}` for each game. In the response, read the top-level summary: the `moneyline` array gives you `bestOdds` and `fairOdds` for each side so you can immediately show users where the best price is and what the no-vig line looks like. The `avgOdds` field is useful for line-shopping context.

**Step 3: Drill into bookmaker-level data.** Iterate over the `bookmakers` array. For each bookmaker, loop through `markets` and then `outcomes`. Each outcome has a `name` (e.g., "Lakers"), an optional `point` (for spreads and totals), and a `price` (American odds integer). This is where you build your odds comparison table or line-shopping widget.

**Step 4: Display player props.** Call `GET /v1/player-props?eventId={eventId}` and render prop lines grouped by player. Each player node includes `teamAbbr` and `teamName`, making it straightforward to group props by team or display them in a player card format.

A typical JavaScript fetch for Step 2 looks like this: `fetch('https://api.moneyline.com/v1/odds?eventId=abc123', { headers: { 'x-api-key': 'YOUR_KEY' } }).then(r => r.json()).then(data => console.log(data.moneyline))`. Swap in your real `eventId` from the events call and you're live.

Working with the Odds Response Schema

Understanding the exact shape of the response is the difference between a clean integration and hours of debugging. Let's walk through the key objects you'll encounter when querying NBA odds.

The top-level summary arrays — `moneyline`, `spread`, and `total` — each contain objects with the shape `{ name, point?, fairOdds, bestOdds, avgOdds }`. The `name` field is the outcome label (team name for moneyline and spread, "Over" or "Under" for totals). The `point` field is present for spreads (e.g., `-5.5`) and totals (e.g., `224.5`) but absent for moneyline outcomes. `fairOdds` represents the no-vig probability-implied price, `bestOdds` is the highest available price across all tracked bookmakers, and `avgOdds` is the market average. Showing the gap between `fairOdds` and `bestOdds` is a great way to surface betting value in your UI.

The `bookmakers` array provides granular per-book data. Each bookmaker object has `bookmakerId` (a stable identifier you can use as a key), `bookmakerName` (display-ready string), and `sourceType` (indicating whether the data comes from an exchange, retail sportsbook, or other source). The `markets` array inside each bookmaker contains objects with `marketType` (e.g., `"moneyline"`, `"spread"`, `"total"`) and an `outcomes` array of `{ name, point?, price }` objects. The `price` field is always in American odds format.

When building a line-shopping feature, you'll want to create a data structure keyed on `marketType` and `name`, then iterate bookmakers to find the max `price` for each outcome. The summary layer (`bestOdds`) already does this for you, but the bookmaker-level data lets you attribute which book is offering that best price so users know where to go.

For NBA totals, pay attention to line movement between the `point` values across bookmakers — it's common to see one book at 224 while another is at 225.5 during sharp action, which itself is a signal. Combine this with the `/v1/edge` endpoint to surface lines where the `fairOdds` gap is most exploitable.

NBA Player Props Integration: Points, Rebounds, and Assists

Player props are the fastest-growing segment of NBA betting, and your integration should treat them as a first-class data type rather than an afterthought. The `/v1/player-props` endpoint returns a rich nested structure organized by player, making it easy to build prop cards, stat comparison tools, or prop-betting alert systems.

Each player node in the response includes `teamAbbr` (e.g., `"LAL"`) and `teamName` (e.g., `"Los Angeles Lakers"`), which you can use to group props by team or match them against your own player database. Under each player, you'll find prop markets structured similarly to the main odds endpoint — with `marketType` indicating the prop category (points, rebounds, assists, three-pointers made, blocks, steals, etc.) and outcomes carrying `name`, `point`, and `price`.

A common use case is building a prop comparison table that shows each player's prop line across multiple books. Fetch the event's player props, group by player name, then for each marketType find the `bestOdds` for Over and Under separately. Display the book offering the best Over price and the book offering the best Under price side by side — this alone is a compelling feature for a props-focused product.

You can also combine player props data with the `/v1/edge` endpoint to flag props where the implied probability differs meaningfully from the fair market price. For deeper prop analysis, check out related content like the [NBA Points Props — Top Over Hit Rates (L25)](/blog/nba-points-props-top-over-hit-rates-l25) post, which demonstrates how to analyze historical prop performance alongside live API data.

Advanced Use Cases: Line Movement, +EV Detection, and AI Chat

Once you've mastered the basics of fetching and displaying NBA odds, there's a layer of more advanced functionality that separates a good product from a great one. MoneyLine's API gives you the tools to build all of it.

**Line movement tracking:** Poll `/v1/odds` for the same `eventId` at regular intervals and store the `avgOdds` and `point` values in your database. Chart how the spread or total shifts over time and you've built a line movement tracker — one of the most requested features in sports betting apps. Fast-moving lines often signal sharp action or breaking news, both of which are high-value signals for your users.

**Positive expected value (+EV) detection:** The `/v1/edge` endpoint does the heavy lifting here. It compares the `fairOdds` (no-vig price) against the best available book price and surfaces outcomes where the book price is better than fair. For NBA, this commonly appears on player props and alternate spreads where market efficiency lags behind the main lines. You can filter results by sport and league to show only NBA edges, then display them with a badge or alert in your UI.

**Arbitrage opportunities:** Also surfaced via `/v1/edge`, arb opportunities occur when the combined implied probability of two outcomes across different books is below 100%. For a fast-moving NBA game, these windows can be short-lived, so your integration should support near-real-time polling and push notifications to be useful.

**AI Chat integration:** The `/v1/ai/chat` endpoint lets you embed a conversational assistant that can answer natural language questions about NBA odds, props, and trends. This is a powerful way to add a premium feature without building a full NLP stack — pipe user questions to the endpoint and stream the response back into your chat UI.

If you're building a React or Next.js frontend, the [Odds API for Next.js](/odds-api-nextjs) guide covers framework-specific patterns for data fetching and caching that apply directly to NBA odds integration.