SportAPI
API integration

Sportsbook API Integration in 7 Days: What the Developer Does Each Day

A day-by-day plan for one developer: menu and events on day 1, markets on day 2, live on day 3, bets on day 4, settlement on day 5, cache and security on day 6, a launch checklist on day 7.

Infographic of a seven-day sportsbook API integration plan: one card per day, from the menu and event list to the launch

One developer can finish a sportsbook API integration in seven working days: the odds feed, bet placement and settlement, with a backend that keeps the API key away from the browser. The trick is to split the work by days and end each day with something you can check on a real match. Below is that split, with the requests, the code and the check for every day.

If you only need odds on your site and don’t accept bets, you need day 0 to day 3 plus day 6. That’s four working days. Days 4 and 5 add the bet slip and settlement through the Coupon API.

For scale: with the ready examples, the first screen with real events takes about 20 minutes. A team that already knows betting systems does the full cycle in about five days, while a team new to the domain can spend a month. Seven days is the realistic middle for one developer who hasn’t worked with a sportsbook feed before but reads the documentation. The plan below is for Sport Line API, the SportAPI odds feed, and the Coupon API, but most of the steps apply to any provider that gives you a line and takes bets through JSON.

Why an integration drags on for months

Rarely because of the API itself. The time goes into decisions nobody made at the start:

What eats the timeWhat happensWhat the plan does instead
No order of workThe developer explores the API instead of building the productOne screen per day, in the order players use them
Calls from the browserThe key leaks, the integration is rewritten through a backendA backend proxy from day 1
A fixed list of sports and marketsA tournament disappears from the line and the page breaksOnly current IDs from menu, markets as the API returns them
Prematch and live linked by ID”Ghost” matches that never go liveSeparate prematch and live storage from day 3
Home-made settlementWeeks on Asian handicaps, cancellations and resettlementResults come from the API, your code only pays
Polling at any rateHTTP 429 and blocked outcomes nobody noticedIntervals from the documentation, one poller for all players
HTTP 200 treated as successRejected coupons saved as acceptedThree checks on every bet: HTTP status, code, error_code

Each of these costs a day to fix in the plan and a month to fix after launch.

Day 0. What to get from the manager

This is half a day, and most of it is waiting for messages. Write to the SportAPI manager on Telegram and get:

  • For the odds feed: the API base URL and the key. The key goes into the Package HTTP header of every request. Confirm which sports and languages your key covers.
  • Server addresses. A key can be restricted to your server IPs or sites. Send the IP of the machine that will make the requests, otherwise you’ll get Access from IP … is not allowed for this Package.
  • For bets: the Coupon API base URL, a login and password for the partner account, and, if you want callbacks, the callback_secret the manager creates for you.

The free key lasts two days and includes all sports, prematch and live. That’s enough for days 1 and 2. From day 3 you’ll be on a paid plan, from $30 a month for one sport, so pick the sport you’ll launch with. Bet placement and settlement, the Coupon API, start at $300 a month.

Check the key before you write any code:

curl 'https://YOUR_API_DOMAIN/v1/account' --header 'Package: YOUR_API_KEY'

The account method returns the key’s terms, sports, languages, restrictions, the address you’re calling from in your_ip, and your request counts for the last 7 days. It’s the first thing to look at when something stops working later.

Day 1. The menu and the first screen with events

Two requests give you a working list of matches. The menu returns the current hierarchy of sports, countries and tournaments in one call, and events returns the matches of a sport with their main odds:

GET /v1/menu/live/en
GET /v1/events/1/0/sub/50/live/en

Here 1 is football, 0 means all tournaments of the sport, sub/50 is the required format (the API returns all events in the scope regardless of the number), live is the line type and en is the language. The response is grouped by tournament: body[] holds tournaments, each with an events_list[], and each event has game_id, opp_1_name, opp_2_name, game_start as a Unix timestamp, score_full, period_name, timer in seconds and game_oc_list with the main markets.

The code that matters on day 1 is the backend proxy. It’s the only place in your system that knows the key, and it serves one cached copy of the line to every player:

// server/line.js: the only module that talks to Sport Line API
const API = process.env.SPORTAPI_BASE_URL; // the API domain the manager issued with the key
const KEY = process.env.SPORTAPI_KEY; // never sent to the browser

const cache = new Map();    // path -> { at, body }
const inflight = new Map(); // path -> Promise, so requests never overlap

