canonical: https://jentic.com/apis/oddsrelay.io/oddsrelay

# OddsRelay API

The OddsRelay API serves sports betting odds that line up bookmaker back prices against exchange lay prices for each event, across six matched boards: standard, 2up, dutching, each-way, extra-place, and bog. It also returns a raw board of every venue's prices per event, paged by cursor, with optional liquidity and deep links, plus a single-event lookup by id. Discovery routes list sports and competitions, events, bookmakers and exchanges, and the regions a key covers, while usage, pricing, health, and coverage routes report token balance, the price table, and board freshness.

## For AI agents

Read matched betting boards that pair bookmaker back prices with exchange lay prices, pull raw per-event odds from every venue, and check token cost, coverage, and board freshness before calling.

## Scope

Does not place bets, hold betting accounts, or move funds at any bookmaker or exchange. Use for reading matched and raw sports betting odds only.

## Capabilities

- Fetch a matched board such as 2up, each-way, extra-place, or dutching, filtered by sports, bookmakers, exchanges, markets, and kick-off window
- Page the raw board of every venue's prices per event, with updatedSince for incremental pulls and includeLiquidity for exchange depth
- Look up one event by its or_evt_ id and read every venue's prices for it
- Discover the sports, competitions, events, bookmakers, exchanges, and regions a key can query
- Price any data request for free with quote=true before spending tokens, and read the full price table
- Check board freshness, odds age, and per-venue coverage before relying on the prices

## Use cases

### Matched-betting research agent

A matched bettor's agent compares each bookmaker's back price against the exchange lay price for upcoming events and surfaces the closest matches. Through Jentic the agent searches for 'get a matched betting board', loads the OddsRelay getMatchedBoard operation, and calls it with the board type and filters such as sports and bookmakers, with the key attached at call time. The agent returns the events where back and lay prices sit closest without the developer wiring the API by hand.

Example prompt: Call GET `/v2/odds/standard` with region 'uk', sports 'soccer', and markets 'h2h', then rank events by the gap between bookmaker back price and exchange lay price

### Each-way and extra-place offers

Horse racing offers like extra places and each-way terms need the bookmaker's terms read against both win and place lays on the exchange. OddsRelay serves dedicated each-way and extra-place boards that carry those terms beside the lays, so a tool can rank races where an each-way bet is close to break-even before the race starts.

Example prompt: Call GET `/v2/odds/extra-place` with region 'uk' and sports 'horse_racing', and list races in the next three hours where the bookmaker pays an extra place

### Incremental raw odds ingestion

A data pipeline keeps a local odds store current without re-downloading the whole board. It pages GET `/v2/odds/raw` with a cursor and limit, and on later runs passes updatedSince so only changed events come back. The raw board names bookmakers with a single price and exchanges with back price, lay price, and available liquidity when includeLiquidity is set.

Example prompt: Page GET `/v2/odds/raw` with region 'uk', rawSports 'tennis', and includeLiquidity true using the cursor until it is exhausted, then store each event keyed by its id

### Cost-aware polling

Every OddsRelay data call is priced from the request, not the size of the reply, and spends from one monthly token pool. An agent can send quote=true on any data request to get its cost and remaining balance for free, read GET `/v2/pricing` for the table, and check GET `/v2/usage` for the balance and account scope, then decide how often it can afford to poll.

Example prompt: Call GET `/v2/odds/raw` with quote true for the planned filters, compare the returned cost against remaining from GET `/v2/usage`, and pick a polling interval that fits the balance

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v2/odds/{type}` | Get a matched board |
| GET | `/v2/odds/raw` | Page the raw board |
| GET | `/v2/odds/event/{id}` | Get one raw event by id |
| GET | `/v2/events` | List events of a sport |
| GET | `/v2/sports` | List sports and competitions |
| GET | `/v2/bookmakers` | List bookmakers and exchanges |
| GET | `/v2/usage` | Read plan, balance, and scope |
| GET | `/v2/health` | Check board freshness |

## Key resources

- **Matched boards** — Six board types pairing bookmaker back prices with exchange lay prices per event, filterable by sport, venue, market, and kick-off time
- **Raw board and events** — Every venue's prices per event, paged by cursor, plus a single-event lookup by id
- **Discovery** — Sports and competitions, events per sport, bookmakers and exchanges, and the regions a key covers
- **Account and service status** — Token usage and scope, the price table, coverage per venue and sport, product status, and board freshness

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 69 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 77 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 61 / 100
  - Agent Usability: 94 / 100
  - Security: 55 / 100
  - AI Discoverability: 60 / 100
- **View full report:** https://jentic.com/apis/oddsrelay.io/oddsrelay/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring OddsRelay by hand means choosing between bearer and x-api-key auth, sending gzip for the raw board, tracking a monthly token pool, and respecting a per-account flood cap. Through Jentic you install once, import OddsRelay from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** OddsRelay puts the board type in the URL path (`/v2/odds/{type}`), so a rule can pin your agent to one board such as each-way and the other operations you pick. Every route is a GET, so the choice is about which data the agent spends tokens on, not about writes.
- **Credential handling:** Your OddsRelay key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get a matched betting board' or 'list bookmakers', and Jentic returns the matching OddsRelay operation with its input schema, including the board type and filter parameters, so the agent calls the right route directly.

## Related APIs

- **The Odds API** — Bookmaker odds across many sports and regions without exchange lay matching
- **Odds-API.io** — Real-time sports betting odds from many bookmakers
- **Betfair Exchange Streaming API** — Direct exchange market data from Betfair

## FAQ

### What authentication does the OddsRelay API use?

Per its OpenAPI spec, the OddsRelay API takes the same key either as a bearer token in the Authorization header or in the x-api-key header, never in the query string. Server keys start with or_live_. A few routes are keyless: /healthz, `/v2/status`, `/v2/openapi.json`, and `/v2/coverage` when no key header is sent. Through Jentic the key is stored by your own instance and attached at call time, so the agent never handles it.

### Which matched boards can I fetch with the OddsRelay API?

GET `/v2/odds/{type}` serves six boards: standard, 2up, dutching, each-way, extra-place, and bog, and also accepts the aliases two-up, each_way, and extra_place. Each board can be filtered by sports, bookmakers, exchanges, markets, and a kick-off window with commenceTimeFrom and commenceTimeTo. The standard and dutching boards serve decimal odds only.

### What are the rate limits for the OddsRelay API?

The spec describes a flood cap per account over a short window and per minute, plus a cap on requests in flight. Replies to a valid key carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, and going over returns too_many_requests with a Retry-After header. Spending is separate: calls draw from a monthly token pool shown by GET `/v2/usage.`

### Is there an OddsRelay MCP server?

You don't need an MCP server to give your agent OddsRelay. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the board and discovery operations on demand without another server's tool definitions sitting in its context.

### How do I pull the each-way board through Jentic?

Search Jentic for 'get a matched betting board', load the getMatchedBoard operation, and execute it with type set to each-way plus a region and sports filter such as horse_racing. Jentic attaches your key and returns the board. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I check what a request costs before spending tokens?

Yes. Add quote=true to any data request and OddsRelay returns its cost, your remaining balance, and the rate card without serving the data, and the quote itself is free. GET `/v2/pricing` publishes the full price table, and discovery routes, usage, pricing, and every refusal are free.

### Can I limit what my agent is allowed to do with the OddsRelay API?

Yes. Write a rule that allows only GET `/v2/odds/each-way` and GET `/v2/usage`, and the agent can read the each-way board and check its balance but cannot page the raw board or other board types, and every call it makes is logged.