Integrate in an afternoon.

# 1. First poll: capture the ETag
ETAG=$(curl -sD - -o /dev/null --compressed \
  "https://api.oddsrelay.io/v2/odds/standard?region=uk" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  | awk -F': ' 'tolower($1)=="etag"{print $2}' | tr -d '\r')

# 2. Subsequent polls: send it back. Until the board rolls you get a
#    bodyless 304 Not Modified (fast + free), otherwise a fresh 200 + new ETag.
curl -s -o /dev/null -w "%{http_code}\n" --compressed \
  "https://api.oddsrelay.io/v2/odds/standard?region=uk" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "If-None-Match: $ETAG"

You are integrating the OddsRelay odds API. Follow this contract exactly.

BASE URL
  https://api.oddsrelay.io/v2

AUTH
  Send the key as a header, never in a query string:
    Authorization: Bearer <YOUR_API_KEY>
  (x-api-key: <YOUR_API_KEY> is equivalent.)
  Keys look like or_live_* (production) or or_test_* (14-day trial).
  Read the key from an environment variable. Never commit it, never ship it to a browser
  bundle: browser embeds need a separate origin-locked widget key.

THE CALL
  GET /v2/odds/standard?region=uk
  Query params:
    region      one region code, or a CSV like uk,ire (max 8). Your key's scope gates which.
    format      envelope (default) or bare. bare returns the data array alone and moves the
                metadata into X-Count / X-Processed-At / X-Stale-Hidden headers.
    oddsFormat  decimal (default) or american.
    dateFormat  iso (default) or unix.
  Feed types are the path segment: standard, 2up, bog, each-way, extra-place, dutching.

RESPONSE SHAPE (event-grouped; this is the part to model carefully)
  { "meta": { "feed_type", "region", "odds_format", "processed_at", "count",
              "stale_hidden", "unreliable_links", "version", "next_cursor" },
    "data": [ {
      "event_id":      "stable across polls and across every /v2 endpoint",
      "sport_key":     "soccer_premier_league",
      "sport_title":   "Premier League",
      "home_team":     "Arsenal",          // team sports
      "away_team":     "Chelsea",          // racing sends "venue" instead;
                                            // "event_name" is the fallback when neither splits
      "commence_time": "2030-07-08T14:00:00Z",
      "markets": [ {
        "key": "h2h",                      // also: totals, win, each_way, btts
        "outcomes": [ {
          "name":  "Arsenal",
          "point": 2.5,                    // present on totals only
          "back":  [ { "bookmaker": "sky_bet", "price": 2.10,
                       "link": "https://...", "last_update": "..." } ],
          "lay":   [ { "exchange": "smarkets", "price": 2.05, "available": 1840.0,
                       "link": "https://...", "last_update": "..." } ]
        } ]
      } ]
    } ] }

  Rules that matter:
  - back[] is sorted best (highest) price first; lay[] is sorted best (lowest) price first,
    deduped to one offer per exchange. Do not re-sort before pairing.
  - An outcome may legally have no lay offers (dutching feed types omit the lay key entirely),
    an empty back array, or neither. Every level can be empty. Walk defensively.
  - "link" is a deep link to that event at that bookmaker or exchange. It can be null.
  - each-way and extra-place replace lay[] with a { "win": [...], "place": [...] } pair, and
    their back offers add "places" and "place_fraction".
  - To build a matched-betting board, fan each outcome out to one row per (back offer x lay
    offer). Pairing only against the best lay hides real opportunities.

MONEY MATHS IS YOURS, NOT THE WIRE'S
  The response carries source facts only. There is no rating, profit, qualifying-loss or
  commission field, by design: commission is the viewer's own exchange account rate.
  Compute derived figures client-side, for example:
    rating        = (backOdds / layOdds) * 100          // 0% commission; >100 is an arb
    layStake      = (backOdds * backStake) / (layOdds - commission/100 * (layOdds - 1))
    liability     = layStake * (layOdds - 1)
  Let the user set their own commission per exchange; do not hardcode one.

POLLING
  Poll every 15 to 30 seconds. Store the ETag from each response and send it back as
  If-None-Match; a 304 means the board is unchanged and you should keep the rows you have.
  Always send Accept-Encoding: gzip — the full board is large.
  Every request counts against the rate limit, including a 304, so do not poll faster than
  the board changes. Read your budget from X-RateLimit-Remaining and X-RateLimit-Remaining-Hour.
  On 429, honour the Retry-After header.