export async function fetchLine(path, ttlMs) {
  const hit = cache.get(path);
  if (hit && Date.now() - hit.at < ttlMs) return hit.body;
  if (inflight.has(path)) return inflight.get(path);

  const request = (async () => {
    const res = await fetch(`${API}${path}`, { headers: { Package: KEY } });
    const data = await res.json();
    if (!res.ok || data.error_code) {
      const err = new Error(data.error_message || `HTTP ${res.status}`);
      err.status = res.status;
      throw err;
    }
    cache.set(path, { at: Date.now(), body: data.body });
    return data.body;
  })().finally(() => inflight.delete(path));

  inflight.set(path, request);
  return request;
}

// routes the front end calls; TTLs are the minimum intervals from the docs
app.get('/api/menu/:type', async (req, res) => {
  const ttl = req.params.type === 'live' ? 20_000 : 60_000;
  res.json(await fetchLine(`/v1/menu/${req.params.type}/en`, ttl));
});

app.get('/api/events/:type/:sportId', async (req, res) => {
  const { type, sportId } = req.params;
  const ttl = type === 'live' ? 7_000 : 30_000;
  res.json(await fetchLine(`/v1/events/${sportId}/0/sub/50/${type}/en`, ttl));
});

Two things in this snippet save you days later. The inflight map means a slow response never piles up duplicate requests for the same data. The cache means a thousand players on the live page produce one request to the API every 7 seconds, not a thousand.

Team logos, flags and sport icons are served ready-made by ID, so you don’t need to host images. The address templates come with the integration guide; for a team you insert opp_1_icon without its file extension.

Check at the end of day 1: the list of live matches renders with scores, the timer counts up locally between requests (the API returns timer in seconds, you divide by 60 and keep counting on the client), and the main odds show up for each match. Don’t call menu as often as events: 20 seconds for live and 60 for prematch is the minimum.

Day 2. The match page and markets

The full list of markets for one match comes from event in group format:

GET /v1/event/{gameId}/group/live/en

The API has already done the layout work: game_oc_list[] holds markets, each market’s oc_list[] holds columns, and each column holds selections. The columns field is the recommended number of columns for the interface. Keep the order of markets, columns and selections as the API returns them. Don’t resort them and don’t build the page around a fixed set of market names, because basketball usually has no draw and tennis never does.

// body.game_oc_list: markets -> columns -> selections
function marketsForPage(game) {
  return game.game_oc_list.map((market) => ({
    id: market.group_id,        // use for logic
    name: market.group_name,    // use for display, depends on the language
    columns: market.oc_list.map((column) =>
      column.map((oc) => ({
        name: oc.oc_name,
        size: oc.oc_size,                       // total or handicap value
        rate: oc.oc_block ? null : oc.oc_rate,  // blocked: no button
        pointer: oc.oc_pointer,                 // goes into the bet slip untouched
      })),
    ),
  }));
}

The fields a bet slip needs are oc_rate, the current odds, oc_size, the total or handicap value, oc_pointer, the selection ID you’ll later send to the Coupon API, and oc_block. A blocked selection stays in the response so the page doesn’t jump, but it must have no button.

Halves, corners, cards and other sub-events are listed in sub_games[] of the main match. Each has its own game_id, and its odds come from a separate event request with that ID. The response then contains only that sub-event’s markets. For screens that don’t show odds, such as a schedule, add ?odds=false: the response is 2 to 5 times smaller.

Check at the end of day 2: open any live match on your page and in the raw API response side by side. Same markets, same order, same odds, and every oc_block: true selection is disabled on your page.

Day 3. Live: polling, intervals and “Game id finished”

Sport Line API is REST, so your server asks for a fresh snapshot at an interval. WebSocket is still in development, so plan on polling. The minimum intervals are in the data update guidelines:

MethodLivePrematch
menu20 s60 s
events (match list)7 s30 s
event (one match)5 s30 s

Three rules make live stable. Request event only for matches someone has open, not for every match in the list. Don’t start a request while the previous one for the same data is still running. And after an error, wait longer before trying again: 5, 10, 20, 40 seconds, then back to normal once a response succeeds.

// one loop per open match; stops when the match leaves the line
async function pollEvent(gameId, onUpdate, onGone) {
  let delay = 5_000; // event, live: 5 s minimum
  for (;;) {
    try {
      const body = await fetchLine(`/v1/event/${gameId}/group/live/en`, 5_000);
      if (body.message === 'Game id finished') return onGone(gameId);
      onUpdate(body);
      delay = 5_000;
    } catch (err) {
      if (err.status === 404) return onGone(gameId); // Game not found: stop
      delay = Math.min(delay * 2, 40_000);           // 5 -> 10 -> 20 -> 40 s
    }
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
}

The part that surprises every first integration: when a match moves from prematch to live, it gets a new game_id. The two IDs are not linked, and there’s no status that says “this prematch match has started”. So store prematch and live separately, take the live list from events with the live type, and don’t try to match them by ID.

When a match leaves the line, event for the old ID returns Game id finished with HTTP 200. It doesn’t tell you why: the match may have gone live under a new ID, been cancelled or disappeared from the line. Stop polling that ID, refresh the menu and the event list, and don’t use this message to decide whether the match ended.

Live matches also carry stat_list with the key statistics for the sport, zp for the ready-made match tracker widget and va / vi for video. None of them are needed on day 3, but they’re free data for later. How the data travels from the feed to the player’s screen, with latency at each step, is in our live data pipeline article.

Check at the end of day 3: open a live match, watch the score and the odds change on your page within a few seconds of the API response, pull the network cable for a minute and watch the delays grow and then recover. Then wait for a match to finish and confirm the loop stops.

Day 4. The bet slip and placement

From here on you work with the Coupon API, the bet placement and settlement service. It has its own base URL and its own auth: POST /api/partner/login with your login and password returns a JWT that goes into the Authorization: Bearer header. When a request returns HTTP 401, log in again.

A bet is a pointer built from what the player saw on day 2. Take oc_pointer from the line unchanged, prefix it with the line type and append the odds:

line_type#oc_pointer#oc_rate
line#123456789|1|3|0#1.4

If the selection has a player ID in op_id, append it as one more # segment. Then place the coupon:

// POST /api/bets: the bet slip sends what the player saw
app.post('/api/bets', requireUser, async (req, res) => {
  const { type, pointer, rate, amount } = req.body;
  const listBets = [`${type}#${pointer}#${rate}`];
  await wallet.reserve(req.user.id, amount); // balances live in your system

  const r = await fetch(`${COUPON_API}/api/partner/coupons/place`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${await partnerToken()}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      list_bets: listBets,
      amount,
      currency: 'USD',
      lang: 'en',
      mode: 'reject', // odds changed: refuse and show the new price
      callback_url: process.env.COUPON_CALLBACK_URL,
    }),
  });
  const data = await r.json();

  // three checks, in this order: HTTP status, code, error_code
  if (!r.ok || data.code !== 1) {
    await wallet.release(req.user.id, amount);
    return res.status(409).json({
      error: data.error_code,             // 501: odds changed, 503: blocked
      changes: data.body?.changes ?? [],  // the new odds for 501-504
    });
  }

  for (const coupon of data.body.coupons) {
    await bets.save(req.user.id, coupon.coupon_code, coupon); // code is a string
  }
  res.json({ coupons: data.body.coupons.map((c) => c.coupon_code) });
});

What the rejections mean and what the slip should show:

CodeReasonShow the player
501The odds changedThe new odds from body.changes[] and a button to accept them
502The outcome is no longer availableRemove it from the slip
503The outcome is blocked”Temporarily unavailable”, keep it in the slip
504Verification error”Try again in a moment”; don’t mark the bet as placed
506Two bets from one match in an accumulator”Only one bet per match in an accumulator”
507Insufficient partner balanceNothing player-facing; alert your own team

If you’d rather accept changed odds automatically, send mode: 'accept' with mode_type: 1 for increases only, 2 for decreases only, 3 for any change. The usual default is reject with a toggle for the player. An accumulator is the same request with several pointers and multi: false; it holds up to 15 legs and can’t contain two bets on the same match, including its halves and corners.

Two rules that prevent money bugs. A business error arrives with HTTP 200 and code: 0, so a check on the HTTP status alone saves rejected coupons as placed. And a timed-out place request must not be retried blindly: the first one may have gone through, and a retry creates a duplicate. Query the coupon or your own records first.

Check at the end of day 4: place a single and an accumulator on the test balance, see them in GET /api/partner/coupons/active, then place a bet on a live match while the odds are moving and watch the 501 path show the new price.