ERRORS
  Every error is { "error": { "code", "message", "type"?, "request_id" } }.
    401  invalid_api_key / key_revoked / key_expired   -> stop and surface it; do not retry.
    403  type_not_in_scope / region_not_in_scope / raw_not_in_scope   -> a scope problem;
         "type" names the failing axis. Do not retry.
    404  unknown_region / unknown_sport                -> a bad request value.
    429  rate_limited                                  -> back off, honour Retry-After.
    500 / 503                                          -> transient; retry with backoff.
  Log request_id on failure; it identifies the request in support.

WHAT TO BUILD
  [Describe what you want here: for example "a matched-betting board sorted by rating, with a
  search box and a per-exchange commission setting", or "a service that pulls the board every
  20 seconds and stores the best back price per outcome".]

# Preferred: Bearer
Authorization: Bearer <YOUR_API_KEY>

# Equivalent: x-api-key header
x-api-key: <YOUR_API_KEY>

# NEVER in a query string (keys leak into logs). This is rejected:
# https://api.oddsrelay.io/v2/odds/standard?api_key=...   ✗

{
  "meta": {
    "feed_type": "sports",
    "region": "uk",
    "odds_format": "decimal",
    "processed_at": "2026-08-15T12:03:12.000Z",
    "count": 2,
    "version": "v2",
    "next_cursor": null
  },
  "data": [
    {
      "key": "soccer_intl_friendly",
      "group": "Soccer",
      "title": "Intl Friendly",
      "description": "Intl Friendly (Soccer)",
      "active": true,
      "has_outrights": false,
      "regions": [
        "ire",
        "uk"
      ]
    },
    {
      "key": "soccer_premier_league",
      "group": "Soccer",
      "title": "Premier League",
      "description": "Premier League (Soccer)",
      "active": true,
      "has_outrights": false,
      "regions": [
        "ire",
        "uk"
      ]
    }
  ]
}

{
  "meta": {
    "feed_type": "events",
    "region": "uk",
    "odds_format": "decimal",
    "processed_at": "2026-08-15T12:03:12.000Z",
    "count": 3,
    "version": "v2",
    "next_cursor": null
  },
  "data": [
    {
      "id": "or_evt_2a7a8855d318",
      "sport_key": "soccer_premier_league",
      "sport_title": "Premier League",
      "commence_time": "2026-08-15T14:00:00Z",
      "home_team": "Arsenal",
      "away_team": "Chelsea",
      "status": "upcoming",
      "has_coverage": [
        "standard"
      ]
    },
    {
      "id": "or_evt_d584fd3d39ef",
      "sport_key": "soccer_premier_league",
      "sport_title": "Premier League",
      "commence_time": "2026-08-15T15:00:00Z",
      "home_team": "Spurs",
      "away_team": "Everton",
      "status": "upcoming",
      "has_coverage": [
        "standard"
      ]
    },
    {
      "id": "or_evt_7b52c2b9681b",
      "sport_key": "soccer_intl_friendly",
      "sport_title": "Intl Friendly",
      "commence_time": "2026-08-15T18:00:00Z",
      "home_team": "Spain",
      "away_team": "Brazil",
      "status": "upcoming",
      "has_coverage": [
        "dutching"
      ]
    }
  ]
}

{
  "meta": {
    "feed_type": "bookmakers",
    "count": 67,
    "version": "v2"
  },
  "data": [
    {
      "key": "betfair_exchange",
      "name": "Betfair Exchange",
      "regions": [
        "ire",
        "uk"
      ],
      "is_exchange": true
    },
    {
      "key": "sky_bet",
      "name": "Sky Bet",
      "regions": [
        "ire",
        "uk"
      ],
      "is_exchange": false
    }
  ]
}

{
  "meta": {
    "feed_type": "raw",
    "region": "uk",
    "odds_format": "decimal",
    "processed_at": "2026-08-15T12:03:12.000Z",
    "count": 1,
    "version": "v2",
    "next_cursor": null
  },
  "data": [
    {
      "id": "or_evt_2a7a8855d318",
      "sport_key": "soccer_premier_league",
      "sport_title": "Premier League",
      "commence_time": "2026-08-15T14:00:00Z",
      "home_team": "Arsenal",
      "away_team": "Chelsea",
      "bookmakers": [
        {
          "key": "bet365",
          "title": "bet365",
          "region": "uk",
          "last_update": "2026-08-15T12:03:11Z",
          "markets": [
            {
              "key": "h2h",
              "last_update": "2026-08-15T12:03:11Z",
              "outcomes": [
                {
                  "name": "Arsenal",
                  "price": 2.1
                },
                {
                  "name": "Chelsea",
                  "price": 3.6
                },
                {
                  "name": "Draw",
                  "price": 3.4
                }
              ]
            }
          ]
        },
        {
          "key": "betfair_exchange",
          "title": "Betfair Exchange",
          "region": "uk",
          "last_update": "2026-08-15T12:03:09Z",
          "markets": [
            {
              "key": "h2h_lay",
              "last_update": "2026-08-15T12:03:09Z",
              "outcomes": [
                {
                  "name": "Arsenal",
                  "back_price": 2.1,
                  "lay_price": 2.12,
                  "available": 1450
                }
              ]
            }
          ],
          "currency": "GBP"
        }
      ]
    }
  ]
}

{
  "id": "or_evt_2a7a8855d318",
  "sport_key": "soccer_premier_league",
  "sport_title": "Premier League",
  "commence_time": "2026-08-15T14:00:00Z",
  "home_team": "Arsenal",
  "away_team": "Chelsea",
  "bookmakers": [
    {
      "key": "bet365",
      "title": "bet365",
      "region": "uk",
      "last_update": "2026-08-15T12:03:11Z",
      "markets": [
        {
          "key": "h2h",
          "last_update": "2026-08-15T12:03:11Z",
          "outcomes": [
            {
              "name": "Arsenal",
              "price": 2.1
            },
            {
              "name": "Chelsea",
              "price": 3.6
            },
            {
              "name": "Draw",
              "price": 3.4
            }
          ]
        }
      ]
    },
    {
      "key": "betfair_exchange",
      "title": "Betfair Exchange",
      "region": "uk",
      "last_update": "2026-08-15T12:03:09Z",
      "markets": [
        {
          "key": "h2h_lay",
          "last_update": "2026-08-15T12:03:09Z",
          "outcomes": [
            {
              "name": "Arsenal",
              "back_price": 2.1,
              "lay_price": 2.12,
              "available": 1450
            }
          ]
        }
      ],
      "currency": "GBP"
    }
  ]
}

{
  "meta": {
    "feed_type": "standard",
    "region": "uk",
    "odds_format": "decimal",
    "processed_at": "2026-07-08T12:34:56.123Z",
    "count": 412,
    "stale_hidden": false,
    "unreliable_links": [],
    "version": "v2",
    "next_cursor": null
  },
  "data": [
    {
      "event_id": "or_evt_8092b51efde0",
      "sport_key": "soccer_premier_league",
      "sport_title": "Premier League",
      "commence_time": "2026-07-08T14:00:00Z",
      "home_team": "Arsenal",
      "away_team": "Chelsea",
      "markets": [
        {
          "key": "h2h",
          "outcomes": [
            {
              "name": "Arsenal",
              "back": [
                {
                  "bookmaker": "888sport",
                  "price": 2.1,
                  "link": null,
                  "last_update": "2026-07-08T12:34:48Z"
                }
              ],
              "lay": [
                {
                  "exchange": "smarkets",
                  "price": 2.05,
                  "available": 1840,
                  "link": null,
                  "last_update": "2026-07-08T12:34:48Z"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

{
  "error": {
    "code": "region_not_in_scope",
    "message": "Key not scoped for region 'sa'.",
    "type": "region",
    "request_id": "or_req_…"
  }
}

X-RateLimit-Limit:            <your per-minute cap>
X-RateLimit-Remaining:        <left this minute>
X-RateLimit-Limit-Hour:       <your per-hour cap>
X-RateLimit-Remaining-Hour:   <left this hour>
# on 429:
Retry-After:                  <seconds>

<div data-or-widget="oddsmatcher"
     data-or-region="uk"
     data-or-key="or_live_YOUR_WIDGET_KEY"></div>
<script src="https://oddsrelay.io/widgets/v1/oddsrelay-widgets.js" crossorigin="anonymous" async></script>