Day 5. Settlement: the callback and the polling fallback

You don’t write settlement logic. After the match the Coupon API settles every bet in the coupon, main markets, halves, corners, Asian lines, and sends the result to your callback_url with an HMAC signature. How the settlement itself works, which markets it covers and how fast, is in our article on automated bet settlement; the callback handler with the signature check is there too. Today’s work is wiring it in correctly.

Rules the handler must follow:

  1. Compute sha256=<hex HMAC-SHA256> over the raw request body, before JSON parsing, with callback_secret, and compare it with the X-Coupon-Signature header in constant time.
  2. Store batchId with a unique index. The same batch may be delivered again, and a repeated batchId must not pay twice.
  3. Process every coupon in the batch, up to 100 per callback, and reply HTTP 200 only after all of them are saved. The API retries on timeouts and on 500, 502, 503 and 504: immediately, then after 1, 5, 15 and 60 minutes, five sends at most.
  4. Pay from realWin only. Coupon status 2 is a win, 4 a loss, 8 a full refund, 15 means a recalculation is coming: if you already paid, debit the stake again, wait for the new final status and pay the new realWin.
  5. One coupon_code can arrive in different batches during progressive settlement and resettlement. Make the payout function idempotent per coupon and batch.

A callback can be lost while your server is down, so the same day you add polling. Every few minutes, ask for coupons settled recently and run them through the same idempotent function:

// every 5 minutes: catch up on coupons settled in the last 10 minutes
setInterval(async () => {
  const r = await fetch(`${COUPON_API}/api/partner/coupons/calculated?time=10`, {
    headers: { Authorization: `Bearer ${await partnerToken()}` },
  });
  const data = await r.json();
  for (const coupon of data.body ?? []) {
    // the same function the callback handler calls; a second run changes nothing
    await bets.applyResult(coupon.coupon_code, coupon.status, coupon.real_win);
  }
}, 5 * 60 * 1000);

The calculated method looks back at most 120 minutes. After a longer outage, use POST /api/partner/coupons/results with your saved coupon codes, up to 100 per request, or with a creation period of up to 24 hours. Note the field names: the callback sends realWin, the full coupon model sends real_win.

Check at the end of day 5: settle a test coupon, replay the same callback body twice and confirm the balance changed once. Stop your callback endpoint for an hour, place and settle a bet, start the endpoint again, and confirm polling delivered the result.

Day 6. Cache, load and security

Day 6 has no new endpoints. It’s the day you make the integration survive a Saturday evening.

RuleWhy
One poller per data set, many players read from your cacheThe line is the same for everyone; a request per player is wasted and hits the limit
Stay under 50 requests per second on average, 100 in a burstAbove that the API returns HTTP 429 with a Retry-After header; wait that many seconds
Honour Retry-After on 503 as wellsearch and event for a match not yet in memory return 503 while the source loads
The key, the partner password, the JWT and callback_secret live only on the serverA key in browser JavaScript or a mobile app is a key anyone can use; the JWT must not appear in URLs or full in logs
Money as decimals, coupon_code as a stringFloats drift; coupon codes have 12 digits and can start with zeros
Callback over HTTPS in productionHTTP is allowed for test environments only
Log every failed request with the URL without the key, the time, the HTTP status and error_codeThat’s exactly what support asks for, and it cuts a day of back-and-forth

If you cache event responses for 5 seconds and events for 7, even a few thousand concurrent players stay far below the limit. The limit is per key, and the manager can change it by agreement, but a correctly cached integration never reaches it.

Check at the end of day 6: run a load test against your own endpoints, not the API, and count the outgoing requests. The number shouldn’t change when you add virtual players.

Day 7. The launch checklist

Before switching from the test key to a production plan, go through the list. Each item is a place where integrations break:

  1. The API key, the partner credentials and callback_secret are not in the front-end bundle, the repository or the logs.
  2. menu, events and event are requested at or below the documented intervals.
  3. Requests for the same data don’t overlap.
  4. Prematch and live are stored separately and never linked by game_id.
  5. Game id finished stops polling and refreshes the list.
  6. Markets render in the order the API returns them, and oc_block: true selections have no button.
  7. The timer counts locally and resyncs on every response.
  8. A bet is saved as placed only after HTTP 200, code: 1 and a coupon in body.coupons.
  9. 501 shows the new odds; 503 says the outcome is temporarily unavailable.
  10. A timed-out place request is checked, not retried blindly.
  11. The callback signature is verified over the raw bytes.
  12. A repeated batchId changes nothing.
  13. Payouts use realWin or real_win, never potential_win.
  14. Coupon status 15 is handled: stake back, wait for the new result.
  15. Polling restores results after an hour of downtime.

When all 15 pass on the trial key, tell the manager which plan you’re starting with, swap the key in the configuration and don’t change anything else. The requests are the same.

The whole week on one page

DayWhat’s builtHow to check it
0Keys, base URLs, allowed IPsaccount returns your terms and your_ip
1Backend proxy with cache, list of matchesScores and odds on the page, one API request per interval
2Match page with all markets and sub-eventsSame markets and odds as the raw response, blocked ones disabled
3Live polling, backoff, prematch and live kept apartOdds move within seconds, loop stops when the match ends
4Bet slip, pointers, placement, rejection codesA single, an accumulator and a 501 on a live match
5Settlement callback and polling fallbackReplayed callback pays once; polling restores after downtime
6Cache, rate limits, secrets, logsOutgoing requests don’t grow with players
7Launch checklist, production keyAll 15 items pass

Seven mistakes that cost the most time

  • Calling the API from the browser or the app. The key is restricted to your server addresses and must stay there. The rewrite through a backend costs more than doing it on day 1.
  • Hard-coding sports, tournaments or market names. The line changes every hour. A tournament with no events disappears from menu, and a sport without matches disappears too.
  • One polling loop per player. Ten players, ten identical requests. The limit arrives on the first busy evening.
  • Polling event for every match in the list. You only need details for matches someone has open.
  • Requesting the API every second to update the timer. Count locally, resync on the next response.
  • Treating HTTP 200 as “bet accepted”. Check code and error_code too.
  • Retrying a timed-out bet. It may already exist. Look it up first.

What makes the week shorter

Most of the seven days go into reading and checking, not typing. These SportAPI tools cut that part:

  • The integration guide walks the same menu → events → event sequence with every field explained, and the quick integration guide for the Coupon API fits bet placement and settlement on one page.
  • Real JSON responses for every method are in the documentation, so you can build the front end before the key arrives.
  • The Python client installs with pip install sportapi and covers sync and async requests with typed models and a demo mode.
  • The OpenAPI specification with a Postman collection and a mock server lets you generate a client in any language.
  • Documentation written for AI coding agents, plus an MCP server for Claude, Cursor and VS Code. With an agent reading that documentation, our own team built the full cycle, odds, bets and settlement, in one day.

If there’s no developer at all, the same line and bet slip come as a ready sportsbook widget that you embed in a page: the week turns into an afternoon, at the cost of a fixed interface.

FAQ

Can one developer really do the whole integration?

Yes, if the plan is followed in order and the developer owns the backend. The feed and the Coupon API are plain HTTPS and JSON; the hard parts are discipline about intervals, IDs and idempotency, not the volume of code. A second developer helps mostly on the front end.

Do I have to use the Coupon API to accept bets?

No. Many projects take the odds feed only and run bets in their own system, or show odds without bets at all. In that case the plan ends after day 3 and day 6. The Coupon API is for teams that don’t want to build and maintain settlement.

Which programming language should I use?

Any language that sends HTTPS requests and parses JSON. The examples here are Node.js; the documentation has the same flow in cURL, Python, PHP and JavaScript, and there’s an official Python client.

Is there a WebSocket or push feed?

Not yet. WebSocket support is in development, so a production integration polls at the documented intervals. With caching on your side, polling serves thousands of players without touching the limit.

How do I move from another odds provider?

Run SportAPI in parallel on the trial key, map your sports and markets to group_id values from the feed, and switch the front end once the line matches. Bets placed with the old provider are settled there; new coupons go through the Coupon API.

What does the API cost once the week is over?

The odds feed is from $30 a month for one sport, prematch and live included. Bet placement and settlement through the Coupon API is from $300 a month. Prices are in the plans on the product pages; the manager confirms them before you switch keys.

Start day 1 today

The first screen with real matches is about 20 minutes away from the moment you have the key. Ask the SportAPI manager on Telegram for a test key, point the proxy from day 1 at your base URL and run the account request. Everything else in this plan builds on that first response.

← All articles